Release v0.19.0 - xchain-documentation

.ci-siblings

@@ -0,0 +1,41 @@
+# Repos the documentation suite needs checked out BESIDE it on the CI venue.
+#
+# Declaring a sibling here is what makes its cross-repo guards actually run. An
+# UNdeclared sibling is not a neutral omission: every guard written against it
+# resolves with existsSync, calls this.skip(), and the gate still prints PASS,
+# so the run reports green having exercised none of them. Measured 2026-09-13,
+# with no roster the venue ran 397 passing / 60 skipped; with every repo below
+# beside it the same tree runs 485 tests, and the only skips left are the three
+# placeholder vector gaps in test/vectors.test.js and the LikeC4 topology model,
+# which lives in the platform workspace rather than in any sibling repo.
+#
+# ci-dispatch.sh ships each of these at the pushed branch (falling back to its
+# origin/master, then local HEAD) and REFUSES the push if one is not a checkout
+# beside this repo, so a declared sibling can never be silently absent.
+
+# The activation registry behind the generated flag-day page, the action
+# activation model, XBRIDGE registration, supply/settlement/dividend source
+# facts, fee and batch limits, and the schema-table coverage of database.md.
+xchain-indexer
+# The consensus wall-clock budget the VM pages quote.
+xchain-vm
+# Endpoint counts, the ExplorerStatus schema, the REST error-code registry,
+# contract-state proof availability and the regtest tip-age escape hatch.
+xchain-explorer
+# The multisign capacity figure the corpus pages publish.
+xchain-encoder
+# The SDK action surface and the canonical batch limits.
+xchain-sdk
+# The signer surface and release-key fingerprint channel one (SECURITY.md).
+xchain-wallet
+# The docs-site slug rule and release-key fingerprint channel two.
+xchain-websites
+# Schema-table coverage of the decoder and hub database pages.
+xchain-decoder
+xchain-hub
+# The environment-variable coverage fleet floor, which applies only when every
+# service component it scans is present (lib/env-var-doc-coverage.js COMPONENTS).
+xchain-node
+xchain-regtest-miner
+xchain-sync
+xchain-utxo-tracker

.github/workflows/ci.yml

@@ -16,9 +16,10 @@ name: CI
 # A drift in any of those is a wrong answer given to an implementer, and until
 # now nothing ran on a push to catch it.
 #
-# Hermetic: no sibling checkouts, no services, no secrets.
+# No services, no secrets, and exactly one sibling checkout (xchain-indexer,
+# read as text by the flag-day literals suite; see that step).
 #
-# The hermeticity has a cost worth naming rather than rediscovering:
+# The near-hermeticity has a cost worth naming rather than rediscovering:
 # a test that needs a SIBLING repo cannot run here, and node:test prints a skip
 # as a pass. test/schema-table-coverage.test.js is the one that bit: its
 # cross-repo half resolves xchain-decoder/-indexer/-hub beside this checkout,
@@ -62,6 +63,33 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          path: xchain-documentation
+
+      # test/flag-day-literals.test.js reads xchain-indexer/src/protocol_changes.js
+      # as a SIBLING checkout (../xchain-indexer relative to this repo's root,
+      # per bin/generate-flag-days.js) and quietly SKIPS its drift and
+      # completeness checks when that sibling is absent, which is exactly what
+      # every push here had been doing: the generated protocol/flag-days.md page
+      # could rot against the indexer's registry with this workflow green the
+      # whole way. Checked out beside xchain-documentation, not nested, so the
+      # generator's '../xchain-indexer' resolution finds it.
+      #
+      # Ref: the release branch on a release head (a PR from release/*), the
+      # pushed/targeted branch otherwise. Matches the ref logic xchain-e2e-test's
+      # CI already uses for the same sibling. The indexer repo is public, so the
+      # default token reads it and this repo keeps holding no secrets.
+      #
+      # Only ONE sibling is checked out. The suites that read a sibling skip the
+      # ones that are absent, and the env-var coverage suite applies its fleet
+      # floor only when every sibling is present, so a partial set is judged on
+      # what is here rather than accused of a broken scanner.
+      - name: Check out xchain-indexer (flag-day registry read by the literals suite)
+        uses: actions/checkout@v4
+        with:
+          repository: XChain-Platform/xchain-indexer
+          ref: ${{ startsWith(github.head_ref, 'release/') && github.head_ref || (github.ref == 'refs/heads/master' && 'master' || 'develop') }}
+          path: xchain-indexer
 
       # Node 22 exactly: the platform's suites require it, and on some repos an
       # off-version run degrades into silent skips rather than failing.
