4ebf2d7902
Add optional Cosmos/Engine-X/act-runner templates, CWUSDC/EI-matrix tooling, non-EVM route planner in multi-chain-execution (tests passing), token list and extraction updates, and documentation (MetaMask matrix, GRU/CWUSDC packets). Ignore institutional evidence tarballs/sha256 under reports/status. Validated with: bash scripts/verify/run-all-validation.sh --skip-genesis Co-authored-by: Cursor <cursoragent@cursor.com>
11 KiB
11 KiB
Cosmos Ecosystem and Chain 138 — Optional Integrations Runbook
Last Updated: 2026-05-09
Status: Optional program — streams A–E fully documented; live bridges remain operator-adopted (see config/cosmos-chain138-optional/STATUS.md)
Audience: Architecture, bridge operators, compliance, routing/backend owners
1. Scope and facts
- Chain 138 is an EVM (Besu) network. It is not a Cosmos SDK zone and does not run the Cosmos stack natively.
- “Full Cosmos integration” therefore means bridges, attestations, routing, wallets, and ops that connect IBC-capable chains to 138 contracts and policies, not enabling IBC on 138 itself.
- Canonical Chain 138 tokens and PMM remain per EXPLORER_TOKEN_LIST_CROSSCHECK.md (sections 5 and 8) and ADDRESS_MATRIX_AND_STATUS.md. Any Cosmos-side asset must map to those policies explicitly.
- Known cross-repo conflicts (PMM addresses, CCIP env drift, missing
smart-contracts-master.json): COSMOS_CHAIN138_GAPS_AND_INCONSISTENCIES.md (section 3–4 are global, not Cosmos-only). - On-chain today:
ChainRegistryincludesChainType.Cosmosfor metadata registration. A historicalCosmosAdapterstub lives undersmom-dbis-138/archive/solidity/contracts/bridge/adapters/non-evm/CosmosAdapter.sol(oracle-confirmed lock pattern; not production IBC). See MASTER_CONTRACTS_AND_INFRASTRUCTURE_LIST.md.
2. Preconditions (all streams)
Complete before treating any stream as “in progress”:
| # | Gate | Owner |
|---|---|---|
| P1 | Bridge class chosen per corridor: trust-minimized (e.g. general-message bridge vendor), CCTP-style where applicable, or oracle/custodial (closest to archived adapter) | Architecture + risk |
| P2 | Allowlist policy for Cosmos denoms and bridge contracts (who may mint/list on 138) | Compliance + engineering |
| P3 | Relayer / vendor SLA or explicit “public relayer only” acceptance | Ops |
| P4 | Incident playbooks (stuck IBC packet, bridge pause, oracle disagreement) | Ops |
| P5 | Explorer / indexer plan: Blockscout covers 138 EVM only; Cosmos legs need Mintscan (or equivalent) and/or internal indexer | Platform |
3. Stream A — Noble (and similar) native Cosmos stable corridor
Objective: Recognized native Cosmos stablecoin (e.g. Noble-issued USDC) maps cleanly to 138 canonical stables or wrapped representations, with auditability.
| Step | Task | Done when |
|---|---|---|
| A1 | Select source chain (e.g. Noble) and bridge stack (vendor contracts + supported routes) | Written decision + vendor docs linked in internal wiki |
| A2 | Define 138-side mint/burn or lock/mint contract(s) and roles (admin, pauser, oracle or light-client consumer) | Spec reviewed; addresses reserved in deployment tracker |
| A3 | Map denom → 138 token address (single canonical mapping table; no duplicate “explorer” addresses) | Row in repo config or registry doc + CI check if applicable |
| A4 | Register non-EVM metadata in ChainRegistry (ChainType.Cosmos, chainIdentifier, adapter, additionalData for channel/bridge IDs) |
On-chain tx executed; CONTRACT_ADDRESSES_REFERENCE.md updated |
| A5 | Liquidity plan: seed PMM/vault or rely on external DEX only | Funding signed off |
| A6 | E2E dry path: small amount round-trip (Cosmos → 138 → Cosmos or to declared sink) | Tx hashes recorded; monitoring dashboards live |
| A7 | Update CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md and GALATIC_SUMMARY.md | PR merged |
4. Stream B — Osmosis (and other Cosmos DEX) liquidity and routing
Objective: Quotes and optional execution legs on Cosmos DEXes appear in the same route-planning discipline as other non-EVM legs (compare TEZOS_USDTZ_INTEGRATION.md: route classes, not native 138 DEX).
| Step | Task | Done when |
|---|---|---|
| B1 | Choose read-only vs executable integration (quotes only vs signed swaps on Osmosis) | Flag in route engine config |
| B2 | Denom/path parser for pool routes and IBC hops | Unit tests + sample traces |
| B3 | Integrate slippage, timeout, and failure handling for IBC + DEX latency | Documented limits in API/runbook |
| B4 | If using aggregator stack: align with existing Axelar/Squid-class patterns where applicable (BRIDGE_CHAINS_IMPLEMENTATION_COMPLETE.md) | Code path reviewed |
| B5 | Security review for any server-side signing or custody | Sign-off recorded |
5. Stream C — Generic IBC token (ICS-20 / app tokens)
Objective: Any allowlisted IBC-traced asset can be registered and routed, not only USDC.
| Step | Task | Done when |
|---|---|---|
| C1 | Define IBC hash / full trace schema stored in ChainMetadata.additionalData (or off-chain registry mirrored on-chain) |
Schema doc + one example on testnet |
| C2 | Tiering: Tier-1 (manual governance allowlist) vs Tier-2 (automated with stricter caps) | Policy published |
| C3 | Per-token: bridge + DEX + 138 contract triple documented | Matrix row per denom |
| C4 | User-facing warnings for non-Noble / long trace paths | UI/API copy merged |
| C5 | Align token list / explorer publication with EXPLORER_TOKEN_LIST_CROSSCHECK.md | No conflicting canonical rows |
6. Stream D — CosmWasm application ↔ Chain 138
Objective: One or more named CosmWasm contracts (e.g. DEX, lending, ID) integrate via explicit messages, not “all of CosmWasm.”
| Step | Task | Done when |
|---|---|---|
| D1 | Pin contract address(es), code ID, migrate policy | Version doc |
| D2 | Choose control path: ICA/ICQ, general-message bridge to EVM, or off-chain coordinator + oracle | Sequence diagrams stored |
| D3 | 138-side counterpart (vault, adapter, settlement hook) deployed or extended | Addresses in CONTRACT_ADDRESSES_REFERENCE |
| D4 | Hyperledger path only if required: Cacti/Firefly alignment per MULTI_CHAIN_DEPLOYMENT_GUIDE.md Phase 4 | Explicit decision recorded |
| D5 | Wasm CI/build and upgrade runbook (outside or inside monorepo) | Maintainer sign-off |
7. Stream E — Cross-cutting layers and program closure
Objective: Relayers, wallets, indexing, audits, rate limits, and formal program closure so Cosmos legs are operable and governable, not only contract code.
| Step | Task | Done when |
|---|---|---|
| E1 | IBC relayers: channels, fees, redundancy, key custody documented | Table in ops doc or config/cosmos-chain138-optional/cross-cutting.example.md filled for live |
| E2 | Wallets: Keplr / Leap / MetaMask Snaps (if used) user flows documented | Links in cross-cutting doc |
| E3 | Indexing: Cosmos txs and IBC events in SIEM or internal logs | Dashboard or log path recorded |
| E4 | Audits: per bridge deployment and per new token class | Report URLs stored |
| E5 | Rate limits: API and on-chain caps for mint/burn | Limits published to integrators |
| E6 | Program closure: P1–P5 signed; adopted product streams A–D named; stream E (E1–E6) complete for adopted scope; CHAINS_AND_PROTOCOLS + GALATIC_SUMMARY updated for live only; annual review owner |
config/cosmos-chain138-optional/STATUS.md reflects live vs doc-only |
Templates (copy before live use): config/cosmos-chain138-optional/README.md
8. Suggested implementation order (still optional)
- Preconditions (section 2)
- Stream A (one stable corridor end-to-end)
- Stream C on top of the same bridge (allowlist + schema)
- Stream B (quotes, then optional execution)
- Stream D (first CosmWasm app as reference)
- Stream E (relayers through program closure) — typically last, but E1–E3 planning can start in parallel
9. Definition of “complete” for this program
The program is complete when:
- Every stream (A–E) that the organization chooses to adopt has all its rows in sections 3–7 marked done, with on-chain or operational evidence (tx hashes, run URLs, audit PDFs) referenced from ADDRESS_MATRIX_AND_STATUS.md or a linked ops doc; and
- CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md reflects live vs not used for Cosmos-related bridges; and
- Deferred streams are explicitly listed as out of scope in
config/cosmos-chain138-optional/STATUS.mdor in PHASE_D_OPTIONAL_CHECKLIST.md.
Repo doc-and-template completion (no live bridge implied): Streams A–E are fully specified in this runbook plus config/cosmos-chain138-optional/*; see STATUS.md for doc vs live matrix.
Streams explicitly not adopted remain optional; no further work is required.
10. Repo map (quick)
| Item | Location |
|---|---|
| Templates + status matrix | config/cosmos-chain138-optional/ |
ChainType.Cosmos |
smom-dbis-138/contracts/registry/ChainRegistry.sol |
| Historical Cosmos adapter | smom-dbis-138/archive/solidity/contracts/bridge/adapters/non-evm/CosmosAdapter.sol |
| Multi-chain Phase 3 checklist | smom-dbis-138/docs/deployment/MULTI_CHAIN_DEPLOYMENT_GUIDE.md |
| Non-EVM adapter backlog | smom-dbis-138/docs/deployment/REMAINING_TASKS_COMPLETE_LIST.md (BRG-DEP-005) |
| Bridge reference (EVM-focused) | This directory, CHAINS_AND_PROTOCOLS_BRIDGE_INTEGRATION.md |
| Tezos route pattern (analogy) | TEZOS_USDTZ_INTEGRATION.md |