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"
+          }
+        ]
+      }
+    ]
+  }
+}

.github/attest-mirror/compose.yml

@@ -202,6 +202,11 @@ services:
       INDEXER_COIN: BTC
       INDEXER_NETWORK: regtest
       INDEXER_API_PORT: 3004
+      # Every host-side caller (the venue's five hubs, its indexers and the suite)
+      # reaches this indexer through the published port from one source address, so
+      # the per-IP default of 600 a minute is spent in about 40 s and the hubs' tip
+      # reads are refused for the rest of each window. The same applies to LTC and DOGE.
+      INDEXER_RATE_LIMIT_RPM: 99999
       INDEXER_DB_HOST: db
       INDEXER_DB_PORT: 3306
       INDEXER_DB_NAME: XChain_BTC_Regtest_Indexer
@@ -409,6 +414,7 @@ services:
       INDEXER_COIN: LTC
       INDEXER_NETWORK: regtest
       INDEXER_API_PORT: 3004
+      INDEXER_RATE_LIMIT_RPM: 99999
       INDEXER_DB_HOST: db
       INDEXER_DB_PORT: 3306
       INDEXER_DB_NAME: XChain_LTC_Regtest_Indexer
@@ -592,6 +598,7 @@ services:
       INDEXER_COIN: DOGE
       INDEXER_NETWORK: regtest
       INDEXER_API_PORT: 3004
+      INDEXER_RATE_LIMIT_RPM: 99999
       INDEXER_DB_HOST: db
       INDEXER_DB_PORT: 3306
       INDEXER_DB_NAME: XChain_DOGE_Regtest_Indexer

.github/attest-mirror/run-leg.sh

@@ -53,7 +53,7 @@ for p in "$BTC_NODE_PORT" "$LTC_NODE_PORT" "$DOGE_NODE_PORT"; do
 done
 cd "${ATTEST_MIRROR_E2E_DIR:-$root/xchain-e2e-test}"
 printf "=== leg %s start %s node %s stack xca7%s venue-base %s file %s extra-env [%s]\n" "$tag" "$(date -u +%FT%TZ)" "$(node -v)" "$stack" "$venue_base" "$leg" "$*"
-env "$@" npx mocha --timeout 0 --exit --require ./test/initialCheck.test.js "$leg" 2>&1 | node -e 'const rl=require("readline").createInterface({input:process.stdin});rl.on("line",l=>process.stdout.write(new Date().toISOString().slice(11,19)+" "+l+"\n"))'
+env "$@" npx mocha --timeout 0 --exit --require ./test/initial_check.test.js "$leg" 2>&1 | node -e 'const rl=require("readline").createInterface({input:process.stdin});rl.on("line",l=>process.stdout.write(new Date().toISOString().slice(11,19)+" "+l+"\n"))'
 rc=${PIPESTATUS[0]}
 printf "=== leg %s exit=%s end %s\n" "$tag" "$rc" "$(date -u +%FT%TZ)"
 exit "$rc"

.github/attest-mirror/seed-stack-config.js

@@ -4,10 +4,14 @@ const port = Number(process.argv[2]);
 const pass = process.env.DB_PASSWORD;
 if (!port || !pass) process.exit(2);
 const ixHost = { BTC: 'indexer', LTC: 'ltc-indexer', DOGE: 'doge-indexer' };
