Release v0.19.0 - xchain-decoder

.github/workflows/ci.yml

@@ -71,12 +71,22 @@ jobs:
             console.log("consensus pin conformance OK (testnet, regtest)");
           '
 
+      # Identity pin: bin/pins/identity.json records the sha256 of the vendored
+      # coin files and the two twin fixtures. Re-hash the tree against it and
+      # fail on any moved, missing or unreadable file, so a stale pin cannot
+      # reach develop or master green through a direct push or a release pull
+      # request. bin/ci-full.sh runs the same command before a push; the tool
+      # uses only node builtins, so this job needs no install.
+      - name: Identity pin (vendored coins, twin fixtures)
+        working-directory: xchain-decoder
+        run: node bin/pin-identity.js --check
+
   # Docker-gated tiers: the integration and e2e suites each bring up their own
   # throwaway regtest node and MariaDB with docker compose, so they cannot run
   # inside `npm run ci`. They get their own job on a runner that has docker, so a
   # slow or flaky venue cannot hold up the fast tier's signal. The map of which
   # tier is gated where lives in test/tier-manifest.json and is enforced by
-  # test/unit/tierManifest.test.js.
+  # test/unit/tier_manifest.test.js.
   docker-suites:
     runs-on: ubuntu-latest
     timeout-minutes: 30

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-09-16
+
+### Added
+- Consensus: the XBRIDGE action name and its escrow role addresses are recognized.
+
+### Changed
+- Audited transitive packages move to their patched releases (lockfile only).
+- Restructured under the platform code-structure standard (feature directories, snake_case files, split test suites, restored comments); consensus identity byte-identical and pinned.
+
 ## [0.18.0] - 2026-09-11
 
 ### Fixed

Dockerfile

@@ -11,9 +11,9 @@ COPY ./src /XChainDecoder/src
 # readUInt64 throws "RangeError: value out of range" for output values above
 # ~9.007e15 (2^53), which Dogecoin mainnet exceeds (>~90.07M DOGE in one output).
 # Mirrors xchain-utxo-tracker's identical patch. Belt-and-braces: the same patch
-# is also applied in-process at require time (src/applyBufferutilsPatch.js), so
+# is also applied in-process at require time (src/chain/apply_bufferutils_patch.js), so
 # non-Docker runs and node_modules refreshes are covered even without this COPY.
-COPY ./src/bufferutils.js /XChainDecoder/node_modules/bitcoinjs-lib/src/bufferutils.js
+COPY ./src/chain/bufferutils.js /XChainDecoder/node_modules/bitcoinjs-lib/src/bufferutils.js
 # No .env is baked in: configuration reaches the container as environment
 # (xchain-node at `docker run`, docker-compose.yml via env_file). An optional
 # `COPY ./.en[v]` glob here builds only under BuildKit.

README.md

@@ -4,8 +4,8 @@
 # XChain Platform Decoder
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.18.0-blue" alt="Version">
-  <img src="https://img.shields.io/badge/tests-2%2C077%2B%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/version-0.19.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/tests-2%2C118%2B%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/node-%3E%3D22-green" alt="Node">
   <img src="https://img.shields.io/badge/license-AGPL--3.0--or--later-blue" alt="License">
 </p>
@@ -113,7 +113,7 @@ neither source sets one, so these defaults hold on an unconfigured box:
 | `npm run migrate` | Apply pending database migrations (auto + manual; `--file <name>` scopes to specific migration(s)) |
 | `npm run ci` | The full no-external-services gate: unit, security, smoke, regression, chaos, and a 100-iteration fuzz pass (about a minute) |
 | `npm run test:smoke` | Smoke tests (58 tests, no external services) |
-| `npm run test:unit` | Unit tests (1,596 tests, no external services) |
+| `npm run test:unit` | Unit tests (1,637 tests, no external services) |
 | `npm run test:security` | Security tests (83 tests, no external services) |
 | `npm run test:integration` | Integration tests (30 tests; brings up its own throwaway regtest node and MariaDB, requires Docker) |
 | `npm run test:e2e` | End-to-end tests (72 tests; brings up its own throwaway regtest node and MariaDB on separate ports, requires Docker) |

