0018. Multi-network architecture and cross-chain trust

Design document, published from the repository at docs/adr/0018-multi-network-architecture.md.

  • Status: Accepted
  • Date: 2026-11-14

Context

QuantLayer must run on Arbitrum (One, Sepolia) and Robinhood Chain (mainnet, testnet), and decide when a credential registered on one chain may be relied on from another. Both families are Arbitrum Nitro chains settling to Ethereum. They have no direct messaging channel: native messages take seven days through Ethereum. The backend (FEAT-10) had a minimal single-chain RPC client, and no QuantLayer contracts are deployed yet.

Decision

  1. A new library, @quantlayer-protocol/networks, built on Viem 2.57.13 (pinned; its chain definitions match the official documentation). One NetworkAdapter interface binds every client to its network's chain id, and an endpoint that reports another chain is refused. Viem handles transport, ABI encoding and transactions.
  2. Cryptography stays behind QuantLayer's boundary. EIP-712 hashing and signer recovery use @quantlayer-protocol/evm, and Keccak-256 comes from @quantlayer-protocol/crypto-classical. EIP-1186 proofs are verified by a small Merkle-Patricia walker in this package, using those primitives and @ethereumjs/rlp for decoding only.
  3. Verify against the chains, not just the docs. Network configuration cites its official sources. Discovery re-derives facts at run time: chain id, ArbOS version, block tags, eth_getProof, parent-chain contract wiring. Discrepancies are reported, as with Arbitrum Sepolia's rollup address. Values the docs don't state are left undefined.
  4. No fabricated deployments. The contract registry is filled only from real deployment records, and each address is verified by code fingerprint (runtime code with immutables masked), so contract version discovery and integrity are one mechanism.
  5. Settlement-grade by default for trust decisions. Cross-chain reads use the finalized tag. Confirmation and event monitoring re-check canonicality and surface reorgs explicitly.
  6. Cross-chain credentials are deny-by-default. A per-target policy lists explicit rules (source chain, issuers, evidence kinds, freshness, header quorum). Evidence is a same-chain registry read, an EIP-1186 state proof under a multi-endpoint header quorum, or an issuer attestation that names both chains, signed by the proven issuer authority. Every result carries its assurance.

Consequences

  • What's easier. Adding an Arbitrum-family network means adding a configuration entry and running the live verification suite.
  • The state-proof assurance is "header quorum". It is not trustless. Light-client or ZK-consensus verification of source headers against the Arbitrum rollup on Ethereum is the stated upgrade path.
  • Native message relaying is not built yet. It would need messenger contracts and the aliased messenger registered as an issuer authority in the target registry.
  • Follow-up. The backend's blockchain module (FEAT-10) can move onto NetworkAdapter and EventMonitor; this ADR doesn't require that change.