+// The indexer entry's host and port are its API; db_host and db_port say where its
+// database lives. The explorer builds its pools from db_host/db_port and falls back to
+// host/port without them, so it would dial the indexer API as MariaDB and never serve.
 function services(code) {
     return {
         'xchain-decoder': { host: 'db', port: '3306', name: `XChain_${code}_Regtest_Decoder`, user: 'root', pass },
-        'xchain-indexer': { host: ixHost[code], port: '3004', name: `XChain_${code}_Regtest_Indexer`, user: 'root', pass }
+        'xchain-indexer': { host: ixHost[code], port: '3004', db_host: 'db', db_port: '3306',
+            name: `XChain_${code}_Regtest_Indexer`, user: 'root', pass }
     };
 }
 const config = {

.github/attest-mirror/setup-stack.sh

@@ -57,6 +57,26 @@ for _ in $(seq 1 180); do
         set +a
         node "$root/seed-stack-config.js" "$HUB_HOST_PORT"
         node "$root/wait-indexer-schema.js"
+        # The explorer answers ping 503 until its next hub config poll picks up the coins
+        # seeded above, which can trail a warm boot by a minute. A suite that pings it
+        # first fails its initial check, so the stack is ready only once it answers.
+        explorer_ping='{"jsonrpc":"2.0","method":"ping","id":1}'
+        explorer_ok=0
+        for _ in $(seq 1 120); do
+            if curl -fsS -o /dev/null -H 'content-type: application/json' --data "$explorer_ping" \
+                "http://127.0.0.1:$EXPLORER_HTTP_HOST_PORT/" 2>/dev/null; then
+                explorer_ok=1
+                break
+            fi
+            sleep 2
+        done
+        if [ "$explorer_ok" != 1 ]; then
+            date -u
+            printf "explorer=%s\n" "$(health explorer)"
+            printf "explorer ping timeout for xca7%s\n" "$stack"
+            exit 1
+        fi
+        printf "explorer ready\n"
         date -u
         exit 0
     fi

.github/attest-mirror/wait-indexer-schema.js

@@ -1,23 +1,94 @@
-'use strict';
-// Venue warm-up: waits until the stack indexer's schema exists (issues table) and its /status answers, so a leg's
-// initialCheck ISSUE never races the indexer's first migration. Credentials come from the stack .env via env.
-const mariadb = require('module').createRequire(require('path').join(process.env.ATTEST_MIRROR_E2E_DIR, 'package.json'))('mariadb');
-const waitMs = Number(process.env.ATTEST_SCHEMA_WAIT_MS || 1200000);
-const deadline = Date.now() + waitMs;
-(async () => {
+'use strict'
+
+const path = require('path')
+const { createRequire } = require('module')
+
+const DATABASE = 'XChain_BTC_Regtest_Indexer'
+const TABLE = 'issues'
+const DEFAULT_WAIT_MS = 1200000
+const DEFAULT_INTERVAL_MS = 3000
+
+function loadMariadb (env) {
+    return createRequire(path.join(env.ATTEST_MIRROR_E2E_DIR, 'package.json'))('mariadb')
+}
+
+async function issuesTableReady (config) {
+    let connection = null
+    try {
+        connection = await config.connect(config.dbOptions)
+        const rows = await connection.query(
+            "SELECT COUNT(*) AS n FROM information_schema.tables WHERE table_schema = '" +
+            DATABASE + "' AND table_name = '" + TABLE + "'")
+        return Number(rows[0].n) === 1
+    } catch (_) {
+        return false
+    } finally {
+        if (connection) await connection.end().catch(() => {})
+    }
+}
+
+async function schemaReady (config) {
+    let body
+    try {
+        const response = await config.fetchImpl(config.statusUrl)
+        if (!response || !response.ok) return false
+        body = await response.json()
+    } catch (_) {
+        return false
+    }
+    if (!body || typeof body !== 'object') return false
+    if (Object.prototype.hasOwnProperty.call(body, 'schemaReady')) return body.schemaReady === true
+    return issuesTableReady(config)
+}
+
+async function waitForSchema (config) {
+    const deadline = config.now() + config.waitMs
     for (;;) {
-        let ok = false;
-        try {
-            const options = { host: '127.0.0.1', port: Number(process.env.DB_HOST_PORT), user: 'root' };
-            options['pass' + 'word'] = process.env['DB_' + 'PASSWORD'];
-            const c = await mariadb.createConnection(options);
-            const rows = await c.query("SELECT COUNT(*) AS n FROM information_schema.tables WHERE table_schema = 'XChain_BTC_Regtest_Indexer' AND table_name = 'issues'");
-            await c.end();
-            const res = await fetch(`http://127.0.0.1:${process.env.INDEXER_HOST_PORT}/status`).catch(() => null);
-            ok = Number(rows[0].n) === 1 && !!res && res.ok;
-        } catch (e) { ok = false; }
-        if (ok) { console.log('indexer schema ready'); return; }
-        if (Date.now() > deadline) { console.log('indexer schema NOT ready after ' + Math.round(waitMs / 1000) + ' s'); process.exit(5); }
-        await new Promise((r) => setTimeout(r, 3000));
+        if (await schemaReady(config)) return true
+        if (config.now() > deadline) return false
+        await config.sleep(config.intervalMs)
+    }
+}
+
+function configFromEnv (env, dependencies) {
+    const dbOptions = { host: '127.0.0.1', port: Number(env.DB_HOST_PORT), user: 'root' }
+    dbOptions['pass' + 'word'] = env['DB_' + 'PASSWORD']
+    return {
+        connect: dependencies.mariadb.createConnection,
+        dbOptions,
+        fetchImpl: dependencies.fetchImpl,
+        statusUrl: 'http://127.0.0.1:' + env.INDEXER_HOST_PORT + '/status',
+        waitMs: Number(env.ATTEST_SCHEMA_WAIT_MS || DEFAULT_WAIT_MS),
+        intervalMs: DEFAULT_INTERVAL_MS,
+        now: dependencies.now || Date.now,
+        sleep: dependencies.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    }
+}
+
+async function main (runtime) {
+    const context = runtime || {}
+    const env = context.env || process.env
+    const mariadb = context.mariadb || loadMariadb(env)
+    const config = configFromEnv(env, {
+        mariadb,
+        fetchImpl: context.fetchImpl || fetch,
+        now: context.now,
+        sleep: context.sleep,
+    })
+    const log = context.log || console.log
+    if (await waitForSchema(config)) {
+        log('indexer schema ready')
+        return 0
     }
-})();
+    log('indexer schema NOT ready after ' + Math.round(config.waitMs / 1000) + ' s')
+    return 5
+}
+
+if (require.main === module) {
+    main().then((code) => { process.exitCode = code }).catch((error) => {
+        console.error(error.message)
+        process.exitCode = 5
+    })
+}
+
+module.exports = { DATABASE, TABLE, issuesTableReady, schemaReady, waitForSchema, configFromEnv, main }

.github/hub-failover/compose.testnet-ids.yml

@@ -0,0 +1,19 @@
+services:
+  hub-a:
+    environment:
+      P2P_VALIDATOR_ADDR: mverify5szar1XwwAjqAnPUHbA814kfHh4
+
+  hub-b:
+    environment:
+      P2P_VALIDATOR_ADDR: mverify7szar1XwwAjqAnPUHbA814kfHh4
+
+  hub-federation-init:
+    command:
+      - |
+        for hub in hub-a hub-b; do
+          for registration in \
+            '{"jsonrpc":"2.0","id":1,"method":"registervalidator","params":{"signing_pubkey":"03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8","addr":"mverify5szar1XwwAjqAnPUHbA814kfHh4"}}' \
+            '{"jsonrpc":"2.0","id":2,"method":"registervalidator","params":{"signing_pubkey":"29acbae141bccaf0b22e1a94d34d0bc7361e526d0bfe12c89794bc9322966dd7","addr":"mverify7szar1XwwAjqAnPUHbA814kfHh4"}}'; do
+            wget -qO- --header="x-api-key: $${HUB_API_KEY}" --header="Content-Type: application/json" --post-data="$${registration}" "http://$${hub}:10000/" | grep -q '"status":"success"'
+          done
+        done

.github/workflows/mutation.yml

@@ -31,11 +31,15 @@ jobs:
       - name: Run Stryker
         run: npm run test:mutation
 
+      - name: Verify mutation reports
+        if: always()
+        run: test -s reports/mutation/report.json && test -s reports/mutation/index.html
+
       - name: Upload mutation report
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: mutation-report
           path: reports/mutation/
-          if-no-files-found: warn
+          if-no-files-found: error
           retention-days: 30

.github/workflows/nightly-e2e.yml

@@ -163,7 +163,7 @@ permissions:
 #
 # A shard is a fresh stack, so every suite already had to be runnable alone
 # (the `suite` input has always relied on that); sharding adds no new ordering
-# assumption. Five shards bring the bitcoin weights to ~42 minutes of action
+# assumption. Six shards bring the bitcoin weights to ~34 minutes of action
 # per shard, about an hour per job with setup and boot.
 jobs:
   plan:
@@ -176,10 +176,10 @@ jobs:
     env:
       STACK_REF: ${{ github.event.inputs.ref || 'develop' }}
       SUITE: ${{ github.event.inputs.suite || '' }}
-      # Sized off run 35605562229: ~204 minutes of bitcoin action weight over 5
-      # shards is ~42 each. Raise it here if the suite grows; nothing else
-      # hardcodes the count. Three coins at 5 shards is 15 concurrent runners.
-      E2E_SHARDS: '5'
+      # Sized off run 35605562229: ~204 minutes of bitcoin action weight over 6
+      # shards is ~34 each. Raise it here if the suite grows; nothing else
+      # hardcodes the count. Three coins at 6 shards is 18 concurrent runners.
+      E2E_SHARDS: '6'
     steps:
       # The plan and merge scripts come from THIS workflow's commit, not from
       # the ref under test, so an older ref (a published vX.Y.Z) that predates
@@ -235,9 +235,9 @@ jobs:
         coin: ${{ fromJSON(needs.plan.outputs.coins) }}
         shard: ${{ fromJSON(needs.plan.outputs.shards) }}
     # 360 was the unsharded ceiling, set because a whole coin pass had no
-    # measured duration to size against. A shard does: ~42 minutes of action
+    # measured duration to size against. A shard does: ~34 minutes of action
     # plus ~15 of setup and boot on bitcoin, somewhat more on the two-stack
-    # legs. 240 is four times that, so a slow leg is never truncated, while a
+    # legs. 240 is about five times that, so a slow leg is never truncated, while a
     # WEDGED shard (a hung container, a stalled indexer poll) reports in four
     # hours instead of six.
     timeout-minutes: 240

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-10-11
+
+### Added
+- Added co-located indexer URLs to the hub config and honored per-coin hub seed and route settings.
+- Added an isolated bootstrap restore rehearsal and recovery of shared containers after a redeploy.
+- Recognized the UNARMED go-live sentinels in the release guards.
+
+### Changed
+- Applied container limits and resource overrides consistently at creation.
+- Made update all continue past a guard refusal and failed closed when the latest release lookup errors.
+
+### Fixed
+- Guarded coin node and datadir bind mount sources against drift.
+- Preserved the container environment on recreate and blocked stake teardown on a sleeping source address.
+- Dropped the encoder from autoheal because a restart cannot clear a tracker halt.
+
 ## [0.22.7] - 2026-10-06
 
 ### Changed

CONTRIBUTING.md

@@ -118,6 +118,7 @@ CI is the unit gate. Before opening a PR:
 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 generated `.env` files).
 4. Open the PR with a clear title and a description of what changed and why.
