by Unity Nodes
docs.near.orgchain abstraction › omnibridge › implementation

Implementation Details

Updated 01-11-2026

View on docs.near.org

Explore Omni Bridge's technical architecture

The Omni Bridge is a sophisticated cross-chain bridge infrastructure that enables secure and efficient token transfers between NEAR Protocol and various other blockchain networks. This document provides a detailed technical overview of the bridge's architecture, covering its core components, security model, and operational mechanisms. By leveraging a combination of Multi-Party Computation (MPC), chain-specific light clients, and a relayer network, the bridge achieves a robust balance of security, decentralization, and user experience.

For reference code implementations, see:

The Bridge Token Factory Pattern

At the core of Omni Bridge is the Bridge Token Factory contract on NEAR that serves as both a token factory and custodian. This unified contract handles both native tokens from the source chain and bridged tokens created by the factory itself. This design simplifies maintenance and reduces complexity compared to having separate contracts.

The contract has several key responsibilities:

For bridged tokens (tokens originally from other chains):

  • Deploys new token contracts when bridging tokens for the first time
  • Mints tokens when receiving valid transfer messages
  • Burns tokens when initiating transfers back to the origin chain

For native NEAR tokens:

  • Acts as a custodian by locking tokens during transfers
  • Releases tokens when receiving valid transfer messages
  • Manages token operations through the NEP-141 standard

Transfer Lifecycle

A transfer's lifecycle includes several states, shown below for a NEAR to Ethereum transfer of native NEAR tokens:

stateDiagram-v2
    [*] --> Initiated: User calls transfer
    Initiated --> Locked: Tokens locked in bridge
    Locked --> Signed: MPC signature generated
    Signed --> Completed: Tokens released on Ethereum
    Completed --> [*]

Message Signing and Verification

For most chains, the bridge uses a payload-based message signing system (with Bitcoin being a notable exception requiring full transaction signing).

Message Types

The bridge supports several types of signed messages:

  • Transfer Messages
    • Initiation messages
    • Finalization messages
  • Token Messages
    • Deployment messages
    • Metadata update messages

Payload Structure

Messages are encoded using Borsh serialization and contain:

Component Description
Message Type Identifier for the message category
Chain Info Chain IDs and relevant addresses
Operation Data Amounts, recipients, fees, etc.

Signature Process

  1. The bridge contract on NEAR records the transfer when the tokens arrive
  2. A relayer calls sign_transfer, and the bridge asks the MPC contract (v1.signer) to sign the payload
  3. The MPC network signs it, and the bridge logs the signature in a SignTransferEvent
  4. Signature is verified on destination chains

[!TIP]

Key Benefits

  • Clearer message intent through structured payloads
  • More efficient signature verification on destination chains
  • Standardized message format across chains

Transaction Flow: NEAR to Other Chains

Here's an overview of how transfers are processed from NEAR to different destination chains:

flowchart TD
    Start[User Initiates Transfer] --> TokenCheck{Token Type?}
    
    TokenCheck -->|NEAR Native| Lock[Lock in Bridge Contract]
    TokenCheck -->|Bridged Token| Burn[Burn Token]
    
    Lock --> MPCSign[Request MPC Signature]
    Burn --> MPCSign
    
    MPCSign --> Chain{Destination Chain}
    
    Chain -->|Bitcoin| BTCBridge[Bitcoin Script]
    Chain -->|Other| OtherBridge[Verify MPC Signature]
    
    BTCBridge --> Mint[Mint/Release Tokens]
    OtherBridge --> Mint
    
    Mint --> End[Transfer Complete]

Transfer Process

Let's follow what happens when a user wants to transfer tokens from NEAR to another chain:

1. Initiation

The user starts by calling the token contract with:

  • Amount to transfer
  • Destination chain and address
  • Fee preferences (whether to pay fees in the token being transferred or in NEAR)
  • Fees are minted on NEAR side for relayers

2. Token Lock

The token contract transfers tokens to the locker contract, which:

  • Validates the transfer message
  • Assigns a unique nonce
  • Records the pending transfer
  • Emits a transfer event

3. MPC Signing

The bridge contract:

  • Requests signature generation
  • MPC nodes jointly generate and aggregate signature
  • Maintains threshold security throughout process

4. Destination Chain

The Bridge Token Factory on the destination chain:

  • Verifies the MPC signature
  • Mints equivalent tokens

Transaction Flow: Other Chains to NEAR

The reverse flow varies based on the source chain:

1. Ethereum

Uses NEAR light client for maximum security:

  • Burning tokens on source chain
  • Submitting proof to NEAR
  • Verifying proof through light client
  • Releasing tokens to recipient

