proxmox/multi-chain-execution

Multi-Chain Execution and Mirroring

API-only execution (DBIS 138, Alltra 651940) and transaction mirroring to public mainnets.

Features

• Intent API: POST /v1/intents, POST /v1/intents/:id/execute
• Execution read: GET /v1/executions/:id, GET /v1/tx/:chainId/:txHash
• Mirroring: POST /v1/mirror/commit, GET /v1/mirror/commits/:id, GET /v1/mirror/proof?chain_id=&tx_hash=
• Observability: GET /v1/health, GET /v1/metrics (Prometheus)
• Chain adapters: CA-138, CA-651940, CA-publicN (RPC, receipt, logs, reorg detection)
• Merkle commitment builder and MirrorRegistry contract (see smom-dbis-138/contracts/mirror/MirrorRegistry.sol)

Setup

npm install
npm run build

Run

PORT=3001 npm start

Or node dist/main.js.

Env

• CHAIN_138_RPC_URL — RPC for chain 138 (default https://rpc-http-pub.d-bis.org)
• CHAIN_651940_RPC_URL — RPC for Alltra (default https://mainnet-rpc.alltra.global)
• PORT — API port (default 3001)

OpenAPI

See docs/api/openapi-multi-chain-execution.yaml.

Runbooks

• Incident response: docs/runbooks/MULTI_CHAIN_EXECUTION_INCIDENT_RESPONSE.md
• Key rotation: docs/runbooks/MULTI_CHAIN_EXECUTION_KEY_ROTATION.md
• Reorg handling: docs/runbooks/MULTI_CHAIN_EXECUTION_REORG_HANDLING.md

Smoke test

With the API running (npm start), in another terminal:

chmod +x scripts/smoke-test.sh
BASE_URL=http://localhost:3001 ./scripts/smoke-test.sh

Requires curl and jq.

Integration test (138 -> 651940)

Minimal integration test that creates an intent 138 -> 651940, executes it, and verifies mirror commit. Assumes deterministic contract addresses (CREATE2) on both chains.

BASE_URL=http://localhost:3001 node scripts/integration-test.mjs

Run after npm run build && npm start in another terminal.

Admin API (protected)

• POST /v1/admin/policies — stub
• POST /v1/admin/keys/rotate — stub
• POST /v1/admin/circuit-breaker/on — force circuit open
• POST /v1/admin/circuit-breaker/off — force circuit closed

Set ADMIN_API_KEY and pass X-Admin-Key header or admin_key query param to protect admin routes.