@@ -73,8 +101,14 @@ jobs:
       # mathjs is a devDependency here, pinned to the same exact 15.2.0 the
       # indexer, explorer, sdk and hub carry, because the reference
       # implementation must compute quorum weights the way the fleet does.
+      # Only this tree needs installing: the flag-day generator READS the
+      # indexer's registry as text (see the file-header note in
+      # bin/generate-flag-days.js) rather than requiring it, so the sibling
+      # checkout above needs no install of its own.
       - name: Install dependencies
+        working-directory: xchain-documentation
         run: if [ -f package-lock.json ]; then npm ci; else npm install; fi
 
       - name: Documentation conformance suite
+        working-directory: xchain-documentation
         run: npm test

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-09-16
+
+### Added
+- Published `ADMIT_MARGIN_BLOCKS`, `ADMIT_MIN_FUTURE_BLOCKS` and `ADMIT_MAX_FUTURE_BLOCKS`, the canonical admission-height margins that let a mirror barrier bind rows by block height instead of by the block's timestamp.
+- Published `MIRROR_ADMISSION_ACTIVATION` and `MIRROR_ADMISSION_CONSUMER_ACTIVATION`, the paired producer and consumer flag-day maps keyed by coin and network, inert everywhere pending their sizing at the cut.
+- Published `ANCHOR_ATTEST_ARRIVAL_MARGIN_S` (64800 s) and `ANCHOR_ATTEST_BARRIER_ACTIVATION`, the maturity-horizon bound that keeps the anchor-attest barrier opening no later than it does today.
+- The XBRIDGE action and the cross-chain bridge protocol are documented.
+- The bridge settle pass's origin-indexer reads are documented and the computed-read baseline is raised for the coin-keyed lookups.
+- The four bridge helper modules are counted in the e2e architecture and README pages.
+- Published the `TRAIN_ACTIVATION` 0.19.0 row and the per-chain testnet bridge heights this train arms.
+
+### Changed
+- The bridge activation is documented as keyed per chain.
+- Testnet activations are documented as arming at the tip read at the cut.
+- The wallet's cross-chain order form is documented.
+- Restructured under the platform code-structure standard (feature directories, snake_case files, split test suites, restored comments).
+
+### Fixed
+- CI checks out xchain-indexer beside this repo so the flag-day literals suite runs on GitHub instead of skipping, and the env-var coverage fleet floor applies only when every sibling is present.
+- The node and explorer configuration pages document `XCHAIN_NODE_ALLOW_NO_DOGE_READ` and `EXPLORER_FEDERATION_READ_KEY`.
+- The undo-window and halted-state pages state the per-network table (every testnet 120 blocks) and the halt's `/status` fields and reset path, replacing the stale LTC value.
+- The Pi 5 firmware's `cgroup_disable=memory` clause, the page-cache disk model and the node operations exit-status section are documented.
+
 ## [0.18.0] - 2026-09-11
 
 ### Added
@@ -23,6 +46,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The SDK websocket page matches the producer roster, adding the mempool, expiry, bet, attestation and xcall event types.
 - The explorer API page describes the merged `hub_status` on the validators endpoint.
 
+### Fixed
+- Corrected the bare-multisig capacity figure: 60 bytes per output (two 32-byte key slots), not ~61 bytes per key.
+- The indexer determinism and replay claims now name the local Hub DB mirror they read during block processing.
+- The explorer pages state the hub-mirror schema the explorer creates and writes under `self_sync`, instead of claiming it never writes to any database.
+- The hub configuration, architecture and database pages distinguish hub-local suspension from equivocation slashing: missed rounds and price deviation leave on-chain stake untouched.
+- Published Token Information Standard v1.1.1, which relaxes the media requirement to `type` plus at least one of `data` or `data_ref` so the fully on-chain form the standard recommends validates; v1.1.0 and v1.0.0 stay frozen as published.
+- The TIS media `type` row states the per-array vocabulary the schema enums pin (`images` display role, `audio` and `video` containers, `files` category) instead of calling it a MIME type.
+- The gated-pack publishing steps require one `FILE` per transaction: a `BATCH` hands one `rawData` payload to every sub-command, so a second `FILE` is recorded valid carrying the first file's ciphertext.
+
 ## [0.17.0] - 2026-09-10
 
 ### Added