2. Wormhole Chains (Solana, Fogo, Base, Arbitrum, BNB Chain, Polygon, HyperEVM)

Utilize established message passing protocols (such as Wormhole) for:

  • Message passing between chains
  • Transaction verification
  • Integration with NEAR token factory system

3. MPC-Verified Chains (Abstract, Starknet, Aptos)

The bridge's MPC prover asks the MPC network to check the source-chain transaction (verify_foreign_transaction on v1.signer) and accepts the transfer once the signed result verifies.

Transaction Flow: Chain to Chain (via NEAR)

For transfers between two non-NEAR chains (e.g., Ethereum to Solana), the bridge combines both flows using NEAR as an intermediary routing layer. Rather than minting or unlocking tokens on NEAR, the bridge creates a forwarding message that directs tokens to be minted or unlocked on the final destination chain.

From the user's perspective, this appears as a single operation - they initiate the transfer on the source chain, and the off-chain relayer infrastructure handles the intermediate NEAR routing automatically.

Security Model

Trust Assumptions

Omni Bridge requires different trust assumptions depending on the chain connection:

For Chain Signatures:

  • NEAR Protocol security (2/3+ honest validators)
  • MPC network security (2/3+ honest nodes)
  • No single entity controls enough MPC nodes to forge signatures
  • Correct implementation of the signing protocol

For Ethereum/Bitcoin connections:

  • Light client security
  • Finality assumptions (e.g., sufficient block confirmations)
  • Chain-specific consensus assumptions

For Message Passing connections:

  • Security of the underlying message passing protocol (e.g., Wormhole Guardian network)
  • Verified by NEAR network participants (e.g., validators and full nodes)

Relayer Network

Relayers are infrastructure operators who monitor for bridge events and execute cross-chain transactions. On NEAR, the relayer steps of omni.bridge.near (sign_transfer, fin_transfer, claim_fee and fast transfers) are open only to trusted relayers: accounts with the bridge's DAO or UnrestrictedRelayer role, or accounts that staked the required NEAR with apply_for_trusted_relayer and waited out the activation period. get_relayer_config returns the stake and the waiting period, and get_active_relayers lists the staked relayers. On EVM destination chains, anyone can submit an already-signed transfer to finTransfer.

Unlike many bridge designs, our relayers cannot:

  • Forge transfers
  • Steal funds
  • Front-run transactions for profit
  • Do not create additional security assumptions

[!NOTE]

The relayer's role is purely operational - executing valid transfers and collecting predetermined fees. Multiple relayers can operate simultaneously, creating competition for faster execution and lower fees. Relayers are paid from the fee set when a transfer starts, so a transfer with a zero fee may never be signed or finalized.

Fast Transfers

Standard cross-chain transfers can take time due to finality and verification requirements. Fast Transfers allow relayers to expedite this process by fronting liquidity.

How it Works

  1. User Initiation: A user sends a FastFinTransferMsg specifying the destination and fee.
  2. Relayer Execution: A trusted relayer detects the request and instantly transfers the equivalent amount (minus fees) to the user on the destination chain from their own funds.
  3. Settlement: The bridge later reimburses the relayer once the original transfer is fully verified and finalized.

[!TIP]

Fast transfers are ideal for users who prioritize speed over cost, as relayers may charge a premium for the liquidity and convenience.

Multi-Token Support (ERC1155)

Omni Bridge supports the ERC1155 standard, enabling the transfer of multiple token types within a single contract.

Address Derivation

To maintain consistency across chains, bridged ERC1155 tokens use a deterministic address derivation scheme:

  • Deterministic Address: keccak256(tokenAddress + tokenId)
  • This ensures that each tokenId within an ERC1155 contract maps to a unique, consistent address on the destination chain.

Key Functions

  • initTransfer1155: Initiates a transfer for a specific ERC1155 token ID.
  • logMetadata1155: Registers metadata for a specific token ID, ensuring it is recognized by indexers and wallets.

Fee Structure

Bridge fees are unified and processed on NEAR, with components including:

Execution Fees

  • Destination chain gas costs
  • Source chain storage costs
  • Relayer operational costs
  • MPC signing costs

Fee Payment Options

  • Native tokens of source chain
  • The token being transferred

[!NOTE]

Fees dynamically adjust based on gas prices across different chains to ensure reliable execution.

Design Goals

The fee structure is designed to:

  • Ensure relayer economic viability
  • Prevent economic attacks
  • Allow fee market competition
  • Cover worst-case execution costs

[!TIP]

On EVM destination chains, users can submit an already-signed transfer themselves, paying only that chain's gas. The steps on NEAR (signing an outbound transfer, finalizing an inbound one) need a trusted relayer.

Back to Documentation