Release v0.23.0

.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "attribution": false,
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "git config user.name 'J-Dog' && git config user.email 'j-dog@j-dog.net' || true",
+            "timeout": 10,
+            "statusMessage": "Setting the repo git identity"
+          }
+        ]
+      }
+    ]
+  }
+}

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-10-11
+
+### Added
+- Added dispenser address collapse, purge grace and expiration extension undo, each behind an activation.
+- Enforced newest-first protocol time windows and the protocol time history bound.
+
+### Changed
+- Required unsigned BIGINT transaction id columns and asserted them at startup.
+- Pinned the BIGINT migration checksum rebaseline so the widened ids migration heals in place.
+
+### Fixed
+- Preserved stale mempool read metadata and kept a known reorg halt on a database ping failure.
+- Validated block hashes from the node and carried JSON-RPC error codes on HTTP 200 errors.
+
 ## [0.21.0] - 2026-09-29
 
 ### Added

CONTRIBUTING.md

@@ -125,6 +125,7 @@ CI runs the no-external-services gate, the docker tiers, the cross-repo drift gu
 2. Update `CHANGELOG.md` with a terse entry for your change.
 3. Make sure `git status` is clean apart from intended changes (no `node_modules/`, no editor leftovers, no `.env`).
 4. Open the PR with a clear title and a description of what changed and why.
+5. Agree to the Contributor License Agreement when the CLA Assistant bot links it on your first PR. Its `license/cla` check must pass before merge, so a PR from a contributor who has not signed cannot be merged. One signature covers every XChain Platform repository.
 
 For non-security bugs, open an issue at <https://github.com/XChain-Platform/xchain-decoder/issues/new>. For security bugs, see [`SECURITY.md`](./SECURITY.md).
 

Dockerfile

@@ -1,11 +1,14 @@
-FROM node:25.9.0
-
-RUN mkdir /XChainDecoder/
+FROM node:22-alpine@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402 AS dependencies
+WORKDIR /XChainDecoder
 COPY ./package.json /XChainDecoder/package.json
 COPY ./package-lock.json /XChainDecoder/package-lock.json
-WORKDIR /XChainDecoder
 RUN npm ci --omit=dev
 
+FROM node:25.9.0@sha256:78839ac448c23517f8eab2e8f7943d9b4f73979eb7f8bed2c73dbf72ff869e7b AS decoder
+WORKDIR /XChainDecoder
+COPY ./package.json /XChainDecoder/package.json
+COPY ./package-lock.json /XChainDecoder/package-lock.json
+COPY --from=dependencies /XChainDecoder/node_modules /XChainDecoder/node_modules
 COPY ./src /XChainDecoder/src
 # Patch bitcoinjs-lib's bufferutils with a BigInt-aware 64-bit reader. The stock
 # readUInt64 throws "RangeError: value out of range" for output values above
@@ -24,4 +27,4 @@ COPY ./src/chain/bufferutils.js /XChainDecoder/node_modules/bitcoinjs-lib/src/bu
 # xchain-encoder/Dockerfile). This image registers real drain work on SIGTERM
 # (src/api.js: flip decoderRunning, then decoder.stop()), which only runs when
 # node is PID 1 and receives the signal itself.
-CMD ["node", "./src/api.js"]
+CMD ["node", "./src/api.js"]

NOTICE.md

@@ -21,8 +21,10 @@ For commercial licensing, contact **legal@dankest.llc**.
 
 ## Attribution
 
-Any redistribution or modification of this software must retain the following
-attribution, per the AGPL and the project's trademark policy:
+As an additional term under section 7(b) of the GNU Affero General Public
+License v3.0, any redistribution or modification of this software must preserve
+the following author attribution in its source and in the Appropriate Legal
+Notices displayed by any work containing it:
 
 > Based on XChain Platform by Dankest, LLC - https://dankest.llc
 

README.md

@@ -29,7 +29,7 @@ Transaction extraction service for the XChain Platform. Polls the coin nodes of
 - **ACTION validation**: 34-name allowlist plus 5 short-form aliases (e.g. TRANSFER -> SEND) expanded before database writes
 - **Parse-failure quarantine**: tx-level decode failures retry up to 3 times, then are quarantined as PARSE_ERROR events rather than halting the block
 - **Source pubkey capture**: records the source address pubkey per transaction in a dedicated table for downstream use by the indexer
