bea1903ac9
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
4.2 KiB
4.2 KiB
Cross-Chain Arbitrage Design (Phase 4)
Purpose: Architecture and operational design for maintaining price parity between Chain 138 and Alltra (651940) via cross-chain arbitrage and bridge buffer sizing.
Related: VAULT_SYSTEM_MASTER_TECHNICAL_PLAN §9; AlltraAdapter, AlltraCustomBridge.
1. Architecture
- Arbitrage engine: Off-chain bot (recommended). Polls price on Chain 138 and on 651940; if |Price138 − Price651940| > ArbitrageThreshold, computes trade size and direction; executes bridge + swap (lock on 138 → relayer mints/releases on 651940, or reverse).
- Data sources: Token-aggregation report API (
/api/v1/report/coingeckoor equivalent), or RPC + DEX/pool on each chain. - Execution: AlltraAdapter
bridge()or AlltraCustomBridge (lock on 138 → relayer mints/releases on 651940). - Optional on-chain: Contract that emits
CrossChainDeviation(chainIdA, chainIdB, token, priceA, priceB, deviationBps)when a trusted oracle/bot submits it; bot listens and executes. Not required for MVP.
2. Data flow
- Poll: Fetch token price (or mid/spot) on Chain 138 and on 651940 (report API or RPC + pool).
- Compare: Compute deviation (e.g. in bps):
|price138 − price651940| / price138 * 10000. - Decide: If deviation > ArbitrageThreshold (e.g. 15 bps), compute trade size and direction (e.g. sell on high side, buy on low side; or bridge out from high, receive on low).
- Execute: Call AlltraAdapter.bridge() or AlltraCustomBridge (lock tokens on 138, relayer mints on 651940) or reverse; optionally swap on destination to realize arb.
3. Environment and configuration
| Variable | Description |
|---|---|
| RPC_URL_138 | RPC for Chain 138 |
| RPC_URL_651940 | RPC for Alltra Mainnet (651940) |
| REPORT_API_URL | Token-aggregation base URL for report API (optional) |
| AlltraAdapter address | Deployed AlltraAdapter on 138 (and 651940 if bidirectional) |
| AlltraCustomBridge address | When using custom transport for 138↔651940 |
| Keeper / private key | EOA or bot key with BRIDGE_OPERATOR_ROLE (or equivalent) for bridge calls |
| ArbitrageThreshold | Deviation in bps above which to trade (e.g. 15) |
| MaxTradeSize | Cap per trade to limit exposure |
4. Failure modes and robustness
- Bridge delay: Settlement may take multiple blocks; do not assume same-block parity. Size bridge reserve per runbook (BridgeReserve ≥ PeakBridgeOutflow × Latency).
- Partial fill: Destination swap may partially fill; implement idempotency (e.g. by requestId) and retries with backoff.
- Rate limits: Report API or RPC may throttle; use reasonable poll interval and exponential backoff on errors.
- Reorgs: Prefer finality before considering a cross-chain price “confirmed”; optional: wait N blocks on both chains before executing.
5. Bridge buffer formula (operations)
- Rule: BridgeReserve ≥ PeakBridgeOutflow × Latency.
- PeakBridgeOutflow: Maximum outflow over a time window (e.g. peak hourly or daily bridge volume).
- Latency: Bridge settlement time (e.g. typical block confirmation + relayer delay in minutes or blocks).
- Sizing: Measure peak outflow from bridge events (TransferInitiated / released volume); measure latency from Initiated to Confirmed (or equivalent). Multiply; add safety factor (e.g. 1.5–2×). See runbook section “Cross-chain parity and bridge buffer” in OPERATIONS_RUNBOOK.
6. Optional bot skeleton
A TypeScript/Node service can live in smom-dbis-138/services/ or dbis_core:
- Config: chains (138, 651940), token addresses, RPC URLs, report API URL, AlltraAdapter address, ArbitrageThreshold, maxTradeSize.
- Loop: (1) Fetch prices (report API or RPC + pool), (2) compute deviation, (3) if over threshold, call AlltraAdapter or AlltraCustomBridge + optional swap on destination.
- Security: Use env for private keys; restrict BRIDGE_OPERATOR_ROLE to bot EOA or dedicated keeper.
No implementation is required for the design to be complete; this section describes the scope if a bot is added.