CONTRIBUTING.md

@@ -27,7 +27,7 @@ xchain-documentation/
 ├── developer-guide/      tutorials: build tokens, dispensers, query data, integrate, testing
 ├── ai-agents/            building AI agents with MCP and bounded wallets
 ├── user-guide/           capabilities, use cases, FAQ (no code required)
-├── protocol/             37 ACTION definitions, Token Information Standard, schemas
+├── protocol/             38 ACTION definitions, Token Information Standard, schemas
 ├── operations/           deployment, Docker, monitoring, upgrades, troubleshooting
 ├── legal/                licensing, commercial license, trademark, contributor agreement
 ├── blockchains.md        supported chains, adding new blockchains

README.md

@@ -3,7 +3,7 @@
 
 # XChain Platform
 
-A blockchain-agnostic token protocol currently running on Bitcoin, Litecoin, and Dogecoin. Create, transfer, trade, and manage tokens, run smart contracts that can call out to AI models and the web, and stake for validation using 37 ACTION commands, 36 of them embedded directly in standard blockchain transactions. No sidechains, no bridges, no separate consensus mechanism. The platform includes a built-in DEX, a sandboxed JavaScript virtual machine for on-chain smart contracts, cross-chain swap support, and **cryptographically secure token-gated file publishing**: encrypt single files or multi-file packs on-chain so only holders of a specific token can decrypt them (see [Token-Gated Content](./protocol/token-gated-content.md)). The platform can be extended to run on any Bitcoin-compatible blockchain, including private blockchains for enterprise deployments.
+A blockchain-agnostic token protocol currently running on Bitcoin, Litecoin, and Dogecoin. Create, transfer, trade, and manage tokens, run smart contracts that can call out to AI models and the web, and stake for validation using 38 ACTION commands, 37 of them embedded directly in standard blockchain transactions. The `XBRIDGE` action moves supply between XChain's own ledgers under lock-and-mint / burn-and-release custody of the hub federation, with no separate consensus mechanism and no external bridge. The platform includes a built-in DEX, a sandboxed JavaScript virtual machine for on-chain smart contracts, cross-chain swap support, and **cryptographically secure token-gated file publishing**: encrypt single files or multi-file packs on-chain so only holders of a specific token can decrypt them (see [Token-Gated Content](./protocol/token-gated-content.md)). The platform can be extended to run on any Bitcoin-compatible blockchain, including private blockchains for enterprise deployments.
 
 **New here?** Start with [What is XChain?](./getting-started/what-is-xchain.md) or jump straight to the [Developer Quickstart](./getting-started/quickstart-developer.md).
 

architecture/component-map.md

@@ -51,7 +51,7 @@ See [`../components/decoder/`](../components/decoder/) for full documentation.
 | | |
 |---|---|
 | **Purpose** | Reads decoded ACTIONs from the Decoder DB, validates them, executes business logic, writes final state |
-| **Inputs** | Decoder MariaDB (SQL polling every 5 seconds); local Hub DB (cross-chain price data); inbound JSON-RPC `pushvalidatorrewards` from xchain-hub |
+| **Inputs** | Decoder MariaDB (SQL polling every 5 seconds); local Hub DB (cross-chain price data); inbound JSON-RPC `pushvalidatorrewards` from xchain-hub (retired for new anchor rewards, which each indexer now derives from the on-chain ANCHOR bytes) |
 | **Outputs** | Indexer MariaDB (`XChain_{CHAIN}_{NETWORK}_Indexer`); outbound JSON-RPC pushes to xchain-hub (`pushchaintip`, `pushpriceround`, `pushoracleprice`) |
 | **Storage** | Three database connections: Decoder DB (read), Indexer DB (read/write, 100+ tables), local Hub DB (read, synced from xchain-hub) |
 | **Communication** | Outbound SQL reads from Decoder DB and local Hub DB; outbound HTTP/WebSocket to xchain-hub; inbound JSON-RPC API for hub pushes |
@@ -78,10 +78,10 @@ See [`../components/indexer/`](../components/indexer/) for full documentation.
 | | |
 |---|---|
 | **Purpose** | Serves REST endpoints, JSON-RPC 2.0, and a web UI over the Indexer DB |
