Skip to main content

Architecture

SkyBridge V2 routes every transfer through a two-contract stack: a SkyBridgeEntryPoint you interact with directly, and a shared Diamond that holds the bridge logic. Three 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 on all 11 chains. 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 three rails​

SkyBridge's rails are numbered 1, 3, and 4 (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.

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.