bin/ci-full.sh

@@ -70,10 +70,13 @@ run_tier() {
   fi
 }
 need_sib() {
-  local s
+  local s missing
   for s in "$@"; do
-    if [ ! -d "$SIB/$s" ]; then
-      echo "ci:full: MISSING SIBLING $SIB/$s" >&2
+    missing=""
+    [ -e "$SIB/$s/package.json" ] || missing="$missing package.json"
+    [ -e "$SIB/$s/.git" ] || missing="$missing .git"
+    if [ -n "$missing" ]; then
+      echo "ci:full: MISSING SIBLING $SIB/$s (missing:$missing)" >&2
       echo "ci:full: GitHub CI checks this sibling out and runs steps against it," >&2
       echo "ci:full: so skipping here would gate green on a subset. Declare it in" >&2
       echo "ci:full: .ci-siblings (venue) or clone it beside this repo (hand run)." >&2
@@ -107,6 +110,13 @@ run_tier "drift: coin consensus-pin conformance" node -e '
   console.log("consensus pin conformance OK (testnet, regtest)");
 '
 
+# --- identity pin (this gate only; no ci.yml job runs it) ------------------
+# bin/pins/identity.json holds the sha256 of the vendored coin files and the
+# two twin fixtures. Nothing else reads it, so this tier re-hashes the tree
+# against it and fails on any moved, missing or unreadable file instead of
+# letting the pin go stale.
+run_tier "identity pin (vendored coins, twin fixtures)" node bin/pin-identity.js --check
+
 # --- job: docker-suites ----------------------------------------------------
 # Both tiers own their venue lifecycle inside their npm script (compose up
 # --wait, mocha, down -v on any exit), so this transcribes the two run-steps

bin/comment-run-pairs.js

@@ -0,0 +1,177 @@
+#!/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.
+ *
+ **********************************************************************
+ *
+ * Which comments did the removal sweep REWRITE, and what did the rewrite take
+ * with it?
+ *
+ * WHY A LINE COUNT CANNOT ANSWER THIS. A restore pass puts back the comment
+ * runs that are GONE, and a coverage floor proves it did. Neither sees the
+ * other half of the loss: the sweep also scrubbed internal references out of
+ * lines it KEPT, and some of those rewrites took the explanation along with
+ * the reference. The file ends up with a comment in the same place, shorter,
+ * saying less, and every line-based check reads it as present.
+ *
+ * WHY THE COMPARISON IS RUN-LEVEL AND NOT LINE-LEVEL. Rewrapping a paragraph
+ * at a different width changes every line in it, so line pairing reports a
+ * pure rewrap as a total loss and buries the real cases. A RUN is a block of
+ * consecutive comment lines, which is the unit a writer actually edits.
+ *
+ * HOW RUNS ARE PAIRED. By token overlap: the Jaccard index of the two runs'
+ * word sets, with a floor of 0.3. Above the floor the two runs are the same
+ * comment, edited. Below it they are different comments, and the before-run
+ * counts as deleted (which the restore pass already handles) rather than as
+ * rewritten.
+ *
+ * WHAT IS FLAGGED. A paired run whose AFTER side carries fewer content words
+ * than its BEFORE side. The words it lost are printed so a reader can judge
+ * whether they were the reference (correctly gone) or the explanation around
+ * it (wrongly gone, and to be merged back WITHOUT the reference).
+ *
+ * The verdict is a human's. This tool finds the candidates and shows both
+ * texts; it never edits a file, because deciding what a sentence was for is
+ * exactly the part that cannot be automated.
+ *
+ * USAGE
+ *   node bin/comment-run-pairs.js --before <sha> --after <sha> [--json]
+ *   node bin/comment-run-pairs.js --before <sha> --after <sha> --file <path>
+ *
+ ********************************************************************/
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const JACCARD_FLOOR = 0.3;
+
+function git(args) {
+    return execFileSync('git', args, { maxBuffer: 256 * 1024 * 1024 }).toString('utf8');
+}
+
+/** The same comment-line definition the coverage gate uses. */
+function commentMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    let inBlock = false;
+    for (let i = 0; i < lines.length; i += 1) {
+        const t = lines[i].trim();
+        if (inBlock) { mask[i] = true; if (t.includes('*/')) inBlock = false; continue; }
+        if (t.startsWith('//')) { mask[i] = true; continue; }
+        if (t.startsWith('/*')) { mask[i] = true; if (!t.includes('*/')) inBlock = true; }
+    }
+    return mask;
+}
+
+/** Content words: whitespace tokens carrying a letter or a digit, markers off. */
+function words(body) {
+    return body
+        .join(' ')
+        .replace(/\/\*+|\*+\/|^\s*\*|\/\//g, ' ')
+        .split(/\s+/)
+        .map((w) => w.replace(/^[^A-Za-z0-9]+|[^A-Za-z0-9]+$/g, ''))
+        .filter((w) => /[A-Za-z0-9]/.test(w));
+}
+
+/** Every comment run in a file, with the code line it sits above. */
+function runs(text) {
+    const lines = text.split('\n');
+    const mask = commentMask(lines);
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (!mask[i]) { i += 1; continue; }
+        const start = i;
+        while (i < lines.length && mask[i]) i += 1;
+        let j = i;
+        while (j < lines.length && lines[j].trim() === '') j += 1;
+        out.push({ body: lines.slice(start, i), anchor: j < lines.length ? lines[j].trim() : null, line: start + 1 });
+    }
+    return out;
+}
+
+function jaccard(a, b) {
+    const sa = new Set(a.map((w) => w.toLowerCase()));
+    const sb = new Set(b.map((w) => w.toLowerCase()));
+    if (!sa.size && !sb.size) return 1;
+    let shared = 0;
+    for (const w of sa) if (sb.has(w)) shared += 1;
+    return shared / (sa.size + sb.size - shared);
+}
+
+function fileList(before, after) {
+    return git(['diff', '--name-only', `${before}..${after}`]).split('\n').filter(Boolean);
+}
+
+function blob(sha, file) {
+    try { return git(['show', `${sha}:${file}`]); } catch (e) { return null; }
+}
+
+function main() {
+    const argv = process.argv.slice(2);
+    const arg = (name) => { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1]; };
+    const before = arg('--before');
+    const after = arg('--after');
+    const only = arg('--file');
+    const asJson = argv.includes('--json');
+    if (!before || !after) { process.stderr.write('usage: comment-run-pairs.js --before <sha> --after <sha> [--file <path>] [--json]\n'); return 2; }
+
+    const flagged = [];
+    let pairs = 0;
+    const files = only ? [only] : fileList(before, after);
+    for (const file of files) {
+        const b = blob(before, file);
+        const a = blob(after, file);
+        if (b === null || a === null) continue;
+
+        const bRuns = runs(b).map((r) => ({ ...r, words: words(r.body) }));
+        const aRuns = runs(a).map((r) => ({ ...r, words: words(r.body) }));
+        const taken = new Set();
+
+        for (const br of bRuns) {
+            let best = null;
+            let bestScore = 0;
+            for (let k = 0; k < aRuns.length; k += 1) {
+                if (taken.has(k)) continue;
+                const score = jaccard(br.words, aRuns[k].words);
+                if (score > bestScore) { bestScore = score; best = k; }
+            }
+            if (best === null || bestScore < JACCARD_FLOOR) continue;
+            taken.add(best);
+            pairs += 1;
+            const ar = aRuns[best];
+            if (ar.words.length >= br.words.length) continue;
+            const after_ = new Set(ar.words.map((w) => w.toLowerCase()));
+            const lost = br.words.filter((w) => !after_.has(w.toLowerCase()));
+            if (!lost.length) continue;
+            flagged.push({
+                file,
+                beforeLine: br.line,
+                afterLine: ar.line,
+                similarity: Number(bestScore.toFixed(2)),
+                lostWords: lost.length,
+                lost,
+                beforeText: br.body.join('\n'),
+                afterText: ar.body.join('\n'),
+            });
+        }
+    }
+
+    if (asJson) { process.stdout.write(`${JSON.stringify({ before, after, pairs, flagged }, null, 2)}\n`); return 0; }
+    for (const f of flagged) {
+        process.stdout.write(`\n${f.file}:${f.beforeLine} -> :${f.afterLine}  similarity ${f.similarity}, ${f.lostWords} word(s) lost\n`);
+        process.stdout.write(`  BEFORE\n${f.beforeText.split('\n').map((l) => `    ${l}`).join('\n')}\n`);
+        process.stdout.write(`  AFTER\n${f.afterText.split('\n').map((l) => `    ${l}`).join('\n')}\n`);
+    }
+    process.stdout.write(`\n${pairs} paired run(s), ${flagged.length} that lost words\n`);
+    return 0;
+}
+
+process.exit(main());

