From 6390174bb7ad419ef76c16f943375e42b571db47 Mon Sep 17 00:00:00 2001 From: defiQUG Date: Tue, 31 Mar 2026 23:10:36 -0700 Subject: [PATCH] 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 --- .env.master.example | 7 ++ AGENTS.md | 1 + config/xdc-zero/README.md | 18 +++++ ...pointconfig.fragment.chain138.example.json | 13 +++ .../network.config.xdc-mainnet.example.json | 5 ++ .../xdc-zero-chain138-pair.example.env | 57 +++++++++++++ ...cparentnet-register-chain138.fragment.json | 7 ++ .../CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md | 77 ++++++++++++++++++ docs/07-ccip/XDC_ZERO_CHAIN138.md | 11 +++ docs/MASTER_INDEX.md | 2 +- scripts/lib/load-project-env.sh | 1 + scripts/verify/README.md | 2 + scripts/verify/xdc-zero-chain138-preflight.sh | 74 +++++++++++++++++ .../xdc-zero/merge-endpointconfig-chain138.sh | 80 +++++++++++++++++++ 14 files changed, 354 insertions(+), 1 deletion(-) create mode 100644 config/xdc-zero/README.md create mode 100644 config/xdc-zero/endpointconfig.fragment.chain138.example.json create mode 100644 config/xdc-zero/network.config.xdc-mainnet.example.json create mode 100644 config/xdc-zero/xdc-zero-chain138-pair.example.env create mode 100644 config/xdc-zero/xdcparentnet-register-chain138.fragment.json create mode 100644 docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md create mode 100644 docs/07-ccip/XDC_ZERO_CHAIN138.md create mode 100755 scripts/verify/xdc-zero-chain138-preflight.sh create mode 100755 scripts/xdc-zero/merge-endpointconfig-chain138.sh diff --git a/.env.master.example b/.env.master.example index 57d2404..f426da9 100644 --- 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= diff --git a/AGENTS.md b/AGENTS.md index 6c00f56..cef3965 100644 --- 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). | diff --git a/config/xdc-zero/README.md b/config/xdc-zero/README.md new file mode 100644 index 0000000..8906c33 --- /dev/null +++ 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). diff --git a/config/xdc-zero/endpointconfig.fragment.chain138.example.json b/config/xdc-zero/endpointconfig.fragment.chain138.example.json new file mode 100644 index 0000000..d514709 --- /dev/null +++ b/config/xdc-zero/endpointconfig.fragment.chain138.example.json @@ -0,0 +1,13 @@ +{ + "chain138": { + "endpoint": "0x0000000000000000000000000000000000000000", + "registers": [ + { + "chainId": 50, + "csc": "0x0000000000000000000000000000000000000000", + "endpoint": "0x0000000000000000000000000000000000000000" + } + ], + "applications": [] + } +} diff --git a/config/xdc-zero/network.config.xdc-mainnet.example.json b/config/xdc-zero/network.config.xdc-mainnet.example.json new file mode 100644 index 0000000..7d477a3 --- /dev/null +++ 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" +} diff --git a/config/xdc-zero/xdc-zero-chain138-pair.example.env b/config/xdc-zero/xdc-zero-chain138-pair.example.env new file mode 100644 index 0000000..4cc4a42 --- /dev/null +++ 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= diff --git a/config/xdc-zero/xdcparentnet-register-chain138.fragment.json b/config/xdc-zero/xdcparentnet-register-chain138.fragment.json new file mode 100644 index 0000000..39ebacc --- /dev/null +++ b/config/xdc-zero/xdcparentnet-register-chain138.fragment.json @@ -0,0 +1,7 @@ +[ + { + "chainId": 138, + "csc": "0x0000000000000000000000000000000000000000", + "endpoint": "0x0000000000000000000000000000000000000000" + } +] diff --git a/docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md b/docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md new file mode 100644 index 0000000..c93a580 --- /dev/null +++ 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). diff --git a/docs/07-ccip/XDC_ZERO_CHAIN138.md b/docs/07-ccip/XDC_ZERO_CHAIN138.md new file mode 100644 index 0000000..008ae36 --- /dev/null +++ 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. diff --git a/docs/MASTER_INDEX.md b/docs/MASTER_INDEX.md index a95ba7a..fde7306 100644 --- 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) | diff --git a/scripts/lib/load-project-env.sh b/scripts/lib/load-project-env.sh index e92ca4b..069a45e 100644 --- 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 \ diff --git a/scripts/verify/README.md b/scripts/verify/README.md index aedbe7b..efa6eeb 100644 --- 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) diff --git a/scripts/verify/xdc-zero-chain138-preflight.sh b/scripts/verify/xdc-zero-chain138-preflight.sh new file mode 100755 index 0000000..6c3182f --- /dev/null +++ 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" diff --git a/scripts/xdc-zero/merge-endpointconfig-chain138.sh b/scripts/xdc-zero/merge-endpointconfig-chain138.sh new file mode 100755 index 0000000..923dd97 --- /dev/null +++ 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 [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)."