-- **Native-coin fee tracking**: when FEE_DESTINATION is set, outputs paying that address are persisted to transaction_outputs for indexer fee validation
+- **Native-coin fee tracking**: outputs paying the coin registry's FEE_DESTINATION are persisted to transaction_outputs for indexer fee validation; on regtest only, `XCHAIN_FEE_DESTINATION_<COIN>_REGTEST` redirects it for the decoder and indexer alike, and a bare `FEE_DESTINATION` env is ignored with a warning
 - **Graceful shutdown**: SIGTERM/SIGINT handlers complete in-flight work
 - **Node RPC failover**: rotates through `NODE_URL_FALLBACK` endpoints after `NODE_FAILOVER_THRESHOLD` consecutive connection failures, round-robin, so a recovered primary is retried again if the fallback also dies
 - **1300+ tests**: unit, integration, e2e, security, fuzz, chaos, mutation, regression, benchmarks, smoke

bin/ci-full.sh

@@ -89,6 +89,7 @@ ci_tier_deferred() {
 # >>> ci-tier timer (generated block; re-run the tier wirer to update) >>>
 run_tier() {
   ci_tier_deferred "$1" && return 0  # ci-tier guard (generated)
+  if [ "${CI_TIER:-full}" = "fast" ] && [ -n "${FAILED:-}" ]; then echo; echo "ci:full ===== $1 NOT RUN (a push stops at its first red tier, its verdict already red; the full sweep runs it) ====="; return 0; fi  # ci-tier stop (generated)
   local name="$1"; shift
   local __ci_tier_t0=$SECONDS
   echo; echo "ci:full ===== $name ====="

bin/lib/migration_residue_pin.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/*********************************************************************
+ *
+ * Copyright © 2025–2026 Dankest, LLC
+ * Based on XChain Platform by Dankest, LLC – https://dankest.llc
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This file is part of XChain Platform. Licensed under the GNU Affero
+ * General Public License v3.0 or later; see LICENSE.md. A commercial
+ * license (without AGPL source-disclosure terms) is available -
+ * contact legal@dankest.llc.
+ *
+ **********************************************************************
+ *
+ * The migration immutability pin: two sha256 values per committed migration in
+ * test/fixtures/migration-executable-residue.json, so an in-place edit to an
+ * applied file fails in CI instead of surfacing on a fleet as `content CHANGED`.
+ * Ported from the indexer's pin of the same name; the decoder's runner hashes
+ * migrations the same way (whole-file sha256 in schema_migrations).
+ *
+ *   residue  the file with every `--` line and blank line dropped (the basis the
+ *            MIGRATION_CHECKSUM_REBASELINES entries are verified on). A change
+ *            here is an executable edit and always fails.
+ *   sha256   the whole file, exactly what schema_migrations records. A change here
+ *            passes only when a reviewed rebaseline heals the pinned hash to the
+ *            current one, since that is the only case a deployed DB survives.
+ *
+ * A file the pin does not hold yet passes when its name sorts after the newest pinned
+ * migration, so a new migration needs no fixture edit; `--add` pins it. A file that
+ * sorts before the newest pinned migration fails because it was missed or backdated.
+ * An existing entry moves only through `--accept <file>`, which is legitimate solely
+ * for a file no database has applied.
+ *
+ * USAGE (from the repo root)
+ *   node bin/lib/migration_residue_pin.js              check; exit 1 on a violation
+ *   node bin/lib/migration_residue_pin.js --add        pin every unpinned file
+ *   node bin/lib/migration_residue_pin.js --accept <file> [--accept <file>]
+ *
+ ********************************************************************/
+
+'use strict';
+
+const crypto = require('crypto');
+const fs     = require('fs');
+const path   = require('path');
+
+// Loads the rebaseline table only; requiring src/db opens no connection and reads no env.
+const { MIGRATION_CHECKSUM_REBASELINES } = require('../../src/db');
+
+const ROOT    = path.join(__dirname, '..', '..');
+const MIG_DIR = path.join(ROOT, 'src', 'sql', 'migrations');
+const FIXTURE = path.join(ROOT, 'test', 'fixtures', 'migration-executable-residue.json');
+
+const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+function executableResidue(raw){
+    return String(raw).split('\n').filter((l) => !/^\s*--/.test(l) && l.trim() !== '').join('\n');
+}
+
+function pinOf(raw){
+    return { residue: sha256(executableResidue(raw)), sha256: sha256(raw) };
+}
+
+// Every violation of the pin over `files` (name -> raw text), as { file, kind, message }.
+function findViolations({ files, fixture, rebaselines }){
+    const out = [];
+    const newest = Object.keys(fixture).sort().pop() || '';
+    for(const file of Object.keys(files).filter((f) => !Object.hasOwn(fixture, f) && f < newest).sort()){
+        out.push({ file, kind: 'unpinned', message: file + ' sorts before the newest pinned migration ' + newest +
+            ' but is not pinned: run node bin/lib/migration_residue_pin.js --add and commit the fixture.' });
+    }
+    for(const file of Object.keys(fixture).sort()){
+        const pinned = fixture[file];
+        // Deleting or renaming an applied migration is forbidden: the decoder has no ledger rename map.
+        if(!Object.hasOwn(files, file)){
+            out.push({ file, kind: 'missing', message: file + ' is pinned but gone: deleting or renaming an applied ' +
+                'migration breaks every ledger that recorded it.' });
+            continue;
+        }
+        const now = pinOf(files[file]);
+        // A changed statement is never healable; it needs a new dated migration.
+        if(now.residue !== pinned.residue){
+            out.push({ file, kind: 'residue', message: file + ': the executable statements of a pinned migration ' +
+                'changed. Revert and write a new dated migration; MIGRATION_CHECKSUM_REBASELINES heals the ledger only.' });
+            continue;
+        }
+        // A comment-only change passes only under a rebaseline healing exactly the pinned hash to the current one.
+        const heal = rebaselines && rebaselines[file];
+        const healed = heal && heal.to === now.sha256 && [].concat(heal.from).includes(pinned.sha256);
+        if(now.sha256 !== pinned.sha256 && !healed){
+            out.push({ file, kind: 'content', message: file + ': content changed with no rebaseline from ' +
+                pinned.sha256.slice(0, 12) + ' to ' + now.sha256.slice(0, 12) + ', so every DB that applied it logs ' +
+                '`content CHANGED` and migrate.js fails closed there. Revert, or add a reviewed comment-only rebaseline.' });
+        }
+    }
+    return out;
+}
+
+// Every committed migration (`.sql` only; the README beside them is not one), name -> raw text.
+function readTree(){
+    const files = {};
+    for(const f of fs.readdirSync(MIG_DIR).filter((n) => n.endsWith('.sql'))) files[f] = fs.readFileSync(path.join(MIG_DIR, f), 'utf8');
+    return files;
+}
+
+function writeFixture(fixture){
+    const sorted = {};
+    for(const k of Object.keys(fixture).sort()) sorted[k] = fixture[k];
+    fs.writeFileSync(FIXTURE, JSON.stringify(sorted, null, 2) + '\n');
+}
+
+function main(argv){
+    const files   = readTree();
+    const fixture = JSON.parse(fs.readFileSync(FIXTURE, 'utf8'));
+    const accept  = argv.flatMap((a, i) => (a === '--accept' ? [argv[i + 1]] : []));
+    if(argv.includes('--add') || accept.length){
+        const added = Object.keys(files).filter((f) => !fixture[f]);
+        if(argv.includes('--add')) for(const f of added) fixture[f] = pinOf(files[f]);
+        for(const f of accept){
+            if(!files[f]) throw new Error('--accept ' + f + ': no such migration');
+            console.warn('ACCEPTED a new pin for ' + f + ': legitimate only if no database has applied it.');
+            fixture[f] = pinOf(files[f]);
+        }
+        writeFixture(fixture);
+        console.log('pinned ' + (argv.includes('--add') ? added.length : 0) + ' new, accepted ' + accept.length +
+            '. Next: node bin/lib/migration_residue_pin.js');
+        return 0;
+    }
+    const bad = findViolations({ files, fixture, rebaselines: MIGRATION_CHECKSUM_REBASELINES });
+    for(const v of bad) console.log(v.kind + ': ' + v.message);
+    const unpinned = Object.keys(files).filter((f) => !fixture[f]).length;
+    console.log(bad.length + ' violation(s), ' + unpinned + ' unpinned file(s).' +
+        (unpinned ? ' Next: node bin/lib/migration_residue_pin.js --add' : ''));
+    return bad.length ? 1 : 0;
+}
+
+module.exports = { executableResidue, pinOf, findViolations, readTree, FIXTURE };
+
+if(require.main === module) process.exitCode = main(process.argv.slice(2));