Source map, reference coverage and verification
Documentation index. This map organizes the two implementations by responsibility and ties their public behavior to the corresponding reference. It is a documentation review and reproducible surface inventory, not a new security audit or a certification that every code path was executed.
1. Exact source baselines
- Public node source:
418926f90f9b85af66f4ea4b0cc060dce6cdc862on XGR3.0, with v3.4.0 execution code. Release tagv3.4.0points tocbe6f8a4ae1718429a9924dcf87f0d28591d74e1. - Public Interchain source/deployment snapshot:
9518472c04432c57a5939a3688e90be332180636on main. Contract suffixes and helper package versions are independent interface/tool versions. - Subsequent Interchain commit
200f636c37cd55c4476f3b5a349fcceb715066d2adds the read-only sponsor-obligation monitor and disposable-PostgreSQL tests. Its source/procedure was reviewed while preparing this correction; it does not replace the protocol/deployment snapshot above. F-07/F-19 remain open. - XGR and organization-profile READMEs link these references. MCP is a separately versioned client/service; this documentation update does not modify its implementation.
- Private development repositories are not an alternative source authority. Historical audit records are unchanged.
2. Module-to-document mapping
| Source module | Responsibilities | Detailed reference |
|---|---|---|
| xgr-interchain/contracts | Protocol/identity, Factory/Registry, guarded routers, Gateway/FeeVault, transport, Direct-BLS ISM, membership/BLS, optional commercial adapter | Contract_Reference, Contract_API |
| xgr-interchain/runtime/native-relayer | Original receipt/finality verification, canonical codecs, unsigned recovery, optional watcher/executor, gas planning | v3.4.0_Operations, Security_Model |
| xgr-interchain/script | Shared infrastructure deployment scripts and reviewed constructor/build inputs | Deployment_Reference, Services |
| xgr-interchain/config | Approved application manifests: chains, assets/routes, publication and defaults; prospect does not mean active node support | Asset_Bridge, Deployment_Reference |
| xgr-interchain/deployments | Append-only receipts, shared addresses, representations and directed Gateway/FeeVault records | Deployment_Reference, Contract_Reference |
| xgr-interchain/services/admin | Main gate, chain/asset planners, artifact verification, wallet intents, journals, reconciliation, receipt auto-sync, operations health | Services, Deployment_Reference |
| xgr-interchain/services/indexer | Canonical transfer index, reorg handling, discovery/intake, proof job leases, read proxy, TVL/flow/history/publication | Services, v3.4.0_Operations |
| xgr-interchain/services/managed-relay | Commercial quote/tax evidence, price cache, immutable sponsor commitments, grant budgets/nonces/reconciliation, fee claims and optional executor | Services, Contract_Reference |
| xgr-interchain/services/onboarding | Manifest proposals, live original-token identity checks, private confirmation storage, mail/publisher/status notifications | Services, Asset_Bridge |
| xgr-interchain/apps/web | Wallet selection, quotes/actions/nonces, original transfer discovery, recovery/worklists, catalog visibility, rankings and SPA rendering | Services, v3.4.0_Operations |
| xgr-interchain/tools | Manifest/catalog validation, bootstrap/receipt/route readiness tools, narrow reverse-proxy and installation generators | Services, Deployment_Reference |
| xgr-interchain/.github/workflows | Validation, contract tests/review, Join checks and BLS receipt workflows | Source_Map, Deployment_Reference |
| xgr-node/interchain/config.go | Compiled physical network identity, finality, Registry/RPC/operator pinning and one-active-Registry invariant | Validator_Runtime, Security_Model |
| xgr-node/consensus/ibft/interchain | Canonical Direct-BLS, identity, membership, fee payloads and aggregate quorum verification | Security_Model, Contract_Reference |
| xgr-node/interchain/runtime | Lifecycle, source discovery/catalog/P2P, grouped scans, retries, signing, archive/quorum hints, source fee execution, storage and health | Validator_Runtime, RPC |
| xgr-node/interchain/evm | Native/local and remote evidence, finality, independent witness agreement, route/fee/binding reads, BLS format, transaction submission and failover | Security_Model, Validator_Runtime |
| xgr-node/interchain/verification | Verification helpers and their regression coverage | Security_Model, Validator_Runtime |
| xgr-node/command/ibft/interchain | Bootstrap proof, membership activation, source fee create/approve/execute, read-only storage diagnostics | CLI, RPC |
| xgr-node/jsonrpc | Actual RPC endpoint implementation, explicit-set archives, request/progress queues, validators, governance and schema-2 health | RPC, Validator_Runtime |
| xgr-node/command | Entire registered node CLI, server, secrets, consensus/staking, peers, txpool, backup/regenesis and diagnostics | CLI, Source_Map |
| xgr-node/consensus/ibft | Native local chain read/submission integration and ordinary consensus; distinguish Interchain worker from weighted block consensus | Validator_Runtime, Source_Map |
| xgr-node/state | Chain execution/accounting and state storage; v3.4.0 consensus gate and transaction-local SSTORE context are separate from message format | Security_Model, Source_Map |
The ordinary node chain/consensus/storage/PoS/networking documentation retains its own scope in the chain index. The complete node CLI enumerates all registered commands and flags. This Interchain map does not replace the broader chain specification with bridge-only prose.
3. Generated interface and deployment coverage
- Declared contract API: every production top-level Solidity source, excluding test mocks; all named public/external functions, events and custom errors. Inherited ABI and generated getters are additional compiler output.
- Node CLI: 46 command/help entries obtained from a fresh build, including all application command families; command bodies were not run during help collection.
- Interchain RPC: all eight current Interchain method names, ordered parameters, result fields, progress states, explicit-set archive and errors. Compatibility reads are distinguished from active processing hints.
- Deployment inventory: shared contracts on three supported chains, two canonical assets with three representations each, and eight directed route records. Sixty recorded component/representation/route references were checked against receipt identity/runtime-hash fields.
- Independent runbook: source preparation, allowance, wallet submission, original receipt/finality, current-set unsigned recovery, destination submission and recipient/deferred-claim checks.
4. Reproduce the repository inventory
Run from each reviewed checkout. This includes tracked application source and configuration, while excluding vendored dependencies and immutable audit artifacts from the implementation inventory. It is a file inventory, not proof of line-by-line audit.
git rev-parse HEAD
rg --files -g '*.go' -g '*.sol' -g '*.mjs' -g '*.js' -g '*.sh' -g '*.json' -g '*.sql' -g '*.yml' -g '*.yaml' -g '!lib/**' -g '!vendor/**' -g '!node_modules/**' -g '!**/node_modules/**' -g '!audits/**' -g '!audit/**'
When adding a module or public method, update this map, its behavioral reference, CLI/RPC/ABI surface where applicable, examples and validation evidence. Do not update a release label while retaining incompatible old method/field descriptions.
5. Deterministic tests and their meaning
| Area | Existing test source / invocation | Evidence limit |
|---|---|---|
| Canonical signing bytes, identity and quorum | node consensus/ibft/interchain/*_test.go |
Vectors and negative cases; not a live quorum deployment |
| Independent evidence/finality/failover | node interchain/evm/*_test.go |
Mock/native readers and inconsistent witness rejection; not proof of real endpoint availability |
| Grouped scans, retries and persistence | node interchain/runtime/*_test.go |
Bounded windows, journal/restart logic and identity checks; not production catch-up timing |
| CLI/RPC | node command/ibft/interchain, jsonrpc tests; fresh CLI help |
Parsing, storage/schema/error behavior; not wallet execution |
| Contract behavior | Interchain test/, configured Foundry workflow |
Local contract invariants and simulations; not all deployed cross-chain transfers |
| Recovery codecs and receipts | runtime/native-relayer/*.test.mjs |
Canonical metadata, original receipt/finality and gas calculations |
| Website/admin/indexer/services | component *.test.mjs, *.test.js, tools tests |
Tested application policies/fixtures; no assumed production enablement |
Reproducible node invocation:
go test ./consensus/ibft/interchain ./command/ibft/interchain ./jsonrpc ./interchain/...
Reproducible helper checks after installing the package-declared dependencies:
cd runtime/native-relayer
npm install --ignore-scripts
npm test
The broader repository CI retains its configured contract, web, service and manifest checks. A documentation-only PR does not weaken or skip those gates. Live network transfer, full node sync across the consensus fork, real endpoint failover, three-validator restart/recovery and commercial service rollout require separately recorded chain/service evidence. None is inferred from a green documentation or unit check.
6. Known boundaries that must remain visible
- One active ValidatorRegistry per physical chain is an operating invariant; membership payloads retain the accepted cross-Registry replay limitation. Message ISM binding is not a fix for that separate domain.
- Node grouped observation retains per-route durable cursors. The old one-source-cursor acceptance target is not described as implemented.
- Pending attestation cache cleanup can occur after 30 days only when complete original evidence can be reverified for regeneration; source principal does not expire.
- The optional paid executor currently configures XGRChain/Base paid sources explicitly; public protocol/quote catalog coverage does not make that worker generic for every chain.
- Native successful message delivery can reserve a beneficiary claim when immediate payment fails; balances and claim state must be checked.
- Recorded deployments, implementation presence, server installation and live end-to-end readiness are different evidence levels.
7. Validation of this documentation correction
A fresh public-node build succeeded. The protocol, Interchain CLI, JSON-RPC and all interchain/... package tests passed. All 14 public native-recovery helper tests passed, including cross-language signing/metadata vectors and receipt/finality cases. The seven JavaScript runbook blocks passed syntax checking; they were not broadcast to live chains. Changed Markdown links and receipt-reference consistency were checked locally. Repository PR checks remain an additional merge gate.
Follow-up review on 2026-10-27
The follow-up checked the system-context inventory against all 21 top-level production Solidity files and validated 131 local Markdown file targets in the Interchain documentation. The caller-authority matrix was checked against Factory registration, router bootstrap/outbound guards, source-fee quorum execution, FeeVault accounting, native beneficiary withdrawal and commercial gateway administration/claims. claimFees() is permissionless to invoke but has a fixed current-service-wallet payee. Storage counters were removed from the RPC reference because they belong to the local CLI command.
The fetched public node branch had no Go-source differences from the documented checkout. The Interchain documentation branch was synchronized with public main, including the previously documented read-only sponsorship monitor; its five deterministic monitor tests passed in this follow-up. PostgreSQL integration, live transfers and the earlier full node/helper suites were not rerun for these Markdown changes. Historical test results in the preceding paragraph describe the earlier correction run, not new execution in this follow-up.