# 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.