Add archive event block endpoint

web3blind · web3blind · commit 4af08987c595 · 2026-06-20T16:26:43.000Z
diff --git a/app/js/blockchain/history-source.js b/app/js/blockchain/history-source.js
@@ -34,6 +34,44 @@ var HistorySource = (function() {
         return pattern.replace(/\/$/, '') + '/' + encodeURIComponent(String(blockNum)) + '.json';
     }
 
+    function _eventsUrl(mirror, blockNum) {
+        var pattern = mirror.eventsUrl || mirror.blockEventsUrl || '';
+        if (!pattern && mirror.apiBase) {
+            pattern = String(mirror.apiBase).replace(/\/$/, '') + '/v1/events/block/{block}.json';
+        }
+        if (!pattern) return '';
+        if (pattern.indexOf('{block}') !== -1) {
+            return pattern.replace('{block}', encodeURIComponent(String(blockNum)));
+        }
+        return pattern.replace(/\/$/, '') + '/' + encodeURIComponent(String(blockNum)) + '.json';
+    }
+
+    function _eventsPayloadToThinBlock(payload) {
+        if (!payload || !payload.events) return null;
+        var events = payload.events || [];
+        var block = {
+            previous: payload.previous || '',
+            timestamp: payload.timestamp || '',
+            block_id: payload.block_id || payload.blockId || '',
+            transactions: []
+        };
+        var byTx = {};
+        for (var i = 0; i < events.length; i++) {
+            var ev = events[i] || {};
+            var txIndex = ev.txIndex || ev.tx_index || 0;
+            if (!byTx[txIndex]) {
+                byTx[txIndex] = { operations: [] };
+                block.transactions.push(byTx[txIndex]);
+            }
+            if (ev.opType === 'custom' || ev.op_type === 'custom') {
+                byTx[txIndex].operations.push(['custom', ev.raw || {}]);
+            } else if (ev.opType === 'award' || ev.op_type === 'award') {
+                byTx[txIndex].operations.push(['award', ev.raw || {}]);
+            }
+        }
+        return block;
+    }
+
     function _extractBlockFromMirrorPayload(payload) {
         if (!payload) return null;
         if (payload.previous && payload.timestamp && payload.transactions) return payload;
@@ -82,6 +120,28 @@ var HistorySource = (function() {
         }
     }
 
+    function _getBlockEventsFromMirrors(blockNum, index, callback) {
+        var mirrors = _archiveMirrors();
+        if (!mirrors.length || index >= mirrors.length) {
+            callback(_makeError('Block events unavailable from archive mirrors'));
+            return;
+        }
+        var mirror = _normalizeMirror(mirrors[index]);
+        var eventsUrl = _eventsUrl(mirror, blockNum);
+        if (!eventsUrl) {
+            _getBlockEventsFromMirrors(blockNum, index + 1, callback);
+            return;
+        }
+        _requestJson(eventsUrl, mirror.timeoutMs || 6000, function(err, payload) {
+            var block = err ? null : _eventsPayloadToThinBlock(payload);
+            if (block) {
+                callback(null, block);
+                return;
+            }
+            _getBlockEventsFromMirrors(blockNum, index + 1, callback);
+        });
+    }
+
     function _getBlockFromMirrors(blockNum, index, callback) {
         var mirrors = _archiveMirrors();
         if (!mirrors.length || index >= mirrors.length) {
@@ -111,15 +171,27 @@ var HistorySource = (function() {
             return;
         }
         if (typeof viz === 'undefined' || !viz.api || !viz.api.getBlock) {
-            _getBlockFromMirrors(blockNum, 0, callback);
+            _getBlockEventsFromMirrors(blockNum, 0, function(eventsErr, eventsBlock) {
+                if (!eventsErr && eventsBlock) {
+                    callback(null, eventsBlock);
+                    return;
+                }
+                _getBlockFromMirrors(blockNum, 0, callback);
+            });
             return;
         }
         viz.api.getBlock(blockNum, function(err, block) {
             if (!err && block) {
                 callback(null, block);
                 return;
             }
-            _getBlockFromMirrors(blockNum, 0, callback);
+            _getBlockEventsFromMirrors(blockNum, 0, function(eventsErr, eventsBlock) {
+                if (!eventsErr && eventsBlock) {
+                    callback(null, eventsBlock);
+                    return;
+                }
+                _getBlockFromMirrors(blockNum, 0, callback);
+            });
         });
     }
 
diff --git a/app/js/config.js b/app/js/config.js
@@ -20,6 +20,8 @@ var VizMagicConfig = (function() {
     var HISTORY_ARCHIVE_MIRRORS = [
         {
             url: 'https://vizmagic.web3blind.xyz/archive-mirror/v1/block/{block}.json',
+            eventsUrl: 'https://vizmagic.web3blind.xyz/archive-mirror/v1/events/block/{block}.json',
+            apiBase: 'https://vizmagic.web3blind.xyz/archive-mirror',
             timeoutMs: 8000
         }
     ];
diff --git a/app/sw.js b/app/sw.js
@@ -1,5 +1,5 @@
 // Viz Magic — Service Worker
-var CACHE_NAME = 'viz-magic-v9';
+var CACHE_NAME = 'viz-magic-v10';
 var ASSETS = [
     '/',
     '/index.html',
@@ -14,6 +14,7 @@ var ASSETS = [
     '/js/utils/crypto.js',
     '/js/utils/a11y.js',
     '/js/blockchain/connection.js',
+    '/js/blockchain/history-source.js',
     '/js/blockchain/account.js',
     '/js/blockchain/broadcast.js',
     '/js/blockchain/invite.js',
diff --git a/tests/history-source-regressions.test.js b/tests/history-source-regressions.test.js
@@ -45,7 +45,8 @@ test('history source wraps VIZ block/account access', function () {
   assert.ok(/var HistorySource/.test(historySourceJs), 'HistorySource module missing');
   assert.ok(/function getBlock\(blockNum, callback\)/.test(historySourceJs), 'getBlock API missing');
   assert.ok(/viz\.api\.getBlock/.test(historySourceJs), 'getBlock should use live VIZ RPC as first implementation');
-  assert.ok(/_getBlockFromMirrors\(blockNum, 0, callback\)/.test(historySourceJs), 'getBlock should fall back to archive mirrors');
+  assert.ok(/_getBlockEventsFromMirrors\(blockNum, 0/.test(historySourceJs), 'getBlock should try archive event blocks before block payload mirrors');
+  assert.ok(/_getBlockFromMirrors\(blockNum, 0, callback\)|_getBlockFromMirrors\(blockNum, 0, function/.test(historySourceJs), 'getBlock should fall back to archive block mirrors');
   assert.ok(/XMLHttpRequest/.test(historySourceJs), 'mirror fallback should use browser-safe XHR');
   assert.ok(/function getAccountProtocol\(account, protocol, callback\)/.test(historySourceJs), 'account protocol API missing');
   assert.ok(/getCapabilities/.test(historySourceJs), 'capabilities API missing');
@@ -54,6 +55,7 @@ test('history source wraps VIZ block/account access', function () {
 test('archive mirror config is explicit and points at production nginx path', function () {
   assert.ok(/HISTORY_ARCHIVE_MIRRORS/.test(configJs), 'archive mirror config missing');
   assert.ok(/vizmagic\.web3blind\.xyz\/archive-mirror\/v1\/block\/\{block\}\.json/.test(configJs), 'production archive mirror URL missing');
+  assert.ok(/vizmagic\.web3blind\.xyz\/archive-mirror\/v1\/events\/block\/\{block\}\.json/.test(configJs), 'production archive event URL missing');
   assert.ok(/timeoutMs:\s*8000/.test(configJs), 'mirror timeout should be explicit');
   assert.ok(/\{block\}/.test(configJs), 'mirror URL pattern should document block placeholder');
 });
diff --git a/tools/archive-node/README.md b/tools/archive-node/README.md
@@ -7,12 +7,12 @@ It indexes public VIZ blocks, extracts only game-relevant operations, and serves
 ## What it stores
 
 - block number, `block_id`, `previous`, timestamp, source node;
-- raw block JSON for indexed blocks;
+- thinned block JSON for indexed blocks (only operations that became game events; no full raw block storage);
 - normalized public events for:
   - `custom` protocol `VM`;
   - `custom` protocol `V`;
   - `custom` protocol `VE`;
-  - `award` operations used for blessings/rewards.
+  - game-marked `award` operations (`memo` starts with `viz://vm/`).
 
 The implementation stores data in SQLite (`data/archive-node/archive.sqlite`) using Node 22's built-in `node:sqlite` module. `sqlite-schema.sql` documents the live schema.
 
@@ -43,6 +43,7 @@ node daemon.js
 GET /health
 GET /v1/status
 GET /v1/block/:blockNum.json
+GET /v1/events/block/:blockNum.json
 GET /v1/range?start=123&end=456&protocol=VM,V,VE&limit=500
 GET /v1/account/:account/protocol/:protocol/actions?limit=500
 GET /v1/account/:account/protocol/:protocol/latest
@@ -54,6 +55,7 @@ When hosted behind Nginx at `/archive-mirror`, the same API is available under t
 GET /archive-mirror/health
 GET /archive-mirror/v1/status
 GET /archive-mirror/v1/block/123.json
+GET /archive-mirror/v1/events/block/123.json
 ```
 
 ## Config
diff --git a/tools/archive-node/archive-node.test.js b/tools/archive-node/archive-node.test.js
@@ -137,6 +137,13 @@ async function run() {
             assert.strictEqual(range.status, 200);
             assert.strictEqual(range.body.count, 3);
 
+            var blockEvents = await getJson(port, '/archive-mirror/v1/events/block/123.json');
+            assert.strictEqual(blockEvents.status, 200);
+            assert.strictEqual(blockEvents.body.blockNum, 123);
+            assert.strictEqual(blockEvents.body.count, 3);
+            assert.strictEqual(blockEvents.body.events[0].protocol, 'VM');
+            assert.strictEqual(blockEvents.body.events[2].payload.memo, 'viz://vm/bless/target-mage');
+
             var account = await getJson(port, '/archive-mirror/v1/account/' + ACCOUNT + '/protocol/VM/actions');
             assert.strictEqual(account.status, 200);
             assert.strictEqual(account.body.count, 1);
diff --git a/tools/archive-node/public-mirror.example.json b/tools/archive-node/public-mirror.example.json
@@ -1,6 +1,7 @@
 {
   "name": "Viz Magic Community Archive",
   "url": "https://vizmagic.web3blind.xyz/archive-mirror/v1/block/{block}.json",
+  "eventsUrl": "https://vizmagic.web3blind.xyz/archive-mirror/v1/events/block/{block}.json",
   "apiBase": "https://vizmagic.web3blind.xyz/archive-mirror",
   "readOnly": true,
   "protocols": ["VM", "V", "VE", "award"]
diff --git a/tools/archive-node/server.js b/tools/archive-node/server.js
@@ -104,6 +104,37 @@ function createServer(options) {
             return;
         }
 
+        if (parts.length === 4 && parts[0] === 'v1' && parts[1] === 'events' && parts[2] === 'block') {
+            var eventBlockRaw = parts[3].replace(/\.json$/, '');
+            var eventBlockNum = safeNum(eventBlockRaw, 0);
+            if (!eventBlockNum || eventBlockNum <= 0) {
+                json(res, 400, { error: 'invalid_block' });
+                return;
+            }
+            var eventBlockRecord = archive.getBlockRecord(eventBlockNum);
+            if (!eventBlockRecord) {
+                json(res, 404, { error: 'block_not_indexed', blockNum: eventBlockNum }, { 'Cache-Control': 'no-store' });
+                return;
+            }
+            var blockEvents = archive.queryEvents({
+                start: eventBlockNum,
+                end: eventBlockNum,
+                limit: 5000
+            });
+            json(res, 200, {
+                blockNum: eventBlockRecord.blockNum,
+                block_id: eventBlockRecord.block_id,
+                previous: eventBlockRecord.previous,
+                timestamp: eventBlockRecord.timestamp,
+                eventCount: eventBlockRecord.eventCount || blockEvents.length,
+                sourceNode: eventBlockRecord.sourceNode || '',
+                indexedAt: eventBlockRecord.indexedAt,
+                events: blockEvents,
+                count: blockEvents.length
+            });
+            return;
+        }
+
         if (parts.length === 2 && parts[0] === 'v1' && parts[1] === 'range') {
             var protocols = parsedUrl.query.protocol ? String(parsedUrl.query.protocol).split(',').map(function(x) { return x.trim(); }).filter(Boolean) : null;
             var events = archive.queryEvents({

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,8 @@ var VizMagicConfig = (function() {`
`20`	`20`	`var HISTORY_ARCHIVE_MIRRORS = [`
`21`	`21`	`{`
`22`	`22`	`url: 'https://vizmagic.web3blind.xyz/archive-mirror/v1/block/{block}.json',`
	`23`	`+ eventsUrl: 'https://vizmagic.web3blind.xyz/archive-mirror/v1/events/block/{block}.json',`
	`24`	`+ apiBase: 'https://vizmagic.web3blind.xyz/archive-mirror',`
`23`	`25`	`timeoutMs: 8000`
`24`	`26`	`}`
`25`	`27`	`];`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "Viz Magic Community Archive",`
`3`	`3`	`"url": "https://vizmagic.web3blind.xyz/archive-mirror/v1/block/{block}.json",`
	`4`	`+ "eventsUrl": "https://vizmagic.web3blind.xyz/archive-mirror/v1/events/block/{block}.json",`
`4`	`5`	`"apiBase": "https://vizmagic.web3blind.xyz/archive-mirror",`
`5`	`6`	`"readOnly": true,`
`6`	`7`	`"protocols": ["VM", "V", "VE", "award"]`