bin/coverage-thresholds.json

@@ -1,5 +1,5 @@
 {
-  "comment": "Coverage floors for the CI coverage job (regression floors, ~1-1.5 points below measured, not tier targets; raise as coverage climbs). Mirrored into the coverage:check npm script in package.json and guarded by test/unit/coverage-thresholds-sync.test.js. Re-measured 2026-08-14 WITH the declared siblings checked out, which is what the coverage job now does: 89.30 lines/statements, 86.97 branches, 78.75 functions over 1289 unit tests (1248 without siblings).",
+  "comment": "Coverage floors for the CI coverage job (regression floors, ~1-1.5 points below measured, not tier targets; raise as coverage climbs). Mirrored into the coverage:check npm script in package.json and guarded by test/unit/coverage_thresholds_sync.test.js. Re-measured 2026-08-14 WITH the declared siblings checked out, which is what the coverage job now does: 89.30 lines/statements, 86.97 branches, 78.75 functions over 1289 unit tests (1248 without siblings).",
   "lines": 87.8,
   "statements": 87.8,
   "branches": 85.4,

bin/indexer_handler_source.js

@@ -0,0 +1,60 @@
+/*********************************************************************
+ *
+ * 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.
+ *
+ **********************************************************************
+ *
+ * Finds one xchain-indexer action handler in a sibling checkout, whichever shape it has.
+ *
+ * WHY. A handler is one file, src/actions/<name>.js, until the indexer's file-size work
+ * splits it into src/actions/<name>/ with the entry at index.js and the logic in parts
+ * beside it, leaving NO flat file behind (the sdk pre-flight drift gate refuses
+ * to pin a handler directory while a flat <name>.js sits next to it, since require() would
+ * resolve the flat file first). Anything here that names the flat path then reads a file
+ * that is not there: the sync tool reports a missing sibling, and a source-text mirror
+ * check reports the indexer as registering nothing.
+ *
+ * WHAT. entry() is the path to require, source() the handler's whole text: the entry plus
+ * every part beside it, so a literal or a registration that moved into a part is still
+ * read. A checkout that still carries the flat file reads exactly as it always did.
+ *
+ ********************************************************************/
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+/** The path to require for handler <name> under an indexer checkout root. */
+function entry(indexerRoot, name) {
+    const flat = path.join(indexerRoot, 'src', 'actions', name + '.js');
+    if (fs.existsSync(flat)) return flat;
+    const inDirectory = path.join(indexerRoot, 'src', 'actions', name, 'index.js');
+    return fs.existsSync(inDirectory) ? inDirectory : flat;
+}
+
+/** Every file of handler <name>, sorted, entry included. Empty when the handler is absent. */
+function files(indexerRoot, name) {
+    const dir = path.join(indexerRoot, 'src', 'actions', name);
+    if (fs.existsSync(dir) && fs.statSync(dir).isDirectory())
+        return fs.readdirSync(dir).filter((f) => f.endsWith('.js')).sort()
+            .map((f) => path.join(dir, f));
+    const flat = path.join(indexerRoot, 'src', 'actions', name + '.js');
+    return fs.existsSync(flat) ? [flat] : [];
+}
+
+/** The handler's source text, entry and parts newline-joined, or null when it is absent. */
+function source(indexerRoot, name) {
+    const list = files(indexerRoot, name);
+    return list.length ? list.map((f) => fs.readFileSync(f, 'utf8')).join('\n') : null;
+}
+
+module.exports = { entry, files, source };