74 lines
2.1 KiB
Markdown
74 lines
2.1 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install
|
||
|
|
npm run build
|
||
|
|
```
|
||
|
|
|
||
|
|
## Run
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|