proxmox/docs/07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md

Runbook: Add LINK Support to Mainnet Relay Bridge

Last Updated: 2026-02-13
Status: Planned
Prerequisite: TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md

---

Context

The Mainnet CCIPRelayBridge (0xF9A32F37099c582D28b4dE7Fca6eaC1e5259f939) is WETH9-only: it accepts only WETH9 in ccipReceive and has no token registry. The relay service already maps Chain 138 LINK → Mainnet LINK in tokenMapping; to actually deliver LINK 138→Mainnet you must extend the bridge or add a separate receiver.

---

Option A: Extend CCIPRelayBridge to accept LINK

1. Contract change
   In smom-dbis-138/contracts/relay/CCIPRelayBridge.sol:

   • Add an immutable or configurable link address (Mainnet LINK: 0x514910771AF9Ca656af840dff83E8264EcF986CA).
   • In ccipReceive, allow message.tokenAmounts[0].token to be either weth9 or link; transfer the corresponding token to the decoded recipient.
   • Keep replay protection and router role as-is.

2. Deploy
   Deploy a new bridge (or use an upgrade pattern if the contract is upgradeable; current one is not). Update:

   • config/smart-contracts-master.json (chain 1) if you use a new contract key.
   • Relay service config: CCIP_RELAY_BRIDGE_MAINNET if the LINK receiver is a new address. If the same contract handles both WETH9 and LINK, no relay config change beyond ensuring tokenMapping includes LINK (already done via config/token-mapping.json).

3. Fund
   Transfer Mainnet LINK to the bridge (or LINK receiver) so it can pay out relayed amounts.

4. Token mapping
   In config/token-mapping.json, set relaySupported: true for the LINK entry. Redeploy or restart the relay so it picks up the mapping (already maps LINK; bridge will no longer revert for LINK).

---

Option B: Deploy a separate LINK receiver

1. New contract
   Deploy a small receiver contract (e.g. CCIPRelayBridgeLINK) that:

   • Has ROUTER_ROLE granted to the same CCIPRelayRouter (0xAd9A228CcEB4cbB612cD165FFB72fE090ff10Afb).
   • In ccipReceive, accepts only Mainnet LINK; transfers LINK to the decoded recipient; replay protection by messageId (or reuse a shared registry).

2. Relay service
   The relay currently sends all messages to one bridge address. To support LINK you would need either:

   • Router logic: Mainnet router inspects token in the message and calls the appropriate bridge (WETH9 bridge vs LINK bridge), or
   • Relay service logic: Relay service chooses destination bridge address by token (e.g. LINK → LINK receiver, others → existing CCIPRelayBridge). That requires changing the relay to pass a different relayBridgeAddress per token (or per message).

3. Fund
   Fund the LINK receiver with Mainnet LINK.

4. Config
   Document the new LINK receiver address in config/smart-contracts-master.json (chain 1) and in TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md. Set relaySupported: true for LINK in config/token-mapping.json once the path is live.

---

After LINK is supported

• Update TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md table: LINK row → "Relay supported: ✅ Yes".
• In config/token-mapping.json, set relaySupported: true for the LINK token entry.
• Add a short note to CCIP_BRIDGE_MAINNET_CONNECTION.md that LINK is accepted (and which contract holds it).

---

References

• TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md — Token mapping and recommendations
• CCIP_BRIDGE_MAINNET_CONNECTION.md — Mainnet contracts and relay flow
• smom-dbis-138/contracts/relay/CCIPRelayBridge.sol — Current WETH9-only bridge