+5. The CLA Assistant bot records your signature on your first PR; one signature covers every XChain Platform repository. Its `license/cla` check must pass before the PR can merge.
 
 For non-security bugs, open an issue at <https://github.com/XChain-Platform/xchain-node/issues/new>. For security bugs, see [`SECURITY.md`](./SECURITY.md).
 

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

@@ -136,15 +136,17 @@ When xchain-node manages its own MariaDB container, these optional env vars over
 
 ## Autoheal (restart-on-unhealthy)
 
-Every persistent service container carries a Docker healthcheck, but Docker itself takes no action on the `unhealthy` state (`--restart unless-stopped` only fires when the process exits). An alive-but-stalled service would otherwise stay wedged until an operator notices it in `docker ps`. `xchain-node autoheal` closes that loop: it restarts containers that have been continuously unhealthy past a grace window, for services opted in via `autoheal: true` in the healthcheck table (currently the decoder, encoder, and indexer; the utxo-tracker is deliberately excluded because it halts on purpose rather than exiting, and a restart would just re-halt it).
+Every persistent service container carries a Docker healthcheck, but Docker itself takes no action on the `unhealthy` state (`--restart unless-stopped` only fires when the process exits). An alive-but-stalled service would otherwise stay wedged until an operator notices it in `docker ps`. `xchain-node autoheal` closes that loop: it restarts containers that have been continuously unhealthy past a grace window, for services opted in via `autoheal: true` in the healthcheck table (currently the decoder and indexer; the utxo-tracker is deliberately excluded because it halts on purpose rather than exiting, and a restart would just re-halt it; the encoder is deliberately excluded because its health probe reports utxo-tracker readiness (unreachable, halted, lagging or mempool not ready), which restarting the encoder cannot clear).
 
 The command is one-shot and never prompts or daemonizes. Unattended remediation requires wiring it to a cron entry or systemd timer, e.g. `*/5 * * * * xchain_node autoheal`. Detection-to-restart latency is the timer interval plus the health retry budget plus the grace window. Use `--dry-run` to see restart candidates without acting. Exit code is non-zero only when a restart was attempted and failed.
 
 | Variable | Default | What it controls |
 |---|---|---|
 | `XCHAIN_NODE_AUTOHEAL_GRACE_MS` | `120000` | How long a container must be continuously unhealthy before a restart is considered |
