Create documentation for omni bridge (#2441)

* Create omnibridge.svg * add omnibridge * 2430 suggestions (#2461) * fix: update near logo (#2453) * Add Lantstool examples for RPC - Access Keys (#2456) * Chain abstraction overview update (#2420) * update * Update what-is.md * Update docs/2.build/1.chain-abstraction/what-is.md Co-authored-by: Josh Ford <[email protected]> * update * Update what-is.md * Update what-is.md * Update what-is.md * diagram * 2379 suggestions (#2457) * fix: simplify intro & overview * feat: expand upon what is CA * feat: enhance intent/solver layer * feat: improve chain sig section * feat: improve omnibridge section * fix: remove duplicate section * fix: remove realyers * fix: remove use-cases -> locate elsewhere * fix: rethink intro based on article updates * fix: minor edits --------- Co-authored-by: Josh Ford <[email protected]> * feat: reorg omnibridge docs and add hackmd content * fix: update omnibridge overview and consolidate into one file --------- Co-authored-by: Volodymyr Bilyk <[email protected]> Co-authored-by: Damián Parrino <[email protected]> * fix: move to omnibridge directory * fix: update architecture description & chain sig link * fix: update intro and add background * feat: enhance background * feat: separate implementation and roadmap into separate docs * fix: update omni bridge overview in what-is chain abstraction * fix: update what-is and implementation * change path * Apply suggestions from code review * Update how-it-works.md * Delete website/static/docs/assets/omnibridge.svg * feat: add more references to SDK for higher visibility * fix: add improvement suggestions * fix: infeasible -> impossible --------- Co-authored-by: Josh Ford <[email protected]> Co-authored-by: Volodymyr Bilyk <[email protected]>
near · Feb 13, 2025 · 0112951 · 0112951
1 parent 914ecc9
commit 0112951
Show file tree

Hide file tree

Showing 6 changed files with 463 additions and 14 deletions.
diff --git a/docs/2.build/1.chain-abstraction/what-is.md b/docs/2.build/1.chain-abstraction/what-is.md
@@ -45,7 +45,7 @@ NEAR's chain abstraction framework consists of three core technologies that work
 
 2. [**Chain Signatures**](#chain-signatures): Enables NEAR accounts, including smart contracts, to sign and execute transactions on other blockchains (like Bitcoin or Ethereum), allowing cross-chain interactions.
 
-3. [**OmniBridge**](#omnibridge): A trustless multi-chain asset bridge that combines Chain Signatures for cross-chain transaction execution with a verification layer allowing NEAR smart contracts to confirm transactions on foreign chains. This creates a fully trustless system where NEAR can both initiate and verify cross-chain operations.
+3. [**OmniBridge**](#omnibridge): A multi-chain asset bridge that combines Chain Signatures with chain-specific verification methods for secure and efficient cross-chain transfers. Using a hybrid approach of MPC-based signatures and light clients, it significantly reduces verification times from hours to minutes while lowering gas costs across supported chains. The bridge serves as both a token factory and custodian, managing native and bridged tokens through a unified interface.
 
 ### Intent / Solver Layer
 
@@ -109,21 +109,27 @@ To learn more about Chain Signatures, the concepts, and how to implement it, che
 
 ### OmniBridge
 
-The [OmniBridge](https://github.com/Near-One/omni-bridge) extends NEAR's chain abstraction capabilities by combining two key elements: Chain Signatures for cross-chain transaction execution, and a verification layer that allows NEAR smart contracts to confirm the state and transactions on foreign chains. This creates a trustless bridge where NEAR contracts can both initiate and verify cross-chain operations.
+The [OmniBridge](../../chain-abstraction/omnibridge/overview.md) is a multi-chain asset bridge that combines Chain Signatures with chain-specific verification methods to enable secure and efficient cross-chain asset transfers. It consists of three core components:
 
 1. **Chain Signatures Integration**:
-   - NEAR smart contracts can generate derivation addresses on other blockchains
-   - These contracts can directly sign and execute transactions on external chains
+   - Enables NEAR smart contracts to generate and control accounts on other blockchains
+   - Allows direct signing and execution of transactions on external chains
+   - Provides secure message signing through MPC network
 
-2. **State Verification Layer (Omniprover)**:
-   - Allows NEAR smart contracts to verify the state and transactions on foreign chains
-   - Supports different verification methods based on the target chain (e.g., light client proofs)
-   - Ensures trustless verification of incoming transfers and state changes from external chains
-   - For example, when receiving assets from Ethereum, NEAR contracts can verify the deposit actually occurred
+2. **Verification Layer**:
+   - Hybrid verification approach combining MPC signatures and light clients
+   - Chain-specific verification methods based on target chain requirements
+   - Significantly reduces verification times from hours to minutes
+   - Lowers gas costs across all supported chains
 
-3. **Decentralized Relayer Network**:
-   - Open participation model for relayers
-   - Trustless and incentivized system
-   - Ensures efficient transaction processing and state updates across chains
+3. **Bridge Token Factory**:
+   - Unified contract serving as both token factory and custodian
+   - Manages both native and bridged tokens through NEP-141 standard
+   - Handles token locking, minting, and burning operations
+   - Supports permissionless relayer network for efficient processing
 
-This architecture creates a fully trustless bridge by combining NEAR's ability to execute transactions on foreign chains (via Chain Signatures) with the capability to independently verify the results of those transactions (via Omniprover).
+This architecture creates a robust bridge system that combines NEAR's ability to execute transactions on foreign chains with secure verification methods, while maintaining high efficiency and security through MPC threshold guarantees.
+
+:::info
+For detailed implementation information and current status, see the [OmniBridge documentation](../../chain-abstraction/omnibridge/overview.md).
+:::
diff --git a/docs/chain-abstraction/omnibridge/how-it-works.md b/docs/chain-abstraction/omnibridge/how-it-works.md
@@ -0,0 +1,82 @@
+---
+id: how-it-works
+sidebar_label: How It Works
+title: How Omni Bridge Works
+---
+
+## Background
+
+The journey toward truly trustless cross-chain communication took a significant leap forward when the NEAR team [created the first trustless bridge with Ethereum](https://near.org/blog/the-rainbow-bridge-is-live) (Rainbow Bridge). This pioneering achievement demonstrated that completely trustless cross-chain communication was possible, marking a crucial step toward the vision of chain abstraction. However, this approach relied on implementing a NEAR light client directly on Ethereum - essentially requiring Ethereum to understand and verify NEAR's complex blockchain rules.
+
+Omni Bridge introduces a more elegant solution using Chain Signatures. Instead of running light clients on each destination chain, it leverages Chain Signature's MPC Service to enable secure cross-chain message verification without the overhead of light client verification. This new approach reduces verification times from hours to minutes while significantly reducing gas costs across all supported chains.
+
+### Issues with Light Clients
+
+A light client is a smart contract that lets one blockchain verify events happening on another blockchain. In Rainbow Bridge's case, the Ethereum light client needs to track NEAR's blocks, verify its validators' signatures, and confirm transactions. This comes with major technical challenges: it requires storing two weeks of Ethereum block data, maintaining an updated list of NEAR validators and their stakes, and most crucially, verifying NEAR's ED25519 signatures - a process Ethereum wasn't built for. This verification is computationally expensive, making the whole process slow, costly, and ultimately a major bottleneck.
+
+For example, with Rainbow Bridge, transactions from NEAR to Ethereum take between 4 and 8 hours due to the 4-hour challenge period and block submission intervals driven by Ethereum's high gas costs. More importantly, this approach becomes increasingly impractical when connecting to multiple chains, as each chain would require its own light client implementation. Some chains, such as Bitcoin, don't even support smart contracts, making it technically impossible to implement a NEAR light client.
+
+While we still need to support light clients of different networks on NEAR (which is significantly easier to implement), a different approach is needed for verifying NEAR state on foreign chains.
+
+### Token Standards and Cross-Chain Communication
+
+Before exploring how Chain Signatures solves these issues, it's important to understand how tokens work on NEAR. [NEP-141](https://nomicon.io/Standards/Tokens/FungibleToken/Core), NEAR's fungible token standard, has a key feature that sets it apart from Ethereum's ERC-20: built-in composability through transfer-and-call functionality.
+
+When a token transfer happens on NEAR using `ft_transfer_call`, the token contract first transfers the tokens and then automatically calls the specified `ft_on_transfer` method on the receiver contract. While these operations happen in sequence within the same transaction, the receiver contract has the ability to reject the transfer, causing the tokens to be refunded. This atomic behavior ensures the integrity and safety of bridge operations by preventing partial execution states.
+
+For more information see [Fungible Tokens](../../2.build/5.primitives/ft.md).
+
+## Enter Chain Signatures
+
+Instead of maintaining complex light clients on destination chains, Chain Signatures introduces a fundamentally different approach based on three core components:
+
+1. **Deterministic Address Derivation** - Every NEAR account can mathematically derive addresses on other chains through derivation paths. This isn't just a mapping - it's a cryptographic derivation that ensures the same NEAR account always controls the same set of addresses across all supported chains.
+
+2. **Bridge Smart Contract** - A central contract on NEAR coordinates with the MPC network to generate secure signatures for cross-chain transactions. This contract handles the token locking and requesting of signatures for outbound transfers
+
+3. **MPC Service** - A decentralized network of nodes that jointly sign transactions without ever reconstructing a full private key. The security comes from threshold cryptography - no single node or small group of nodes can create valid signatures alone.
+
+## Putting It All Together
+
+As we've learned, Chain Signatures fundamentally changes the verification mechanism for cross-chain messages. Here's what this means in practice:
+
+The light client approach requires destination chains to verify ED25519 signatures from NEAR validators. Chain Signatures replaces this with a single MPC signature verification. Destination chains only need to verify one signature using their native signature verification schemes - typically ECDSA for EVM chains.
+
+NEP-141's transaction guarantees handle the security of token locking. A transfer creates two operations within a **single transaction**:
+1. Lock tokens and record the transfer state
+2. Request MPC signature for the destination chain
+
+The Locker contract requests signatures from the MPC network, which then generates signatures for valid transfer requests. This replaces the need for challenge periods - the security derives from the MPC threshold guarantees rather than optimistic assumptions.
+
+Adding new chains becomes a matter of implementing three standard components:
+1. Chain-specific address derivation
+2. MPC signature verification (or transaction signing for chains like Bitcoin)
+3. Bridge contract deployment
+4. Communication path for transfers back to NEAR (currently using Wormhole for newer chains)
+
+While we still need light clients on NEAR for receiving transfers from other chains, this approach makes it feasible to support a wider range of chains without implementing complex verification logic on each destination chain.
+
+
+```mermaid
+sequenceDiagram
+   title: High-Level Overview of NEAR to External Chain Transfer
+   participant User as User Account
+   participant Bridge as Omni Bridge <br> Locker Contract
+   participant MPC as MPC Service <br> (off-chain)
+   participant Other as Destination Chain
+
+   note over User, Bridge: NEAR Blockchain
+ 
+    User->>Bridge:1. Submits transfer <br> token request
+    Bridge->>Bridge: 2. Locks tokens
+    Bridge->>MPC: 3. Request signature
+    MPC->>MPC: 3. Signs message
+    MPC-->>Bridge: 4. Return signed msg
+    Bridge->>Other: 5. Broadcast signed msg to destination chain
+    Other->>Other: 4. Mint/release tokens
+```
+
+To get started building with Omni Bridge, see:
+
+- [Bridge SDK JS](https://github.com/near-one/bridge-sdk-js) Omni Bridge implementation in JavaScript
+- [Bridge SDK Rust](https://github.com/near-one/bridge-sdk-rs) Omni Bridge implementation in Rust
diff --git a/docs/chain-abstraction/omnibridge/implementation.md b/docs/chain-abstraction/omnibridge/implementation.md
@@ -0,0 +1,258 @@
+---
+id: implementation-details
+sidebar_label: Implementation Details
+title: Implementation Details
+---
+
+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 permissionless relayer network, the bridge achieves a robust balance of security, decentralization, and user experience.
+
+For referece code implementations, see:
+
+- [Bridge SDK JS](https://github.com/near-one/bridge-sdk-js) Omni Bridge implementation in JavaScript
+- [Bridge SDK Rust](https://github.com/near-one/bridge-sdk-rs) Omni Bridge implementation in Rust
+
+---
+
+## 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:
+
+```mermaid
+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. NEAR contract creates and stores the message payload
+2. MPC network observers detect valid payloads
+3. Nodes jointly sign the payload
+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:
+
+```mermaid
+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 -->|Ethereum| EVMBridge[EVM Bridge Contract]
+    Chain -->|Bitcoin| BTCBridge[Bitcoin Script]
+    Chain -->|Other| WormBridge[Wormhole Bridge]
+    
+    EVMBridge --> Mint[Mint/Release Tokens]
+    BTCBridge --> Mint
+    WormBridge --> 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. Solana
+
+Currently using Wormhole for:
+
+* Message passing between chains
+* Transaction verification
+* Integration with NEAR token factory system
+
+### 3. Other Chains
+
+Initially using Wormhole for:
+
+* Message passing between chains
+* Transaction verification
+* Will transition to Chain Signatures
+
+---
+
+## 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 interim Wormhole connections:
+
+* Wormhole Guardian network security
+* We acknowledge this is a temporary trust assumption until Chain Signatures integration is complete
+
+---
+
+## Relayer Network
+
+Relayers are permissionless infrastructure operators who monitor for bridge events and execute cross-chain transactions. Unlike many bridge designs, our relayers cannot:
+
+* Forge transfers
+* Steal funds
+* Censor transactions (users can self-relay)
+* Front-run transactions for profit
+* Do not create additional security assumptions
+
+:::info
+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.
+:::
+
+---
+
+## 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
+Users can bypass relayers entirely by executing their own transfers, paying only the necessary gas fees on each chain. This creates a natural ceiling on relayer fees.
+:::
+