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
This commit is contained in:
defiQUG
77
docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md
Normal file
77
docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md
Normal file
@@ -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).
|
||||
11
docs/07-ccip/XDC_ZERO_CHAIN138.md
Normal file
11
docs/07-ccip/XDC_ZERO_CHAIN138.md
Normal file
@@ -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.
|
||||
@@ -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) |
|
||||
|
||||
Reference in New Issue
Block a user