smom-dbis-138/docs/bridge/ETHERLINK_RELAY_RUNBOOK.md

Etherlink Relay Runbook

Runbook for bridging to Etherlink (chain 42793) when CCIP does not support Etherlink (custom relay path) or as reference when CCIP is added.

Branch: CCIP vs Custom Relay

• If CCIP supports Etherlink: Use official CCIP lane. Deploy receiver bridges on Etherlink per DeployWETHBridges.s.sol and execute-bridge-config.sh. Configure addDestination on source (138, 651940 if ever CCIP) with Etherlink chain selector and receiver addresses. Fund LINK. No custom relay needed.
• If CCIP does not support Etherlink: Use custom relay (this runbook). Same pattern as 138→Mainnet in relay ARCHITECTURE.

Custom Relay Path (when CCIP not available)

Components

1. Source chain(s) (e.g. ChainID 138 or ALL Mainnet)
   • Bridge contract (UniversalCCIPBridge or WETH bridge) that locks tokens and emits events (e.g. MessageSent or equivalent).
2. Relay service (off-chain)
   • Event monitor: listen for bridge/router events for destination Etherlink (chainId 42793).
   • Message queue: queue detected messages; retry; idempotency.
   • Token mapping: source token address → Etherlink token address.
   • Submit on Etherlink: call relay-compatible receiver contract to mint/unlock and transfer to recipient.
3. Etherlink (42793)
   • Relay-compatible receiver: Contract that accepts relay-submitted payloads (sender, token, amount, recipient); mints or unlocks and transfers. Must be authorized (e.g. only relayer key can call).

Receiver interface (Etherlink)

• Function: e.g. relayMintOrUnlock(bytes32 messageId, address token, address recipient, uint256 amount) or equivalent.
• Access control: only relayer (or authorized bridge) can call.
• Replay: use messageId (or source chain tx hash) for idempotency.

Env

• ETHERLINK_RPC_URL (e.g. https://node.mainnet.etherlink.com).
• ETHERLINK_RELAY_BRIDGE: receiver contract on Etherlink.
• ETHERLINK_RELAY_PRIVATE_KEY: key that holds authority on receiver (or relayer role).

Deployment on Etherlink (custom relay)

1. Deploy receiver contract (relay-compatible: accept relayMintOrUnlock-style calls).
2. Deploy or map wrapped token contracts if needed.
3. Configure relay service: source RPC, Etherlink RPC, receiver address, token mapping, private key.

References

• relay ARCHITECTURE (138→Mainnet pattern).
• TEZOS_CCIP_DON_PREREQUISITES: verify CCIP first; if not listed, use this runbook.