-| **Inputs** | Indexer MariaDB (direct SQL reads); xchain-hub (config sync every 60s) |
+| **Inputs** | Indexer MariaDB (direct SQL reads); Decoder MariaDB (raw transaction lookups); xchain-hub (config sync every 60s, plus the hub-mirror snapshot and live feed under `self_sync`) |
 | **Outputs** | HTTP responses (REST, JSON-RPC, HTML) |
-| **Storage** | None (stateless read layer) |
-| **Communication** | Inbound HTTP from clients; outbound SQL to Indexer DB; outbound JSON-RPC to xchain-hub |
+| **Storage** | A hub-mirror schema it owns (created and written under `"self_sync": true`); otherwise a read layer over indexed state |
+| **Communication** | Inbound HTTP from clients; outbound SQL to Indexer and Decoder DBs; DDL and row writes to its own hub-mirror DB; outbound JSON-RPC to xchain-hub |
 
 Key technical details:
 
@@ -143,7 +143,7 @@ These services support the construction and submission of XChain transactions.
 
 Key technical details:
 
-- With `encoding` omitted, selects between `OP_RETURN` (≤80 bytes/output, 76 bytes user data, 1 tx) and `P2SH` (476 bytes/chunk, 2 tx) by payload size. `MULTISIGN` (~61 bytes/key, 1 tx), `P2WSH` (476 bytes/chunk up to the 8,192-byte compiled-payload ceiling, 2 tx) and `TAPROOT` (the envelope, up to 390,000 bytes in one tapscript witness, 2 tx, segwit chains only) are never reached by that size fallback; they are used only when explicitly requested, or when `encoding: AUTO` opts into smallest-footprint selection.
+- With `encoding` omitted, selects between `OP_RETURN` (≤80 bytes/output, 76 bytes user data, 1 tx) and `P2SH` (476 bytes/chunk, 2 tx) by payload size. `MULTISIGN` (60 bytes/output, 1 tx), `P2WSH` (476 bytes/chunk up to the 8,192-byte compiled-payload ceiling, 2 tx) and `TAPROOT` (the envelope, up to 390,000 bytes in one tapscript witness, 2 tx, segwit chains only) are never reached by that size fallback; they are used only when explicitly requested, or when `encoding: AUTO` opts into smallest-footprint selection.
 - P2SH and P2WSH use a two-transaction pattern: fund tx commits funds to a script; reveal tx spends it, embedding the data in the unlocking script. TAPROOT uses a commit/reveal pair returned together from one call.
 - Obfuscates payloads with AES-128-CTR. Key and IV are derived from the first input's txid, deterministic and reversible by any party with the txid.
 - Available as a Node.js JSON-RPC service and as a browser bundle via webpack.
@@ -167,7 +167,7 @@ Key technical details:
 
 - LevelDB key schema uses single-character prefixes: `B`=block, `T`=transaction, `I`=input, `O`=output, `H`/`J`=address hints.
 - Processes blocks in batches of up to 200 (flush may trigger earlier under heap pressure), writing each batch atomically to LevelDB.
-- Maintains a per-chain undo window (BTC: 12 / LTC: 48 / DOGE: 120 blocks, overridable via XCHAIN_UNDO_BLOCKS_<COIN>) to support chain reorganization rollback.
+- Maintains a per-chain, per-network undo window (mainnet and regtest: BTC 12 / LTC 120 / DOGE 120 blocks; testnet: 120 blocks for every coin; overridable via XCHAIN_UNDO_BLOCKS_<COIN>) to support chain reorganization rollback.
 - Tracks the mempool for real-time unconfirmed UTXO state.
 - Supports bootstrap from tar archives to avoid re-indexing from genesis.
 - Outputs are indexed by scriptPubKey hash, enabling efficient address lookups.
@@ -189,7 +189,7 @@ See [`../components/utxo-tracker/`](../components/utxo-tracker/) for full docume
 
 Key technical details:
 
-- Exposes 31 action construction methods (one per developer-invocable ACTION type) and 118 explorer query wrappers.
+- Exposes 32 action construction methods (one per developer-invocable ACTION type) and 118 explorer query wrappers.
 - Batch builder allows multiple actions to be combined into a single `BATCH` action string.
 - Discovers service endpoints via xchain-hub.
 - Implements retry with exponential backoff and connection pooling for all outbound calls.