Skip to main content

Architecture

SkyBridge V2 routes every transfer through the SkyBridgeEntryPoint you interact with directly. Most rails forward to a shared Diamond that holds the bridge logic; Rail 5 talks directly to the destination chain's canonical Arbitrum Inbox instead. Four rails handle the actual cross-chain messaging.

The two-contract stack​

SkyBridgeEntryPoint​

The EntryPoint is the only contract you ever call. It:

  1. Accepts a flat native-currency fee (see Fees)
  2. Validates the transfer parameters
  3. Forwards the call to the appropriate rail inside the Diamond

The EntryPoint is deployed as an ERC-1967 / UUPS proxy, so it can be upgraded without changing its address. Each chain has its own EntryPoint - addresses are in Official Addresses.

Diamond (0x14fbb1eD5BC098B4Ea236dcE0941EDB02e967b44)​

The Diamond is the same address across the 11-chain fleet (Robinhood Chain is a divergent-address exception - see Diamond & Facets). It follows the EIP-2535 Diamond Standard: a single proxy that delegates to 12 facets based on the function selector called. All bridge functions inside the Diamond are gated to onlyEntryPoint - users never call the Diamond directly.

12 facets - 65 selectors total:

Genesis facets (deployed first, identical addresses on every chain):

  • DiamondCutFacet - manages the propose → finalize upgrade flow
  • DiamondLoupeFacet - EIP-2535 introspection
  • AccessControlFacet - role management
  • WithdrawalTimelockFacet - 48-hour emergency withdrawal timelock
  • ReceiverSelectorWhitelist - allowlists which function selectors can be called on destination

Init-cut facets (deployed per chain, contain CCIP-router and other immutable ctor args):

  • BridgeFacet - CCIP ERC-20 bridging (lock/burn on source, mint/unlock on destination)
  • ERC721BridgeFacet - CCIP NFT bridging
  • BridgeReceiverFacet - handles ccipReceive(), auto-deploys SkyToken via CREATE3 on first arrival
  • ERC721BridgeReceiverFacet - NFT receiver, auto-deploys SkyNFT on first arrival
  • CCIPFacet - CCIP router integration, chain/sender allowlisting, failed-message recovery
  • SkyTokenDeployerFacet - deterministic ERC-20 deployment
  • SkyNFTDeployerFacet - deterministic ERC-721 deployment

Diamond storage uses namespaced keccak256 slots so facets never collide with each other.

The four rails​

SkyBridge's rails are numbered 1, 3, 4, and 5 (Rail 2, the old OP custom bridge, was removed in V6.1).

Rail 3 - Chainlink CCIP (recommended)​

CCIP is the primary rail for all custom ERC-20 and NFT transfers. The bridge locks or burns tokens on the source chain and mints or unlocks them on the destination. The first time a token arrives on a new chain, the BridgeReceiverFacet deploys a deterministic SkyToken (CREATE3) so the address is the same on every chain.

WETH via CCIP: On the Ethereum ↔ Base, Ethereum ↔ Arbitrum One, and Ethereum ↔ Optimism lanes, WETH bridges natively over CCIP rather than being wrapped a second time.

Coverage: All 11 chains, full mesh.

Rail 4 - Circle CCTP (native USDC)​

CCTP burns native USDC on the source chain and mints native USDC on the destination - no wrapped representation. The bridge calls Circle's TokenMessengerV2 directly. Select "Fast" to pay a 0.25% fee (fastCctpFeeBps = 25) and receive funds in a single atomic step.

Coverage: Ethereum, Base, Optimism, Arbitrum One, Polygon, Avalanche C-Chain, Unichain, Ink.

Rail 1 - OP Standard Bridge (optional L2 path)​

The OP Standard Bridge is an optional fast path between Ethereum and the five OP-stack L2s (Base, Optimism, Unichain, Soneium, Ink). It handles ETH, WETH, and listed ERC-20s, in both directions: deposits (L1 → L2) land in minutes, and withdrawals (L2 → L1) follow the OP Stack's prove + finalize cycle (~7 days).

Coverage: Ethereum ↔ Base / Optimism / Unichain / Soneium / Ink.

note

Rail 2 (the legacy OP Custom Bridge / L1AviBridge) was removed in V6.1. If you used the V1 bridge, see the SkyBridge V1 (Legacy) section.

Rail 5 - Arbitrum Canonical (native ETH)​

Rail 5 deposits native ETH from Ethereum into Arbitrum-stack chains using each chain's canonical Delayed Inbox and Arbitrum's retryable ticket mechanism (createRetryableTicket) - the same path Arbitrum's own bridge UI uses. The EntryPoint calls the Inbox directly; this rail does not touch the Diamond at all.

Unlike Rails 1, 3, and 4, this rail is deposits only (Ethereum → L2) and native ETH only - no withdrawals, no ERC-20s. ERC-20s continue to bridge via CCIP, and USDC via CCTP.

Coverage: Ethereum → Arbitrum One, Ethereum → Robinhood Chain. Both chains settle directly on Ethereum (Robinhood is a true L2, not an L3 on Arbitrum One), so the same one-hop deposit path works for both.

Why not the other rails: Arbitrum's canonical interface (IInbox.createRetryableTicket) is not the OP Standard Bridge's IStandardBridge.bridgeETHTo (Rail 1 is OP-stack only), and it avoids the extra CCIP fee and WETH wrap/unwrap that the WETH-via-CCIP lane (Rail 3) requires. Robinhood Chain has no WETH-via-CCIP path at all, so Rail 5 is the only way to deliver native ETH there.

One-way today

Rail 5 only moves ETH from Ethereum to Arbitrum-stack chains. Arbitrum One → Ethereum ETH still works via the WETH-via-CCIP lane (Rail 3). Robinhood Chain → Ethereum native ETH has no SkyBridge return path yet.

See Bridge Arbitrum ETH for the user-facing walkthrough and EntryPoint - Rail routing for the contract interface.

Transfer flow (CCIP example)​

User wallet
  │  calls bridgeERC20(token, amount, destChain, recipient) + flat fee
  ▼
SkyBridgeEntryPoint (UUPS proxy, per-chain)
  │  validates, deducts fee, calls Diamond
  ▼
Diamond → BridgeFacet
  │  locks or burns token on source chain
  │  sends CCIP message via Chainlink router
  ▼
Chainlink CCIP network
  ▼
Diamond → BridgeReceiverFacet (destination chain)
  │  deploys SkyToken if first arrival (CREATE3)
  │  mints or unlocks token
  ▼
Recipient wallet

Fees accumulate in the EntryPoint and are pulled to the Fee Safe (0xA953B9DF3b081709eA75895cF5a8fAf7DCC29354, 2-of-3 Gnosis Safe) via the permissionless collectFees() function.