feat(xdc-zero): Chain 138 bridge runbook, config fragments, merge helper

- Add CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK and 07-ccip pointer doc - Add config/xdc-zero templates, parent register fragment, README - Add merge-endpointconfig-chain138.sh (jq merge, XDC_ZERO_ENDPOINT_DIR) - Add xdc-zero-chain138-preflight.sh; trim XDC URL vars in load-project-env - Wire AGENTS.md, MASTER_INDEX, verify README, .env.master.example Made-with: Cursor
2026-03-31 23:10:36 -07:00
parent f411a89908
commit 6390174bb7
14 changed files with 354 additions and 1 deletions
--- a/.env.master.example
+++ b/.env.master.example
@@ -115,6 +115,13 @@ PINATA_API_SECRET=
 PRIVATE_KEY=
 RPC_URL_138=
 RPC_URL_138_PUBLIC=
+# XDC Zero — second relayer pair (XDC Network mainnet <-> Chain 138). See docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md and config/xdc-zero/
+# Use XDC mainnet JSON-RPC only (chain id 50), not Ethereum L1. Default:
+XDC_PARENTNET_URL=https://rpc.xinfin.network
+# Testnet (Apothem): https://rpc.apothem.network
+# Optional alias for 138 side (defaults to RPC_URL_138 in preflight if unset):
+XDC_ZERO_PEER_RPC_URL=
+
 # Ethereum L1 — used for dual-anchor attestation with scripts/omnl/omnl-chain138-attestation-tx.sh (consumes ETH gas). Alias: RPC_URL_MAINNET.
 ETHEREUM_MAINNET_RPC=
 CHAIN_651940_RPC_URL=
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,6 +32,7 @@ Orchestration for Proxmox VE, Chain 138 (`smom-dbis-138/`), explorers, NPMplus,
 | Portal Keycloak OIDC secret on CT 7801 | After client exists: `./scripts/deployment/sankofa-portal-merge-keycloak-env-from-repo.sh` (needs `KEYCLOAK_CLIENT_SECRET` in repo `.env`; base64-safe over SSH) |
 | Sankofa corporate web → CT 7806 | Provision: `./scripts/deployment/provision-sankofa-public-web-lxc-7806.sh`. Sync: `./scripts/deployment/sync-sankofa-public-web-to-ct.sh`. systemd: `config/systemd/sankofa-public-web.service`. Set `IP_SANKOFA_PUBLIC_WEB` in `.env`, then `scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh` |
 | CCIP relay (r630-01 host) | Unit: `config/systemd/ccip-relay.service` → `/etc/systemd/system/ccip-relay.service`; `systemctl enable --now ccip-relay` |
+| XDC Zero + Chain 138 (parallel to CCIP) | `docs/07-ccip/XDC_ZERO_CHAIN138.md`, `docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md`, `config/xdc-zero/`; `bash scripts/verify/xdc-zero-chain138-preflight.sh`; `XDC_ZERO_ENDPOINT_DIR=.../XDC-Zero/endpoint bash scripts/xdc-zero/merge-endpointconfig-chain138.sh --dry-run` — **XDC mainnet RPC:** `https://rpc.xinfin.network` (not Ethereum); Hardhat `chain138` in XDC-Zero `endpoint/` uses `RPC_URL_138` |
 | Wormhole protocol (LLM / MCP) vs Chain 138 facts | Wormhole NTT/Connect/VAAs/etc.: `docs/04-configuration/WORMHOLE_AI_RESOURCES_LLM_PLAYBOOK.md`, mirror `scripts/doc/sync-wormhole-ai-resources.sh`, MCP `mcp-wormhole-docs/` + `docs/04-configuration/MCP_SETUP.md`. **Chain 138 addresses, PMM, CCIP:** repo `docs/11-references/` + `docs/07-ccip/` — not Wormhole bundles. Cursor overlay: `.cursor/rules/wormhole-ai-resources.mdc`. |
 | TsunamiSwap VM 5010 check | `./scripts/deployment/tsunamiswap-vm-5010-provision.sh` (inventory only until VM exists) |
 | The Order portal (`https://the-order.sankofa.nexus`) | OSJ management UI (secure auth); source repo **the_order** at `~/projects/the_order`. NPM upstream defaults to **order-haproxy** CT **10210** (`IP_ORDER_HAPROXY:80`); use `THE_ORDER_UPSTREAM_*` to point at the Sankofa portal if 10210 is down. Provision HAProxy: `scripts/deployment/provision-order-haproxy-10210.sh`. **`www.the-order.sankofa.nexus`** → **301** apex (same as www.sankofa / www.phoenix). |