-| `XCHAIN_NODE_AUTOHEAL_COOLDOWN_MS` | `600000` | Minimum time between two autoheal restarts of the same container (anti-flap) |
-| `XCHAIN_NODE_AUTOHEAL_STATE_DIR` | `~/.xchain-node` | Where the anti-flap state file (`autoheal-state.json`) lives |
+| `XCHAIN_NODE_AUTOHEAL_COOLDOWN_MS` | `600000` | Base wait before autoheal restarts the same container again (anti-flap). The first retry waits this long; each further restart of a container that has not recovered doubles the wait, up to `XCHAIN_NODE_AUTOHEAL_COOLDOWN_CEILING_MS` (with defaults: 10m, 20m, 40m and so on, capped at 6h). The doubling resets once the container recovers |
+| `XCHAIN_NODE_AUTOHEAL_COOLDOWN_CEILING_MS` | `21600000` | Upper bound on the doubled cooldown. A container that never recovers settles at one restart per ceiling; there is no attempt cap, and every skipped pass logs an "investigate" line |
+| `XCHAIN_NODE_AUTOHEAL_PROBATION_MS` | `150000` | How long after an autoheal restart a passing health probe counts as that restart's own artifact rather than recovery, so it does not reset the backoff. If you widen a service's start period with `XCHAIN_NODE_HEALTH_START_PERIOD_<SERVICE>`, widen this to match (start period plus interval times retries, plus margin) |
+| `XCHAIN_NODE_AUTOHEAL_STATE_DIR` | `~/.xchain-node` | Where the state file (`autoheal-state.json`) lives: last restart times, unhealthy onsets and the per-container restart count that drives the backoff. Falls back to `XCHAIN_NODE_LOCK_DIR` when that is set, otherwise `~/.xchain-node` |
 
 ## Telemetry
 

bin/ci-full.sh

@@ -74,19 +74,16 @@ fast_defer() {
 # >>> 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 ====="
-  local root
-  root="$(mktemp -d "${TMPDIR:-/tmp}/xchain-node-ci-full.XXXXXX")"
-  mkdir -p "$root/config" "$root/data"
-  if ( export XCHAIN_NODE_CONFIG_DIR="$root/config" XCHAIN_NODE_DATA_DIR="$root/data"; "$@" ); then
+  if "$@"; then
     echo "ci:full ----- $name PASS ($(( SECONDS - __ci_tier_t0 ))s)"
   else
     FAILED="$FAILED [$name]"
     echo "ci:full ----- $name FAIL ($(( SECONDS - __ci_tier_t0 ))s)"
   fi
-  rm -rf -- "$root"
 }
 # <<< ci-tier timer <<<
 need_sib() {