--- a/config/xdc-zero/README.md
+++ b/config/xdc-zero/README.md
@@ -0,0 +1,18 @@
+# XDC Zero + Chain 138 — config templates
+
+Templates for pairing **DBIS Chain 138** with **XDC Network mainnet** JSON-RPC (`https://rpc.xinfin.network`, chain id 50) or Apothem/devnet, using the [XDC-Zero](https://github.com/XinFinOrg/XDC-Zero) Endpoint pattern, **without** replacing your existing subnet↔parent XDC-Relayer deployment.
+
+| File | Purpose |
+|------|---------|
+| [`xdc-zero-chain138-pair.example.env`](xdc-zero-chain138-pair.example.env) | Env vars for the **second** relayer pair (parent ↔ 138). Copy to a secure path; wire into XinFin relayer/docker or your own CSC updater. |
+| [`network.config.xdc-mainnet.example.json`](network.config.xdc-mainnet.example.json) | Example `network.config.json` for XDC-Zero `endpoint/`: **XDC mainnet** `https://rpc.xinfin.network` + LAN Chain 138. Merge or copy keys into your clone. |
+| [`endpointconfig.fragment.chain138.example.json`](endpointconfig.fragment.chain138.example.json) | Top-level **`chain138`** block to **merge** into XDC-Zero `endpointconfig.json`. Also **append** one object to existing `xdcparentnet.registers[]` for peer chain id 138 (see runbook). |
+| [`xdcparentnet-register-chain138.fragment.json`](xdcparentnet-register-chain138.fragment.json) | Single **`registers[]`** entry (chain id **138**) consumed by the merge helper for `xdcparentnet`. Replace zero addresses after CSC/Endpoint deploy. |
+
+**Merge helper (repo):** `bash scripts/xdc-zero/merge-endpointconfig-chain138.sh` (requires `jq`).
+
+**Canonical procedure:** [docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md](../../docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md)
+
+**Preflight:** `bash scripts/verify/xdc-zero-chain138-preflight.sh`
+
+Upstream repos (clone separately): [XDC-Zero](https://github.com/XinFinOrg/XDC-Zero), [XDC-CSC](https://github.com/XinFinOrg/XDC-CSC), [XDC-Relayer](https://github.com/XinFinOrg/XDC-Relayer).
--- a/config/xdc-zero/endpointconfig.fragment.chain138.example.json
+++ b/config/xdc-zero/endpointconfig.fragment.chain138.example.json
@@ -0,0 +1,13 @@
+{
+  "chain138": {
+    "endpoint": "0x0000000000000000000000000000000000000000",
+    "registers": [
+      {
+        "chainId": 50,
+        "csc": "0x0000000000000000000000000000000000000000",
+        "endpoint": "0x0000000000000000000000000000000000000000"
+      }
+    ],
+    "applications": []
+  }
+}
--- a/config/xdc-zero/network.config.xdc-mainnet.example.json
+++ b/config/xdc-zero/network.config.xdc-mainnet.example.json
@@ -0,0 +1,5 @@
+{
+  "xdcsubnet": "http://localhost:8545",
+  "xdcparentnet": "https://rpc.xinfin.network",
+  "chain138": "http://192.168.11.211:8545"
+}
--- a/config/xdc-zero/xdc-zero-chain138-pair.example.env
+++ b/config/xdc-zero/xdc-zero-chain138-pair.example.env
@@ -0,0 +1,57 @@
+# XDC Zero — second relayer pair: XDC parent ↔ Chain 138
+# Copy to e.g. .env.xdc-zero-138 (gitignored) or secrets store. Do not commit real keys.
+#
+# Stock XinFin relayer uses PARENTNET_URL + SUBNET_URL for TWO chains only.
+# For 138 pairing, treat Chain 138 as the "subnet" side in env names ONLY if you
+# run a dedicated second relayer instance (leave your original subnet↔parent instance untouched).
+
+# --- XDC Network "parent" side (pick ONE profile) ---
+# Mainnet: XDC Network JSON-RPC only (chain id 50). Official:
+XDC_PARENTNET_URL=https://rpc.xinfin.network
+# Testnet (Apothem):
+# XDC_PARENTNET_URL=https://rpc.apothem.network
+# Devnet shortcut (XDC-Zero cicd accepts aliases):
+# XDC_PARENTNET_URL=devnet
+# XDC_PARENTNET_URL=testnet
+
+# --- Chain 138 (Besu) — deploy + proof source ---
+# Prefer same vars as rest of repo (load-project-env strips CR/LF on these):
+RPC_URL_138=http://192.168.11.211:8545
+# Public mirror (read-only checks OK; deploy from LAN when possible):
+# RPC_URL_138=https://rpc-http-pub.d-bis.org
+
+# Relayer naming (XinFin docker / common.env): this process pairs TWO URLs only.
+# Set both to the same values as XDC_PARENTNET_URL and RPC_URL_138 respectively:
+PARENTNET_URL=
+SUBNET_URL=
+
+# --- Keys (relayer / deploy wallets) — separate from subnet↔parent relayer ---
+PARENTNET_PK=
+SUBNET_PK=
+# Aliases some scripts use:
+# PARENTNET_WALLET_PK=
+# XDC_ZERO_138_PAIR_PARENT_PK=
+# XDC_ZERO_138_PAIR_PEER_PK=
+
+# --- New CSC addresses for THIS pair only (deploy per runbook) ---
+# On parent: stores Chain 138 block roots (for verifying messages from 138).
+CHECKPOINT_CONTRACT_138_ON_PARENT=
+# On Chain 138: stores parent block roots (for verifying messages from parent).
+REVERSE_CHECKPOINT_CONTRACT_PARENT_ON_138=
+
+# XinFin stock env names (subset of cicd/.env.example) — map to the above when running stock scripts:
+# CHECKPOINT_CONTRACT -> CHECKPOINT_CONTRACT_138_ON_PARENT (138 roots on parent)
+# REVERSE_CHECKPOINT_CONTRACT -> REVERSE_CHECKPOINT_CONTRACT_PARENT_ON_138 (parent roots on 138)
+
+# --- Deployed XDC Zero Endpoint addresses (after Hardhat deploy) ---
+PARENTNET_ZERO_CONTRACT=
+SUBNET_ZERO_CONTRACT=
+# Clearer aliases for operators:
+XDC_ZERO_ENDPOINT_ON_PARENT=
+XDC_ZERO_ENDPOINT_ON_138=
+
+# --- Optional: extra public mainnets for operator verification (preflight only) ---
+# Already supported in load-project-env.sh — not used by XDC-Relayer unless you add another stack.
+# ETHEREUM_MAINNET_RPC=https://eth.llamarpc.com
+# BSC_RPC_URL=
+# POLYGON_MAINNET_RPC=
--- a/config/xdc-zero/xdcparentnet-register-chain138.fragment.json
+++ b/config/xdc-zero/xdcparentnet-register-chain138.fragment.json
@@ -0,0 +1,7 @@
+[
+  {
+    "chainId": 138,
+    "csc": "0x0000000000000000000000000000000000000000",
+    "endpoint": "0x0000000000000000000000000000000000000000"
+  }
+]
--- a/docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md
+++ b/docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md
@@ -0,0 +1,77 @@
+# Chain 138 + XDC Zero Endpoint (XDC Network mainnet RPC + optional testnet)
+
+**Last updated:** 2026-03-31  
+**Purpose:** Register **DBIS Chain 138** as an additional peer in the [XDC-Zero](https://github.com/XinFinOrg/XDC-Zero) pattern while keeping **stock XDC-CSC + XDC-Relayer** semantics: reuse `IFullCheckpoint.getRoots` and a **dedicated second** relayer/oracle process for the **parent ↔ 138** pair. **Do not** repoint or tear down an existing XDC **subnet ↔ parent** relayer.
+
+**XDC mainnet:** Use **XDC Network** JSON-RPC — default `https://rpc.xinfin.network` (chain id **0x32 / 50**). This is **not** Ethereum mainnet RPC (`ETHEREUM_MAINNET_RPC` is unrelated to the XDC-Relayer parent URL).
+
+**Audience:** Operators and integration engineers with access to Chain 138 RPC, XDC RPC, and deployer keys.
+
+**Templates:** [`config/xdc-zero/README.md`](../../config/xdc-zero/README.md)  
+**Preflight:** `bash scripts/verify/xdc-zero-chain138-preflight.sh`
+
+---
+
+## 1. XDC parent RPC (mainnet default)
+
+| Profile | Set `PARENTNET_URL` / `XDC_PARENTNET_URL` to | Notes |
+|---------|-----------------------------------------------|--------|
+| **XDC mainnet (default)** | `https://rpc.xinfin.network` | Official XDC Network HTTP JSON-RPC. Production: fund relayer with **XDC** for CSC txs. Alternate enterprise mirror OK if XinFin-approved. |
+| **Apothem (testnet)** | `https://rpc.apothem.network` | Lower risk for spikes; not mainnet. |
+| **Devnet shortcuts** | `devnet` / `testnet` strings | XDC-Zero `cicd` maps these to Apothem-style URLs — confirm before production. |
+
+**Chain 138:** Prefer LAN deploy RPC (`RPC_URL_138` from project dotenv, e.g. Core Besu). For monitoring from outside LAN, use a controlled public RPC (e.g. `rpc-http-pub.d-bis.org`) if policy allows.
+
+**Other public mainnets (Ethereum, BSC, etc.):** They are **not** part of stock XDC-Relayer. This runbook does not mix them into one relayer process. If you later add **separate** Zero-style pairs (e.g. 138 ↔ Ethereum), treat each as **another** two-URL relayer/CSC stack and document it independently. Repo dotenv already supports `ETHEREUM_MAINNET_RPC` etc. for **verification** and CCIP workflows — use [`xdc-zero-chain138-preflight.sh`](../../scripts/verify/xdc-zero-chain138-preflight.sh) optional checks.
+
+---
+
+## 2. Topology (what you are adding)
+
+- **Unchanged:** existing **subnet ↔ parent** Endpoints, CSCs, and relayer.
+- **New:**  
+  - **Endpoint + trie libraries** on Chain 138 (same deploy path as upstream `endpoint/scripts/endpointdeploy.js`).  
+  - **CSC on parent** storing **138** block roots.  
+  - **CSC on 138** storing **parent** block roots.  
+  - **Second** relayer (or minimal CSC updater with same ABI) with `PARENTNET_URL` + `SUBNET_URL` = parent + 138 RPC.  
+  - **`registerChain` on both** parent Endpoint and 138 Endpoint, then **approveApplication** for your apps.
+
+**`registerChain(chainId, csc, remoteEndpoint)`** (on a given chain): `chainId` = peer’s chain id; `csc` = checkpoint **on this chain** for the **peer’s** blocks; `remoteEndpoint` = peer’s Endpoint contract.
+
+---
+
+## 3. Ordered steps (summary)
+
+1. **Spike:** Run stock or built-from-source **XDC-Relayer** against 138 RPC + chosen parent RPC with **throwaway** CSCs; confirm JSON-RPC and block/header handling (Besu vs XDC subnet client expectations).
+2. **Deploy on 138:** `EthereumTrieDB` → `MerklePatricia` → `Endpoint`; record addresses; transfer `Ownable` to production admin/multisig.
+3. **Deploy CSCs:** Parent-side CSC for 138 roots; 138-side CSC for parent roots (prefer **stock XDC-CSC** contracts if compatible).
+4. **Merge config:** In your XDC-Zero clone, `endpoint/` supports Hardhat network **`chain138`** (uses `RPC_URL_138` or `network.config.json` → `chain138`). For **XDC mainnet** URLs, align `xdcparentnet` with [`config/xdc-zero/network.config.xdc-mainnet.example.json`](../../config/xdc-zero/network.config.xdc-mainnet.example.json). Merge `endpointconfig.json` with repo fragments (top-level `chain138` + append `xdcparentnet.registers` for chain id **138**):  
+   `XDC_ZERO_ENDPOINT_DIR=/path/to/XDC-Zero/endpoint bash scripts/xdc-zero/merge-endpointconfig-chain138.sh --dry-run`  
+   then the same command without `--dry-run` (backs up the file). Or pass the file explicitly: `bash scripts/xdc-zero/merge-endpointconfig-chain138.sh /path/to/endpointconfig.json --dry-run`. Replace placeholder addresses in [`config/xdc-zero/`](../../config/xdc-zero/) (or edit merged JSON) after CSC/Endpoint deploy. **Do not** run `endpointandregisterchain.js` unmodified after manual merge — it overwrites JSON for two networks only.
+5. **Register chains:** Owner calls `registerChain` on parent and on 138.
+6. **Apps:** Deploy SUA/RUA (or Subswap) on both sides; fill `applications`; run `registerapplications.js` (or multisig) on **both** chains.
+7. **Operate second relayer:** Env from [`config/xdc-zero/xdc-zero-chain138-pair.example.env`](../../config/xdc-zero/xdc-zero-chain138-pair.example.env); point `CHECKPOINT_CONTRACT` / `REVERSE_CHECKPOINT_CONTRACT` at the **new** CSCs only.
+8. **E2E:** Send/receive one packet with real proofs; monitor `getRoots` lag.
+
+---
+
+## 4. Subnet ↔ 138 (optional)
+
+If **XDC subnet** apps must talk to **138** directly (not via parent), you need **additional** CSC pairs and `registerChain` on the **subnet** Endpoint plus another relayer process or routing policy. Default scope of this runbook is **parent ↔ 138** only.
+
+---
+
+## 5. Security and compliance
+
+- Relayer keys: **separate** from subnet↔parent relayer; fund for gas on **both** chains.  
+- **Never** use test `SimpleCsc` open `setRoots` in production.  
+- RPC: restrict by firewall/VPN; mainnet RPC URLs should be operator-approved endpoints.  
+- Record deployed addresses in [`docs/11-references/`](../../docs/11-references/) or internal CMDB when stable.
+
+---
+
+## 6. References
+
+- XDC-Zero: `endpoint/README.md`, `cicd/README.md` (clone locally).  
+- CCIP / Chain 138 (parallel path): [docs/07-ccip/](07-ccip/), [docs/11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md](../11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md).  
+- Chain 138 RPC / operator context: [AGENTS.md](../../AGENTS.md), [docs/04-configuration/ALL_VMIDS_ENDPOINTS.md](../04-configuration/ALL_VMIDS_ENDPOINTS.md).
--- a/docs/07-ccip/XDC_ZERO_CHAIN138.md
+++ b/docs/07-ccip/XDC_ZERO_CHAIN138.md
@@ -0,0 +1,11 @@
+# XDC Zero + Chain 138 (pointer)
+
+**Purpose:** Cross-chain messaging via [XDC-Zero](https://github.com/XinFinOrg/XDC-Zero) Endpoint + CSC + relayer — **parallel** to CCIP/Wormhole-style bridges documented elsewhere in this folder.
+
+**Canonical runbook:** [../03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md](../03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md)
+
+**Config templates:** [`../../config/xdc-zero/`](../../config/xdc-zero/)
+
+**Scripts:** `bash scripts/verify/xdc-zero-chain138-preflight.sh` · `bash scripts/xdc-zero/merge-endpointconfig-chain138.sh`
+
+**XDC mainnet RPC:** `https://rpc.xinfin.network` (chain id 50) — set as `XDC_PARENTNET_URL` / `xdcparentnet` in `network.config.json`; not Ethereum L1.
--- a/docs/MASTER_INDEX.md
+++ b/docs/MASTER_INDEX.md
@@ -80,7 +80,7 @@
 | **04-configuration** | [04-configuration/README.md](04-configuration/README.md), [04-configuration/naming-conventions/README.md](04-configuration/naming-conventions/README.md) (UTRNF + DBIS token/bridge naming), [04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md](04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md) (paths, registry, token-mapping, LiFi/Jumper), [04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md](04-configuration/GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md) (canonical `c* V2` standards, facet mapping, migration plan), [04-configuration/GRU_STANDARDS_PROFILE.md](04-configuration/GRU_STANDARDS_PROFILE.md) and [`../config/gru-standards-profile.json`](../config/gru-standards-profile.json) (machine-readable x402, EIP/ERC, transport, governance, and ISO-4217-plus standards profile), [04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md](04-configuration/GRU_STORAGE_GOVERNANCE_AND_SUPERVISION_STANDARD.md) and [`../config/gru-governance-supervision-profile.json`](../config/gru-governance-supervision-profile.json) (deterministic storage namespaces, jurisdiction-aware proposal review, supervision metadata, and upgrade notice periods), [04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md](04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md) (end-to-end FX currency attachment), [`../config/gru-iso4217-currency-manifest.json`](../config/gru-iso4217-currency-manifest.json) (machine-readable supported currency manifest); **info.defi-oracle.io (Chain 138 hub SPA):** [04-configuration/INFO_DEFI_ORACLE_IO_DEPLOYMENT.md](04-configuration/INFO_DEFI_ORACLE_IO_DEPLOYMENT.md), app [info-defi-oracle-138/README.md](../info-defi-oracle-138/README.md); **Chain 138 wallets:** [04-configuration/CHAIN138_WALLET_CONFIG_VALIDATION.md](04-configuration/CHAIN138_WALLET_CONFIG_VALIDATION.md); **Chain 2138 testnet wallets:** [04-configuration/CHAIN2138_WALLET_CONFIG_VALIDATION.md](04-configuration/CHAIN2138_WALLET_CONFIG_VALIDATION.md); **OMNL Indonesia / HYBX-BATCH-001:** [04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md](04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md), [04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md](04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md) |
 | **06-besu** | [06-besu/MASTER_INDEX.md](06-besu/MASTER_INDEX.md) |
 | **Testnet (2138)** | [testnet/DEFI_ORACLE_META_TESTNET_2138_RUNBOOK.md](testnet/DEFI_ORACLE_META_TESTNET_2138_RUNBOOK.md), [testnet/TESTNET_DEPLOYMENT.md](testnet/TESTNET_DEPLOYMENT.md) |
-| **07-ccip** | [07-ccip/](07-ccip/), Truth plan: [07-ccip/TRUTH_NETWORK_BRIDGE_SPEC.md](07-ccip/TRUTH_NETWORK_BRIDGE_SPEC.md), [00-meta/CW_BRIDGE_TASK_LIST.md](00-meta/CW_BRIDGE_TASK_LIST.md) |
+| **07-ccip** | [07-ccip/](07-ccip/), Truth plan: [07-ccip/TRUTH_NETWORK_BRIDGE_SPEC.md](07-ccip/TRUTH_NETWORK_BRIDGE_SPEC.md), [00-meta/CW_BRIDGE_TASK_LIST.md](00-meta/CW_BRIDGE_TASK_LIST.md); **XDC Zero + Chain 138 (parallel to CCIP):** [07-ccip/XDC_ZERO_CHAIN138.md](07-ccip/XDC_ZERO_CHAIN138.md) → [03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md](03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md), [`config/xdc-zero/`](../config/xdc-zero/) |
 | **11-references** | [11-references/ADDRESS_MATRIX_AND_STATUS.md](11-references/ADDRESS_MATRIX_AND_STATUS.md), [11-references/CONTRACT_ADDRESSES_REFERENCE.md](11-references/CONTRACT_ADDRESSES_REFERENCE.md), [11-references/DEPLOYER_CONTRACTS_INVENTORY_AND_VERIFICATION_STATUS.md](11-references/DEPLOYER_CONTRACTS_INVENTORY_AND_VERIFICATION_STATUS.md) (all contracts by deployer wallet, network, verified/not), [11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md](11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md) (tokens, bridges, DODO/Uniswap LPs, full route map), [11-references/DEPLOYER_TO_PUBLIC_STABLECOIN_ROUTES.md](11-references/DEPLOYER_TO_PUBLIC_STABLECOIN_ROUTES.md) (deployer→public stablecoin routes), [11-references/ROUTES_NO_PREFUNDED_BRIDGE_REQUIRED.md](11-references/ROUTES_NO_PREFUNDED_BRIDGE_REQUIRED.md) (routes where bridge pre-fund not required), [11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md](11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md) (per-chain per-token: mint vs receive+forward vs release), [11-references/DEPLOYMENT_DATA_SOURCES_INDEX.md](11-references/DEPLOYMENT_DATA_SOURCES_INDEX.md) (dotenv and config files with contract deployments), [11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md](11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md) (Explorer /tokens vs repo token lists), [11-references/CW_STAR_CMC_COINGECKO_LISTING_STATUS.md](11-references/CW_STAR_CMC_COINGECKO_LISTING_STATUS.md) (cW* on CMC/CoinGecko), [11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md](11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md) (Complete Credential / eIDAS connector repo authority + manifest), [11-references/HARDWARE_INVENTORY_MASTER.md](11-references/HARDWARE_INVENTORY_MASTER.md), [11-references/13_NODE_NETWORK_AND_CABLING_CHECKLIST.md](11-references/13_NODE_NETWORK_AND_CABLING_CHECKLIST.md), [11-references/13_NODE_AND_ASSETS_BRING_ONLINE_CHECKLIST.md](11-references/13_NODE_AND_ASSETS_BRING_ONLINE_CHECKLIST.md) |
 | **Hardware / 13-node** | [11-references/HARDWARE_INVENTORY_MASTER.md](11-references/HARDWARE_INVENTORY_MASTER.md) (R630×13, R750×3, 7920×2, UDM Pro×2, XG×2), [02-architecture/R630_13_NODE_DOD_HA_MASTER_PLAN.md](02-architecture/R630_13_NODE_DOD_HA_MASTER_PLAN.md), [11-references/13_NODE_NETWORK_AND_CABLING_CHECKLIST.md](11-references/13_NODE_NETWORK_AND_CABLING_CHECKLIST.md), [11-references/13_NODE_AND_ASSETS_BRING_ONLINE_CHECKLIST.md](11-references/13_NODE_AND_ASSETS_BRING_ONLINE_CHECKLIST.md) |
 | **Runbooks** | [03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md) |
--- a/scripts/lib/load-project-env.sh
+++ b/scripts/lib/load-project-env.sh
@@ -34,6 +34,7 @@ err_exit() { echo "ERROR: $1" >&2; exit 1; }

 # 4b. Strip trailing CR/LF from RPC URL vars (editor mistakes; breaks cast/curl)
 for _lpr_k in RPC_URL_138 RPC_URL CHAIN138_RPC CHAIN138_RPC_URL ETHEREUM_MAINNET_RPC \
+  XDC_PARENTNET_URL PARENTNET_URL SUBNET_URL XDC_ZERO_PEER_RPC_URL \
  RPC_URL_138_PUBLIC GNOSIS_MAINNET_RPC GNOSIS_RPC CRONOS_RPC_URL CRONOS_RPC \
  CELO_MAINNET_RPC CELO_RPC WEMIX_RPC WEMIX_MAINNET_RPC BSC_RPC_URL \
  POLYGON_MAINNET_RPC BASE_MAINNET_RPC OPTIMISM_MAINNET_RPC ARBITRUM_MAINNET_RPC \
--- a/scripts/verify/README.md
+++ b/scripts/verify/README.md
@@ -34,6 +34,8 @@ One-line install (Debian/Ubuntu): `sudo apt install -y sshpass rsync dnsutils ip
 - `check-gru-transport-preflight.sh` - Operator-focused GRU runtime preflight. Calls `/api/v1/bridge/preflight`, prints blocked pairs with `eligibilityBlockers` / `runtimeMissingRequirements`, and fails unless all active pairs are runtime-ready or `ALLOW_BLOCKED=1` is set.
 - `check-cstar-v2-transport-stack.sh` - Predeploy Forge verifier for the `c* V2` bridge stack. Runs the base V2 token suite, legacy reserve-verifier compatibility suite, V2 reserve/verifier full L1/L2 round-trip suite, and the core `CWMultiTokenBridge` round-trip suite.
 - `run-repo-green-test-path.sh` - Local deterministic green-path aggregate behind root `pnpm test`. Runs config validation, then the focused `smom-dbis-138` contract and service CI targets.
+- `xdc-zero-chain138-preflight.sh` - `eth_chainId` HTTP checks for `XDC_PARENTNET_URL`/`PARENTNET_URL` and `RPC_URL_138`; optional `ETHEREUM_MAINNET_RPC`, `BSC_RPC_URL`. See [CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK](../../docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md).
+- `../xdc-zero/merge-endpointconfig-chain138.sh` - Merge `chain138` into XDC-Zero `endpointconfig.json` (optional `xdcparentnet.registers` append). Set `XDC_ZERO_ENDPOINT_DIR`; use `--dry-run`. See [config/xdc-zero/README.md](../../config/xdc-zero/README.md).
 - `check-completion-status.sh` - One-command summary of repo-completable checks, public report API health, and pointers to operator/external remaining work.
 - `reconcile-env-canonical.sh` - Emit recommended .env lines for Chain 138 (canonical source of truth); use to reconcile `smom-dbis-138/.env` with [CONTRACT_ADDRESSES_REFERENCE](../../docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md). Usage: `./scripts/verify/reconcile-env-canonical.sh [--print]`
 - `check-deployer-balance-blockscout-vs-rpc.sh` - Compare deployer native balance from Blockscout API vs RPC (to verify index matches current chain); see [EXPLORER_AND_BLOCKSCAN_REFERENCE](../../docs/11-references/EXPLORER_AND_BLOCKSCAN_REFERENCE.md)
--- a/scripts/verify/xdc-zero-chain138-preflight.sh
+++ b/scripts/verify/xdc-zero-chain138-preflight.sh
@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Preflight: RPC reachability and eth_chainId for XDC Zero second pair (parent ↔ Chain 138).
+# Optional: ETHEREUM_MAINNET_RPC (or other vars) for quick public mainnet access checks.
+#
+# Usage:
+#   bash scripts/verify/xdc-zero-chain138-preflight.sh
+#   XDC mainnet (default in .env.master.example): XDC_PARENTNET_URL=https://rpc.xinfin.network
+#   Apothem: XDC_PARENTNET_URL=https://rpc.apothem.network bash scripts/verify/xdc-zero-chain138-preflight.sh
+#
+# Loads repo dotenv via scripts/lib/load-project-env.sh when sourced from repo root.
+
+# Avoid nounset while sourcing dotenv (some .env lines reference optional vars).
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# shellcheck source=/dev/null
+source "${PROJECT_ROOT}/scripts/lib/load-project-env.sh"
+
+_rpc_chain_id() {
+  local url="$1"
+  local name="$2"
+  if [[ -z "$url" || "$url" == "devnet" || "$url" == "testnet" ]]; then
+    echo "SKIP $name: empty or alias URL ($url) — resolve to HTTPS RPC for this check."
+    return 0
+  fi
+  local out
+  if ! out="$(curl -sS --connect-timeout 8 --max-time 20 -X POST "$url" \
+    -H 'Content-Type: application/json' \
+    -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' 2>/dev/null)"; then
+    echo "FAIL $name: no HTTP response from $url"
+    return 1
+  fi
+  local hex
+  hex="$(printf '%s' "$out" | sed -n 's/.*"result":"\([^"]*\)".*/\1/p')"
+  if [[ -z "$hex" ]]; then
+    echo "FAIL $name: bad JSON or error from $url — $out"
+    return 1
+  fi
+  echo "OK   $name ($url) eth_chainId=$hex"
+}
+
+echo "=== XDC Zero Chain 138 pair — RPC preflight ==="
+
+fail=0
+PARENT="${XDC_PARENTNET_URL:-${PARENTNET_URL:-}}"
+PEER="${XDC_ZERO_PEER_RPC_URL:-${RPC_URL_138:-${CHAIN138_RPC_URL:-${CHAIN138_RPC:-}}}}"
+
+if [[ -n "$PARENT" ]]; then
+  _rpc_chain_id "$PARENT" "XDC_PARENTNET / PARENTNET" || fail=1
+else
+  echo "WARN XDC_PARENTNET_URL and PARENTNET_URL unset — set one for parent checks."
+fi
+
+if [[ -n "$PEER" ]]; then
+  _rpc_chain_id "$PEER" "Chain138 RPC_URL_138" || fail=1
+else
+  echo "WARN RPC_URL_138 (or CHAIN138_RPC_URL) unset — set for Chain 138 checks."
+fi
+
+if [[ -n "${ETHEREUM_MAINNET_RPC:-}" ]]; then
+  _rpc_chain_id "$ETHEREUM_MAINNET_RPC" "ETHEREUM_MAINNET_RPC (optional)" || fail=1
+fi
+
+if [[ -n "${BSC_RPC_URL:-}" ]]; then
+  _rpc_chain_id "$BSC_RPC_URL" "BSC_RPC_URL (optional)" || fail=1
+fi
+
+if [[ "$fail" -ne 0 ]]; then
+  echo "=== Preflight finished with failures ==="
+  exit 1
+fi
+echo "=== Preflight finished ==="
+echo "Next: deploy Endpoint/CSC per docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md"
--- a/scripts/xdc-zero/merge-endpointconfig-chain138.sh
+++ b/scripts/xdc-zero/merge-endpointconfig-chain138.sh
@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Merge Chain 138 XDC-Zero fragments into an existing endpointconfig.json (upstream XDC-Zero layout).
+# Requires jq. Backs up the target file unless --dry-run or explicit stdout.
+#
+# Usage:
+#   bash scripts/xdc-zero/merge-endpointconfig-chain138.sh path/to/endpointconfig.json
+#   bash scripts/xdc-zero/merge-endpointconfig-chain138.sh path/to/endpointconfig.json path/to/out.json
+#   bash scripts/xdc-zero/merge-endpointconfig-chain138.sh path/to/endpointconfig.json --dry-run
+#   bash scripts/xdc-zero/merge-endpointconfig-chain138.sh --dry-run path/to/endpointconfig.json
+# Or set XDC_ZERO_ENDPOINT_DIR to an XDC-Zero/endpoint clone path (uses .../endpointconfig.json).
+#
+# Sources: config/xdc-zero/endpointconfig.fragment.chain138.example.json,
+#          config/xdc-zero/xdcparentnet-register-chain138.fragment.json
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+FRAG="$PROJECT_ROOT/config/xdc-zero/endpointconfig.fragment.chain138.example.json"
+REG_FRAG="$PROJECT_ROOT/config/xdc-zero/xdcparentnet-register-chain138.fragment.json"
+
+DRY_RUN=false
+BASE=""
+OUT=""
+POSITIONAL=()
+for a in "$@"; do
+  if [[ "$a" == "--dry-run" ]]; then
+    DRY_RUN=true
+  else
+    POSITIONAL+=("$a")
+  fi
+done
+
+if [[ ${#POSITIONAL[@]} -ge 1 ]]; then
+  BASE="${POSITIONAL[0]}"
+fi
+if [[ ${#POSITIONAL[@]} -ge 2 ]]; then
+  OUT="${POSITIONAL[1]}"
+fi
+
+if [[ -z "$BASE" && -n "${XDC_ZERO_ENDPOINT_DIR:-}" ]]; then
+  BASE="${XDC_ZERO_ENDPOINT_DIR%/}/endpointconfig.json"
+fi
+
+if [[ -z "$BASE" || ! -f "$BASE" ]]; then
+  echo "Usage: $0 <endpointconfig.json> [out.json] [--dry-run]" >&2
+  echo "  Or: XDC_ZERO_ENDPOINT_DIR=/path/to/XDC-Zero/endpoint $0 [--dry-run]" >&2
+  exit 1
+fi
+if [[ ! -f "$FRAG" || ! -f "$REG_FRAG" ]]; then
+  echo "ERROR: missing fragment under config/xdc-zero/" >&2
+  exit 1
+fi
+command -v jq >/dev/null 2>&1 || { echo "ERROR: jq required" >&2; exit 1; }
+
+_step1="$(jq --slurpfile f "$FRAG" '.chain138 = $f[0].chain138' "$BASE")"
+MERGED="$(printf '%s\n' "$_step1" | jq --slurpfile r "$REG_FRAG" '
+  (if .xdcparentnet == null then . + {xdcparentnet: {registers: []}} else . end)
+  | .xdcparentnet.registers += $r[0]
+')"
+
+_c138_count="$(printf '%s' "$MERGED" | jq '[.xdcparentnet.registers[]? | select(.chainId == 138)] | length')"
+if [[ "${_c138_count:-0}" -gt 1 ]]; then
+  echo "WARN: xdcparentnet.registers has ${_c138_count} entries with chainId 138 — review manually." >&2
+fi
+
+if $DRY_RUN; then
+  printf '%s\n' "$MERGED"
+  exit 0
+fi
+
+if [[ -n "$OUT" ]]; then
+  printf '%s\n' "$MERGED" >"$OUT"
+  echo "Wrote $OUT"
+  exit 0
+fi
+
+cp -a "$BASE" "${BASE}.bak.$(date +%Y%m%d%H%M%S)"
+printf '%s\n' "$MERGED" >"$BASE"
+echo "Merged into $BASE (backup beside file)."