deBridge Solana SDK Development Guide

A comprehensive guide for building Solana programs with the deBridge Solana SDK - enabling decentralized cross-chain transfers of arbitrary messages and value between blockchains.

Overview

deBridge is a cross-chain infrastructure protocol enabling:

• Cross-Chain Transfers: Bridge assets between Solana and 20+ EVM chains
• Message Passing: Send arbitrary messages across blockchains
• External Calls: Execute smart contract calls on destination chains
• Sub-Second Settlement: ~2 second median settlement time
• Capital Efficiency: Intent-based architecture with 4bps lowest spreads

Key Features

• 26+ security audits (Halborn, Zokyo, Ackee Blockchain)
• $200K bug bounty on Immunefi
• 100% uptime since launch
• Zero security incidents

Quick Start

Installation

Add the SDK to your Anchor/Solana program:

cargo add --git ssh://git@github.com/debridge-finance/debridge-solana-sdk.git debridge-solana-sdk

Or add to Cargo.toml:

[dependencies]
debridge-solana-sdk = { git = "ssh://git@github.com/debridge-finance/debridge-solana-sdk.git" }

Basic Setup (Anchor)

use anchor_lang::prelude::*;
use debridge_solana_sdk::prelude::*;

declare_id!("YourProgramId11111111111111111111111111111");

#[program]
pub mod my_bridge_program {
    use super::*;

    pub fn send_cross_chain(
        ctx: Context<SendCrossChain>,
        target_chain_id: [u8; 32],
        receiver: Vec<u8>,
        amount: u64,
    ) -> Result<()> {
        // Invoke deBridge send
        debridge_sending::invoke_debridge_send(
            debridge_sending::SendIx {
                target_chain_id,
                receiver,
                is_use_asset_fee: false,  // Use native SOL for fees
                amount,
                submission_params: None,
                referral_code: None,
            },
            ctx.remaining_accounts,
        )?;

        Ok(())
    }
}

#[derive(Accounts)]
pub struct SendCrossChain<'info> {
    #[account(mut)]
    pub sender: Signer<'info>,
    // Additional accounts passed via remaining_accounts
}

Core Concepts

1. Chain IDs

deBridge uses 32-byte chain identifiers for all supported networks:

use debridge_solana_sdk::chain_ids::*;

// Solana
let solana = SOLANA_CHAIN_ID;  // Solana mainnet

// EVM Chains
let ethereum = ETHEREUM_CHAIN_ID;     // Chain ID: 1
let polygon = POLYGON_CHAIN_ID;       // Chain ID: 137
let bnb = BNB_CHAIN_CHAIN_ID;         // Chain ID: 56
let arbitrum = ARBITRUM_CHAIN_ID;     // Chain ID: 42161
let avalanche = AVALANCHE_CHAIN_ID;   // Chain ID: 43114
let fantom = FANTOM_CHAIN_ID;         // Chain ID: 250
let heco = HECO_CHAIN_ID;             // Chain ID: 128

2. Program IDs

use debridge_solana_sdk::{DEBRIDGE_ID, SETTINGS_ID};

// Main deBridge program for sending/claiming
let debridge_program = DEBRIDGE_ID;

// Settings and confirmation storage program
let settings_program = SETTINGS_ID;

3. Fee Structure

deBridge supports multiple fee payment methods:

// Native Fee (SOL)
is_use_asset_fee: false  // Pay fees in SOL

// Asset Fee
is_use_asset_fee: true   // Pay fees in the bridged token

// Fee Constants
const BPS_DENOMINATOR: u64 = 10000;  // Basis points divisor

4. Flags

Control transfer behavior with flags:

use debridge_solana_sdk::flags::*;

// Available flags (bit positions)
const UNWRAP_ETH: u8 = 0;              // Unwrap to native ETH on destination
const REVERT_IF_EXTERNAL_FAIL: u8 = 1; // Revert if external call fails
const PROXY_WITH_SENDER: u8 = 2;       // Include sender in proxy call
const SEND_HASHED_DATA: u8 = 3;        // Send data as hash
const DIRECT_WALLET_FLOW: u8 = 31;     // Use direct wallet flow

// Setting flags on submission params
let mut flags = [0u8; 32];
flags.set_reserved_flag(UNWRAP_ETH);
flags.set_reserved_flag(REVERT_IF_EXTERNAL_FAIL);

Sending Cross-Chain Transfers

Basic Token Transfer

use debridge_solana_sdk::prelude::*;

pub fn send_tokens(
    ctx: Context<SendTokens>,
    amount: u64,
) -> Result<()> {
    debridge_sending::invoke_debridge_send(
        debridge_sending::SendIx {
            target_chain_id: chain_ids::ETHEREUM_CHAIN_ID,
            receiver: recipient_eth_address.to_vec(),
            is_use_asset_fee: false,
            amount,
            submission_params: None,
            referral_code: Some(12345),  // Optional referral
        },
        ctx.remaining_accounts,
    )?;

    Ok(())
}

Transfer with Fixed Native Fee

pub fn send_with_native_fee(
    ctx: Context<Send>,
    target_chain_id: [u8; 32],
    receiver: Vec<u8>,
    amount: u64,
) -> Result<()> {
    // Get the fixed fee for the target chain
    let fee = debridge_sending::get_chain_native_fix_fee(
        &target_chain_id,
        ctx.remaining_accounts,
    )?;

    debridge_sending::invoke_debridge_send(
        debridge_sending::SendIx {
            target_chain_id,
            receiver,
            is_use_asset_fee: false,
            amount,
            submission_params: None,
            referral_code: None,
        },
        ctx.remaining_accounts,
    )?;

    Ok(())
}

Transfer with Asset Fee

pub fn send_with_asset_fee(
    ctx: Context<Send>,
    target_chain_id: [u8; 32],
    receiver: Vec<u8>,
    amount: u64,
) -> Result<()> {
    // Check if asset fee is available for this chain
    let is_available = debridge_sending::is_asset_fee_available(
        &target_chain_id,
        ctx.remaining_accounts,
    )?;

    if !is_available {
        return Err(error!(ErrorCode::AssetFeeNotAvailable));
    }

    debridge_sending::invoke_debridge_send(
        debridge_sending::SendIx {
            target_chain_id,
            receiver,
            is_use_asset_fee: true,  // Use asset for fees
            amount,
            submission_params: None,
            referral_code: None,
        },
        ctx.remaining_accounts,
    )?;

    Ok(())
}

Transfer with Exact Amount

pub fn send_exact_amount(
    ctx: Context<Send>,
    target_chain_id: [u8; 32],
    receiver: Vec<u8>,
    exact_receive_amount: u64,
) -> Result<()> {
    // Calculate total amount including fees
    let total_with_fees = debridge_sending::add_all_fees(
        exact_receive_amount,
        &target_chain_id,
        ctx.remaining_accounts,
    )?;

    debridge_sending::invoke_debridge_send(
        debridge_sending::SendIx {
            target_chain_id,
            receiver,
            is_use_asset_fee: true,
            amount: total_with_fees,
            submission_params: None,
            referral_code: None,
        },
        ctx.remaining_accounts,
    )?;

    Ok(())
}

Transfer from PDA (Signed)

pub fn send_from_pda(
    ctx: Context<SendFromPda>,
    target_chain_id: [u8; 32],
    receiver: Vec<u8>,
    amount: u64,
    pda_seeds: Vec<Vec<u8>>,
) -> Result<()> {
    // Use signed variant for PDA-owned tokens
    debridge_sending::invoke_debridge_send_signed(
        debridge_sending::SendIx {
            target_chain_id,
            receiver,
            is_use_asset_fee: false,
            amount,
            submission_params: None,
            referral_code: None,
        },
        ctx.remaining_accounts,
        &pda_seeds,
    )?;

    Ok(())
}

Message Passing

Send messages without token transfers:

use debridge_solana_sdk::prelude::*;

pub fn send_message(
    ctx: Context<SendMessage>,
    target_chain_id: [u8; 32],
    receiver: Vec<u8>,
    message_data: Vec<u8>,
) -> Result<()> {
    // Create submission params with message
    let submission_params = debridge_sending::SendSubmissionParamsInput {
        execution_fee: 0,
        flags: [0u8; 32],
        fallback_address: receiver.clone(),
        external_call_shortcut: compute_keccak256(&message_data),
    };

    // Send message (zero amount)
    debridge_sending::invoke_send_message(
        debridge_sending::SendIx {
            target_chain_id,
            receiver,
            is_use_asset_fee: false,
            amount: 0,  // No token transfer
            submission_params: Some(submission_params),
            referral_code: None,
        },
        ctx.remaining_accounts,
    )?;

    Ok(())
}

External Calls

Execute smart contract calls on destination chains:

Initialize External Call Buffer

pub fn init_external_call(
    ctx: Context<InitExternalCall>,
    target_chain_id: [u8; 32],
    external_call_data: Vec<u8>,
) -> Result<()> {
    let shortcut = compute_keccak256(&external_call_data);

    debridge_sending::invoke_init_external_call(
        debridge_sending::InitExternalCallIx {
            external_call_len: external_call_data.len() as u32,
            chain_id: target_chain_id,
            external_call_shortcut: shortcut,
            external_call: external_call_data,
        },
        ctx.remaining_accounts,
    )?;

    Ok(())
}

Send with External Call

pub fn send_with_external_call(
    ctx: Context<SendWithExternalCall>,
    target_chain_id: [u8; 32],
    receiver: Vec<u8>,  // Target contract address
    amount: u64,
    external_call_data: Vec<u8>,
    execution_fee: u64,  // Fee for executor on destination
) -> Result<()> {
    let shortcut = compute_keccak256(&external_call_data);

    // Set flags for external call behavior
    let mut flags = [0u8; 32];
    flags.set_reserved_flag(flags::REVERT_IF_EXTERNAL_FAIL);

    let submission_params = debridge_sending::SendSubmissionParamsInput {
        execution_fee,
        flags,
        fallback_address: ctx.accounts.fallback.key().to_bytes().to_vec(),
        external_call_shortcut: shortcut,
    };

    debridge_sending::invoke_debridge_send(
        debridge_sending::SendIx {
            target_chain_id,
            receiver,
            is_use_asset_fee: false,
            amount,
            submission_params: Some(submission_params),
            referral_code: None,
        },
        ctx.remaining_accounts,
    )?;

    Ok(())
}

Claim Verification

Verify claims on the receiving side:

Validate Incoming Claims

use debridge_solana_sdk::check_claiming::*;

pub fn receive_tokens(ctx: Context<ReceiveTokens>) -> Result<()> {
    // Get and validate the parent claim instruction
    let claim_ix = ValidatedExecuteExtCallIx::try_from_current_ix()?;

    // Validate submission details
    let validation = SubmissionAccountValidation {
        receiver_validation: Some(ctx.accounts.receiver.key()),
        token_mint_validation: Some(ctx.accounts.token_mint.key()),
        source_chain_id_validation: Some(chain_ids::ETHEREUM_CHAIN_ID),
        ..Default::default()
    };

    claim_ix.validate_submission_account(
        &ctx.accounts.submission_account,
        &validation,
    )?;

    // Proceed with claim logic
    Ok(())
}

Get Submission Key

pub fn get_claim_info(ctx: Context<ClaimInfo>) -> Result<Pubkey> {
    let claim_ix = ValidatedExecuteExtCallIx::try_from_current_ix()?;
    let submission_key = claim_ix.get_submission_key()?;
    Ok(submission_key)
}

Fee Queries

Get Transfer Fees

// Get base transfer fee (in BPS)
let transfer_fee = debridge_sending::get_transfer_fee(
    ctx.remaining_accounts,
)?;

// Get transfer fee for specific chain
let chain_fee = debridge_sending::get_transfer_fee_for_chain(
    &target_chain_id,
    ctx.remaining_accounts,
)?;

// Get default native fix fee
let default_fee = debridge_sending::get_default_native_fix_fee(
    ctx.remaining_accounts,
)?;

// Get chain-specific native fix fee
let native_fee = debridge_sending::get_chain_native_fix_fee(
    &target_chain_id,
    ctx.remaining_accounts,
)?;

// Get asset fix fee for chain
let asset_fee = debridge_sending::try_get_chain_asset_fix_fee(
    &target_chain_id,
    ctx.remaining_accounts,
)?;

Calculate Total Amount with Fees

// Add transfer fee to amount
let with_transfer_fee = debridge_sending::add_transfer_fee(
    amount,
    ctx.remaining_accounts,
)?;

// Add all fees (transfer + execution + asset fees)
let total_amount = debridge_sending::add_all_fees(
    amount,
    &target_chain_id,
    ctx.remaining_accounts,
)?;

Chain Support Queries

// Check if chain is supported
let is_supported = debridge_sending::is_chain_supported(
    &target_chain_id,
    ctx.remaining_accounts,
)?;

// Get chain support info
let chain_info = debridge_sending::get_chain_support_info(
    &target_chain_id,
    ctx.remaining_accounts,
)?;

// Check if asset fee is available
let asset_fee_available = debridge_sending::is_asset_fee_available(
    &target_chain_id,
    ctx.remaining_accounts,
)?;

PDA Derivation

Bridge Account

use debridge_solana_sdk::keys::*;

// Find bridge PDA for a token mint
let (bridge_address, bump) = BridgePubkey::find_bridge_address(&token_mint);

// Create with known bump
let bridge_address = BridgePubkey::create_bridge_address(&token_mint, bump)?;

Chain Support Info

// Find chain support info PDA
let (chain_support_info, bump) = ChainSupportInfoPubkey::find_chain_support_info_address(
    &target_chain_id,
);

Asset Fee Info

// Find asset fee info PDA
let (asset_fee_info, bump) = AssetFeeInfoPubkey::find_asset_fee_info_address(
    &bridge_pubkey,
    &target_chain_id,
);

// Get default bridge fee address
let default_fee = AssetFeeInfoPubkey::default_bridge_fee_address();

External Call Storage

// Find external call storage PDA
let (storage, bump) = ExternalCallStoragePubkey::find_external_call_storage_address(
    &shortcut,
    &owner,
);

// Find external call meta PDA
let (meta, bump) = ExternalCallMetaPubkey::find_external_call_meta_address(
    &storage_account,
);

Required Accounts

The SDK requires specific accounts passed via remaining_accounts. The account order is important:

Index	Account	Signer	Writable	Description
0	Bridge	No	Yes	Bridge account for token
1	Token Mint	No	No	SPL Token mint
2	Staking Wallet	No	Yes	Staking rewards wallet
3	Mint Authority	No	No	Token mint authority
4	Chain Support Info	No	No	Target chain config
5	Settings Program	No	No	deBridge settings
6	SPL Token Program	No	No	Token program
7	State	No	No	Protocol state
8	deBridge Program	No	No	Main deBridge program
...	Additional accounts	-	-	Varies by operation

TypeScript Client Integration

Setup

import { Connection, Keypair, PublicKey, Transaction } from '@solana/web3.js';
import { Program, AnchorProvider, Wallet } from '@coral-xyz/anchor';

const connection = new Connection('https://api.mainnet-beta.solana.com');
const wallet = new Wallet(keypair);
const provider = new AnchorProvider(connection, wallet, {});

// deBridge Program IDs
const DEBRIDGE_PROGRAM_ID = new PublicKey('DEbrdGj3HsRsAzx6uH4MKyREKxVAfBydijLUF3ygsFfh');
const SETTINGS_PROGRAM_ID = new PublicKey('DeSetTwWhjZq6Pz9Kfdo1KoS5NqtsM6G8ERbX4SSCSft');

Build Send Transaction

import {
  TOKEN_PROGRAM_ID,
  getAssociatedTokenAddress
} from '@solana/spl-token';

async function buildSendTransaction(
  tokenMint: PublicKey,
  amount: bigint,
  targetChainId: Uint8Array,
  receiver: Uint8Array,
): Promise<Transaction> {
  // Derive required PDAs
  const [bridge] = PublicKey.findProgramAddressSync(
    [Buffer.from('BRIDGE'), tokenMint.toBuffer()],
    DEBRIDGE_PROGRAM_ID
  );

  const [chainSupportInfo] = PublicKey.findProgramAddressSync(
    [Buffer.from('CHAIN_SUPPORT_INFO'), targetChainId],
    SETTINGS_PROGRAM_ID
  );

  const [state] = PublicKey.findProgramAddressSync(
    [Buffer.from('STATE')],
    DEBRIDGE_PROGRAM_ID
  );

  // Build instruction with remaining accounts
  const instruction = await program.methods
    .sendViaDebridge(
      Array.from(targetChainId),
      Array.from(receiver),
      new BN(amount.toString()),
    )
    .remainingAccounts([
      { pubkey: bridge, isSigner: false, isWritable: true },
      { pubkey: tokenMint, isSigner: false, isWritable: false },
      // ... additional required accounts
    ])
    .instruction();

  return new Transaction().add(instruction);
}

Build External Call Data

import { ethers } from 'ethers';
import { keccak256 } from '@ethersproject/keccak256';

function buildExternalCallData(
  targetContract: string,
  functionSig: string,
  params: any[]
): { data: Uint8Array; shortcut: Uint8Array } {
  const iface = new ethers.Interface([functionSig]);
  const calldata = iface.encodeFunctionData(
    functionSig.split('(')[0].replace('function ', ''),
    params
  );

  const data = ethers.getBytes(calldata);
  const shortcut = ethers.getBytes(keccak256(data));

  return { data, shortcut };
}

// Example: ERC20 approve call
const { data, shortcut } = buildExternalCallData(
  '0xTargetContract...',
  'function approve(address spender, uint256 amount)',
  ['0xSpenderAddress...', ethers.parseEther('1000')]
);

Testing

Anchor Test Setup

# Anchor.toml
[provider]
cluster = "mainnet"  # Use mainnet for testing with real deBridge

[programs.mainnet]
my_program = "YourProgramId..."

Run Tests

# Full build and test
cd example_program && anchor build && anchor test

# Test only (skip rebuild)
anchor test --skip-build --skip-deploy

Local Testing Tips

1. Use Mainnet Fork: deBridge infrastructure is on mainnet
2. Mock Remaining Accounts: Create mock accounts for unit tests
3. Test Fee Calculations: Verify fee amounts before sending

Build Features

The SDK supports different environments via Cargo features:

# Production (default) - uses hardcoded program IDs
debridge-solana-sdk = { git = "..." }

# Custom environment - uses env vars
debridge-solana-sdk = { git = "...", features = ["env"] }

Environment variables for custom networks:

• DEBRIDGE_PROGRAM_PUBKEY: Custom deBridge program ID
• DEBRIDGE_SETTINGS_PROGRAM_PUBKEY: Custom settings program ID

Resources

• deBridge Documentation
• Solana SDK GitHub
• deBridge App
• Widget Integration
• API Reference

Skill Structure

debridge/
├── SKILL.md                          # This file
├── resources/
│   ├── sdk-api-reference.md          # Complete SDK API reference
│   ├── chain-ids.md                  # Supported chain identifiers
│   ├── program-ids.md                # Program IDs and PDAs
│   └── error-codes.md                # Error types and handling
├── examples/
│   ├── basic-transfer/               # Simple cross-chain transfer
│   ├── external-calls/               # External call execution
│   ├── message-passing/              # Message-only transfers
│   └── fee-configurations/           # Fee payment options
└── docs/
    └── troubleshooting.md            # Common issues and solutions

LayerZero

LayerZero V2 is an immutable, censorship-resistant messaging protocol for cross-chain communication. It enables smart contracts on different blockchains to send arbitrary messages to each other through a modular security stack of Decentralized Verifier Networks (DVNs). The core primitive is the OApp (Omnichain Application) — a contract that inherits OApp.sol and implements _lzSend / _lzReceive to send and receive cross-chain messages through EndpointV2.

What You Probably Got Wrong

AI agents trained before mid-2024 confuse V1 and V2 architecture. These are the critical corrections.

• V2 is NOT V1 — completely different architecture. V1 used LZApp, ILayerZeroEndpoint, and a monolithic oracle+relayer model. V2 uses OApp, EndpointV2, and modular DVNs+Executors. Do NOT import @layerzerolabs/solidity-examples — that is V1. Use @layerzerolabs/oapp-evm for V2.
• OFT burns on source, mints on destination — NOT a lock/mint bridge. The Omnichain Fungible Token standard burns tokens on the source chain and mints equivalent tokens on the destination. For existing ERC-20s that cannot add burn/mint, use OFTAdapter which locks on source and mints an OFT representation on destination.
• DVNs replace the V1 oracle+relayer model. V1 had a single Oracle and Relayer operated by LayerZero Labs. V2 decouples verification into configurable DVN sets — you choose which DVNs must verify your messages and set quorum thresholds.
• _lzSend requires proper fee estimation via quoteSend() or _quote(). You must call the quote function first to determine the exact MessagingFee (native + lzToken), then pass that fee as msg.value. Underpaying reverts.
• Peer addresses must be set on BOTH chains. Calling setPeer(dstEid, bytes32(peerAddress)) on chain A is not enough. You must also call setPeer(srcEid, bytes32(chainAAddress)) on chain B. Unset peers cause NoPeer reverts.
• Message ordering is NOT guaranteed unless you configure ordered delivery. V2 delivers messages in a nonce-based system, but by default the executor can deliver messages out of order. Use the OrderedNonce enforcement option if strict ordering matters.
• eid (Endpoint ID) is NOT the chain ID. LayerZero uses its own Endpoint ID system. Ethereum mainnet is eid 30101, Arbitrum is 30110, Base is 30184, Optimism is 30111, Polygon is 30109. Using chain IDs instead of eids is the most common integration mistake.
• Peer addresses are bytes32, not address. All peer addresses are stored as bytes32 to support non-EVM chains. For EVM addresses, left-pad with zeros: bytes32(uint256(uint160(addr))). Passing a raw address to setPeer will fail.
• The Executor is separate from DVNs. DVNs verify messages, but the Executor actually calls lzReceive on the destination. You can configure a custom Executor or use the LayerZero default. If you set gas limits too low in message options, the Executor will run out of gas on the destination.

Quick Start

Installation

npm install @layerzerolabs/oapp-evm @layerzerolabs/lz-evm-protocol-v2 @openzeppelin/contracts

For Foundry projects:

forge install LayerZero-Labs/LayerZero-v2

Minimal OApp Contract

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import {OApp, Origin, MessagingFee} from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

contract MyOApp is OApp {
    event MessageSent(uint32 dstEid, bytes payload, uint256 nativeFee);
    event MessageReceived(uint32 srcEid, bytes32 sender, bytes payload);

    constructor(
        address _endpoint,
        address _delegate
    ) OApp(_endpoint, _delegate) Ownable(_delegate) {}

    /// @notice Sends a message to a destination chain
    /// @param _dstEid Destination endpoint ID
    /// @param _payload Arbitrary bytes payload
    /// @param _options Message execution options (gas, value)
    function sendMessage(
        uint32 _dstEid,
        bytes calldata _payload,
        bytes calldata _options
    ) external payable {
        MessagingFee memory fee = _quote(_dstEid, _payload, _options, false);
        if (msg.value < fee.nativeFee) revert InsufficientFee(msg.value, fee.nativeFee);

        _lzSend(_dstEid, _payload, _options, fee, payable(msg.sender));

        emit MessageSent(_dstEid, _payload, fee.nativeFee);
    }

    /// @notice Quotes the fee for sending a message
    /// @param _dstEid Destination endpoint ID
    /// @param _payload Arbitrary bytes payload
    /// @param _options Message execution options
    /// @return fee The messaging fee breakdown
    function quote(
        uint32 _dstEid,
        bytes calldata _payload,
        bytes calldata _options
    ) external view returns (MessagingFee memory fee) {
        return _quote(_dstEid, _payload, _options, false);
    }

    /// @dev Called by EndpointV2 when a message arrives from a source chain
    function _lzReceive(
        Origin calldata _origin,
        bytes32 /*_guid*/,
        bytes calldata _payload,
        address /*_executor*/,
        bytes calldata /*_extraData*/
    ) internal override {
        emit MessageReceived(_origin.srcEid, _origin.sender, _payload);
    }

    error InsufficientFee(uint256 sent, uint256 required);
}

Client Setup (TypeScript)

import { createPublicClient, createWalletClient, http, parseAbi, type Address } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(process.env.RPC_URL),
});

const account = privateKeyToAccount(
  process.env.PRIVATE_KEY as `0x${string}`
);

const walletClient = createWalletClient({
  account,
  chain: mainnet,
  transport: http(process.env.RPC_URL),
});

Core Concepts

Architecture Overview

Source Chain                          Destination Chain
+-----------+                        +-----------+
|  Your     |  _lzSend()             |  Your     |
|  OApp     | -----> EndpointV2      |  OApp     |
+-----------+        |               +-----------+
                     |                     ^
                     v                     | lzReceive()
              +------------+         +------------+
              |  MessageLib |         | EndpointV2 |
              +------------+         +------------+
                     |                     ^
                     v                     |
              +------+------+        +-----+-----+
              | DVN 1 | DVN 2|       | Executor  |
              +------+------+        +-----------+
                     |                     ^
                     +---------------------+
                     (off-chain verification & relay)

OApp

The base contract for all cross-chain applications. Inherits from OAppSender and OAppReceiver. Manages peer addresses and delegates message send/receive through EndpointV2.

OFT (Omnichain Fungible Token)

An ERC-20 that natively supports cross-chain transfers. Burns on source, mints on destination. For existing tokens, OFTAdapter wraps them.

ONFT (Omnichain Non-Fungible Token)

ERC-721 that supports cross-chain transfers. Locks on source, mints on destination.

EndpointV2

The immutable on-chain entry point. One per chain. Handles message dispatching, DVN verification, and executor relay. Cannot be upgraded.

DVN (Decentralized Verifier Network)

Off-chain verifiers that attest to cross-chain message validity. Each OApp configures which DVNs must verify its messages. Multiple DVNs can be required for higher security.

Executor

Calls lzReceive() on the destination contract. The default LayerZero Executor is used unless overridden. Executors are paid via the messaging fee.

MessageLib

Handles message serialization, DVN verification, and nonce tracking. V2 uses UltraLightNodeV2 (ULN302) as the default send/receive library.

OApp Development

Sending Messages

// _lzSend is inherited from OAppSender
function _lzSend(
    uint32 _dstEid,          // destination endpoint ID
    bytes memory _message,    // encoded payload
    bytes memory _options,    // execution options (gas, value)
    MessagingFee memory _fee, // fee from _quote()
    address payable _refundAddress
) internal returns (MessagingReceipt memory receipt);

The full send flow:

function sendPing(uint32 _dstEid) external payable {
    bytes memory payload = abi.encode("ping", block.timestamp);

    // Build options: 200k gas for lzReceive on destination
    bytes memory options = OptionsBuilder.newOptions().addExecutorLzReceiveOption(200_000, 0);

    MessagingFee memory fee = _quote(_dstEid, payload, options, false);
    if (msg.value < fee.nativeFee) revert InsufficientFee(msg.value, fee.nativeFee);

    _lzSend(_dstEid, payload, options, fee, payable(msg.sender));
}

Receiving Messages

// Override _lzReceive to handle incoming messages
function _lzReceive(
    Origin calldata _origin,   // srcEid, sender (bytes32), nonce
    bytes32 _guid,             // globally unique message ID
    bytes calldata _payload,   // the message bytes
    address _executor,         // executor that delivered this
    bytes calldata _extraData  // additional data from executor
) internal override {
    (string memory message, uint256 timestamp) = abi.decode(_payload, (string, uint256));
    // Process the message
}

Peer Configuration

Peers must be set bidirectionally. The peer address is bytes32-encoded.

// On Ethereum OApp — register Arbitrum peer
oapp.setPeer(
    30110, // Arbitrum eid
    bytes32(uint256(uint160(arbitrumOAppAddress)))
);

// On Arbitrum OApp — register Ethereum peer
oapp.setPeer(
    30101, // Ethereum eid
    bytes32(uint256(uint160(ethereumOAppAddress)))
);

From TypeScript:

const oappAbi = parseAbi([
  "function setPeer(uint32 eid, bytes32 peer) external",
]);

function addressToBytes32(addr: Address): `0x${string}` {
  return `0x${addr.slice(2).padStart(64, "0")}` as `0x${string}`;
}

const { request } = await publicClient.simulateContract({
  address: ethereumOApp,
  abi: oappAbi,
  functionName: "setPeer",
  args: [30110, addressToBytes32(arbitrumOApp)],
  account: account.address,
});

const hash = await walletClient.writeContract(request);
const receipt = await publicClient.waitForTransactionReceipt({ hash });
if (receipt.status !== "success") throw new Error("setPeer reverted");

OFT (Omnichain Fungible Token)

Deploy a New OFT

For new tokens that do not already exist on any chain:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import {OFT} from "@layerzerolabs/oft-evm/contracts/OFT.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

contract MyToken is OFT {
    constructor(
        string memory _name,
        string memory _symbol,
        address _lzEndpoint,
        address _delegate
    ) OFT(_name, _symbol, _lzEndpoint, _delegate) Ownable(_delegate) {
        // Mint initial supply to deployer
        _mint(_delegate, 1_000_000 * 10 ** decimals());
    }
}

OFTAdapter for Existing ERC-20s

If an ERC-20 already exists and cannot be modified, deploy OFTAdapter on the token's home chain. It locks the original token and coordinates minting on remote chains.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import {OFTAdapter} from "@layerzerolabs/oft-evm/contracts/OFTAdapter.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

contract MyTokenAdapter is OFTAdapter {
    constructor(
        address _token,       // existing ERC-20 address
        address _lzEndpoint,
        address _delegate
    ) OFTAdapter(_token, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

Sending OFT Cross-Chain

const oftAbi = parseAbi([
  "function send((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) calldata sendParam, (uint256 nativeFee, uint256 lzTokenFee) calldata fee, address refundAddress) payable returns ((bytes32 guid, uint64 nonce, (uint256 nativeFee, uint256 lzTokenFee) fee) receipt)",
  "function quoteSend((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) calldata sendParam, bool payInLzToken) view returns ((uint256 nativeFee, uint256 lzTokenFee) fee)",
]);

const DST_EID = 30110; // Arbitrum
const AMOUNT = 1000_000000000000000000n; // 1000 tokens (18 decimals)

const sendParam = {
  dstEid: DST_EID,
  to: addressToBytes32(account.address),
  amountLD: AMOUNT,
  minAmountLD: (AMOUNT * 995n) / 1000n, // 0.5% slippage
  extraOptions: "0x" as `0x${string}`,
  composeMsg: "0x" as `0x${string}`,
  oftCmd: "0x" as `0x${string}`,
};

// Quote the fee
const fee = await publicClient.readContract({
  address: oftAddress,
  abi: oftAbi,
  functionName: "quoteSend",
  args: [sendParam, false],
});

// Execute the send
const { request } = await publicClient.simulateContract({
  address: oftAddress,
  abi: oftAbi,
  functionName: "send",
  args: [sendParam, fee, account.address],
  value: fee.nativeFee,
  account: account.address,
});

const hash = await walletClient.writeContract(request);
const receipt = await publicClient.waitForTransactionReceipt({ hash });
if (receipt.status !== "success") throw new Error("OFT send reverted");

OFT Shared Decimals

OFT uses a concept of "shared decimals" to normalize precision across chains. The default shared decimals is 6. Tokens with more than 6 decimals will have dust removed during transfers.

Local Decimals: 18 (standard ERC-20)
Shared Decimals: 6 (LayerZero default)
Dust removed: 12 decimal places

Sending 1.123456789012345678 tokens
Actually transferred: 1.123456000000000000 tokens
Dust lost: 0.000000789012345678 tokens

Override sharedDecimals() to change this behavior:

function sharedDecimals() public pure override returns (uint8) {
    return 8; // higher precision cross-chain
}

DVN & Security Configuration

Setting Required and Optional DVNs

Each OApp configures its security stack through the EndpointV2's delegate (typically the OApp owner).

import {SetConfigParam} from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/IMessageLibManager.sol";

struct UlnConfig {
    uint64 confirmations;         // block confirmations before DVN can verify
    uint8 requiredDVNCount;       // DVNs that MUST verify (all required)
    uint8 optionalDVNCount;       // DVNs from optional pool
    uint8 optionalDVNThreshold;   // how many optional DVNs must verify
    address[] requiredDVNs;       // addresses of required DVNs
    address[] optionalDVNs;       // addresses of optional DVNs
}

Example configuration — require LayerZero Labs DVN and one of two optional DVNs:

UlnConfig memory ulnConfig = UlnConfig({
    confirmations: 15,                  // 15 block confirmations
    requiredDVNCount: 1,
    optionalDVNCount: 2,
    optionalDVNThreshold: 1,            // 1 of 2 optional must verify
    requiredDVNs: [LZ_DVN_ADDRESS],
    optionalDVNs: [GOOGLE_DVN_ADDRESS, POLYHEDRA_DVN_ADDRESS]
});

Configuring via EndpointV2

const endpointAbi = parseAbi([
  "function setConfig(address oapp, address lib, (uint32 eid, uint32 configType, bytes config)[] calldata params) external",
]);

// ULN config type for send library
const CONFIG_TYPE_ULN = 2;

// Encode the ULN config
// confirmations(uint64) + requiredDVNCount(uint8) + optionalDVNCount(uint8)
// + optionalDVNThreshold(uint8) + requiredDVNs(address[]) + optionalDVNs(address[])
import { encodeAbiParameters, parseAbiParameters } from "viem";

const ulnConfigEncoded = encodeAbiParameters(
  parseAbiParameters("uint64, uint8, uint8, uint8, address[], address[]"),
  [
    15n,                                // confirmations
    1,                                  // requiredDVNCount
    2,                                  // optionalDVNCount
    1,                                  // optionalDVNThreshold
    [LZ_DVN],                           // requiredDVNs
    [GOOGLE_DVN, POLYHEDRA_DVN],        // optionalDVNs
  ]
);

Security Best Practices

• Always set at least one required DVN. The default config uses the LayerZero Labs DVN. For production, add at least one additional DVN (Google Cloud, Polyhedra, etc.).
• Set block confirmations appropriate to the chain. Ethereum: 15+, L2s (Arbitrum, Base, Optimism): 5+. Higher confirmations reduce reorg risk.
• Configure BOTH send and receive libraries. Security config applies per-direction. A message sent from Ethereum to Arbitrum uses Ethereum's send config AND Arbitrum's receive config. Configure both.

Message Options

Building Options with OptionsBuilder

import {OptionsBuilder} from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OptionsBuilder.sol";

using OptionsBuilder for bytes;

// Gas limit for lzReceive execution on destination
bytes memory options = OptionsBuilder.newOptions()
    .addExecutorLzReceiveOption(200_000, 0);

// Gas limit + native airdrop to recipient on destination
bytes memory optionsWithDrop = OptionsBuilder.newOptions()
    .addExecutorLzReceiveOption(200_000, 0)
    .addExecutorNativeDropOption(1 ether, receiverAddress);

// Composed message — triggers lzCompose after lzReceive
bytes memory composedOptions = OptionsBuilder.newOptions()
    .addExecutorLzReceiveOption(200_000, 0)
    .addExecutorLzComposeOption(0, 100_000, 0); // index, gas, value

// Ordered delivery — enforce nonce ordering
bytes memory orderedOptions = OptionsBuilder.newOptions()
    .addExecutorLzReceiveOption(200_000, 0)
    .addExecutorOrderedExecutionOption();

Options Encoding in TypeScript

import { encodePacked } from "viem";

// Option type constants
const EXECUTOR_WORKER_ID = 1;
const OPTION_TYPE_LZRECEIVE = 1;
const OPTION_TYPE_NATIVE_DROP = 2;

// Encode lzReceive option: 200k gas, 0 value
// Format: workerID(uint8) + optionLength(uint16) + optionType(uint8) + gas(uint128) + value(uint128)
function buildLzReceiveOption(gasLimit: bigint, value: bigint = 0n): `0x${string}` {
  // Options V2 encoding
  const TYPE_3 = "0x0003" as `0x${string}`;
  const workerIdAndOption = encodePacked(
    ["uint8", "uint16", "uint8", "uint128", "uint128"],
    [EXECUTOR_WORKER_ID, 34, OPTION_TYPE_LZRECEIVE, gasLimit, value]
  );
  return `${TYPE_3}${workerIdAndOption.slice(2)}` as `0x${string}`;
}

const options = buildLzReceiveOption(200_000n);

Composed Messages

Composed messages allow an OApp to trigger follow-up logic after the initial lzReceive. The destination contract receives the message in lzReceive, then the Executor calls lzCompose separately.

// In your OApp
function _lzReceive(
    Origin calldata _origin,
    bytes32 _guid,
    bytes calldata _payload,
    address _executor,
    bytes calldata _extraData
) internal override {
    // Decode and store state from the message

    // Queue a composed message for follow-up execution
    endpoint.sendCompose(
        address(this), // composeTo — typically self
        _guid,
        0,             // compose index
        _payload       // data for lzCompose
    );
}

// Called by the Executor after lzReceive completes
function lzCompose(
    address _from,
    bytes32 _guid,
    bytes calldata _message,
    address _executor,
    bytes calldata _extraData
) external payable {
    require(msg.sender == address(endpoint), "Only endpoint");
    // Execute follow-up logic (swap, stake, etc.)
}

Deployment Pattern

Multi-Chain Deploy Sequence

1. Deploy OApp on each chain (with that chain's EndpointV2 address)
2. Set peers bidirectionally between every chain pair
3. Configure DVNs for each pathway
4. Verify with a test message

const ENDPOINT_V2: Record<number, Address> = {
  30101: "0x1a44076050125825900e736c501f859c50fE728c", // Ethereum
  30110: "0x1a44076050125825900e736c501f859c50fE728c", // Arbitrum
  30184: "0x1a44076050125825900e736c501f859c50fE728c", // Base
  30111: "0x1a44076050125825900e736c501f859c50fE728c", // Optimism
  30109: "0x1a44076050125825900e736c501f859c50fE728c", // Polygon
};

// After deploying OApp on each chain, set peers pairwise
async function setPeers(
  deployments: Map<number, Address>,
  walletClients: Map<number, typeof walletClient>,
  publicClients: Map<number, typeof publicClient>,
) {
  const eids = [...deployments.keys()];

  for (const srcEid of eids) {
    for (const dstEid of eids) {
      if (srcEid === dstEid) continue;

      const oapp = deployments.get(srcEid)!;
      const peer = deployments.get(dstEid)!;
      const client = walletClients.get(srcEid)!;
      const pub = publicClients.get(srcEid)!;

      const { request } = await pub.simulateContract({
        address: oapp,
        abi: oappAbi,
        functionName: "setPeer",
        args: [dstEid, addressToBytes32(peer)],
        account: account.address,
      });

      const hash = await client.writeContract(request);
      const receipt = await pub.waitForTransactionReceipt({ hash });
      if (receipt.status !== "success") {
        throw new Error(`setPeer failed: ${srcEid} -> ${dstEid}`);
      }
    }
  }
}

Hardhat Deploy Script

import { ethers } from "hardhat";

async function main() {
  const [deployer] = await ethers.getSigners();
  const endpointV2 = "0x1a44076050125825900e736c501f859c50fE728c";

  const MyOApp = await ethers.getContractFactory("MyOApp");
  const oapp = await MyOApp.deploy(endpointV2, deployer.address);
  await oapp.waitForDeployment();

  const address = await oapp.getAddress();
  console.log(`MyOApp deployed at: ${address}`);

  // Verify on explorer
  await run("verify:verify", {
    address,
    constructorArguments: [endpointV2, deployer.address],
  });
}

main().catch(console.error);

Foundry Deploy Script

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import {Script, console} from "forge-std/Script.sol";
import {MyOApp} from "../src/MyOApp.sol";

contract DeployOApp is Script {
    function run() external {
        uint256 deployerKey = vm.envUint("PRIVATE_KEY");
        address endpoint = 0x1a44076050125825900e736c501f859c50fE728c;
        address delegate = vm.addr(deployerKey);

        vm.startBroadcast(deployerKey);
        MyOApp oapp = new MyOApp(endpoint, delegate);
        console.log("MyOApp deployed:", address(oapp));
        vm.stopBroadcast();
    }
}

Fee Estimation

Quoting Send Fees

Always quote before sending. The fee depends on payload size, message options (gas, native drop), DVN configuration, and destination chain gas prices.

const oappAbi = parseAbi([
  "function quote(uint32 dstEid, bytes calldata payload, bytes calldata options) view returns ((uint256 nativeFee, uint256 lzTokenFee) fee)",
]);

const fee = await publicClient.readContract({
  address: oappAddress,
  abi: oappAbi,
  functionName: "quote",
  args: [30110, payload, options],
});

// fee.nativeFee — amount of ETH/native token to send as msg.value
// fee.lzTokenFee — if paying with ZRO token (usually 0)

Fee Breakdown

Component	Determines
DVN fees	Cost of DVN verification (based on DVN count and destination)
Executor fee	Gas cost of calling lzReceive on destination + native drop
Treasury fee	Protocol fee paid to LayerZero treasury

Paying with LZ Token (ZRO)

// To pay with ZRO instead of native:
// 1. Approve ZRO token to EndpointV2
// 2. Pass payInLzToken = true in quote
// 3. lzTokenFee will be non-zero, nativeFee reduced
MessagingFee memory fee = _quote(_dstEid, _payload, _options, true);
// fee.lzTokenFee > 0, fee.nativeFee may be lower

Error Handling

Common Reverts

Error	Cause	Fix
NoPeer	Peer not set for destination eid	Call setPeer(dstEid, peerBytes32) on source
OnlyPeer	Message from unregistered sender	Set peer on the receiving chain
InvalidEndpointCall	Direct call instead of via endpoint	Only EndpointV2 can call lzReceive
InsufficientFee	msg.value less than quoted fee	Call _quote() or quoteSend() first, pass exact fee
LzTokenUnavailable	Trying to pay with ZRO when not enabled	Pass false for payInLzToken parameter
InvalidOptions	Malformed options bytes	Use OptionsBuilder to construct options
SlippageExceeded	OFT minAmountLD check failed	Increase minAmountLD tolerance or retry
InvalidAmount	OFT amount below shared decimal minimum	Send larger amount; dust below shared decimals is removed
Unauthorized	Caller is not the delegate/owner	Check OApp ownership and delegate settings
InvalidEid	Endpoint ID does not exist	Use correct eid from LayerZero docs (NOT chain ID)

Debugging Cross-Chain Failures

1. Check source chain transaction. If it reverted, the message was never sent. Fix the source-side issue (fee, peer, options).

2. Use LayerZero Scan. Go to layerzeroscan.com and enter the source tx hash. It shows message status: Sent, Verifying, Verified, Delivered, or Failed.

3. Check DVN verification status. If stuck at "Verifying", DVNs have not confirmed yet. Wait for block confirmations, or check if your DVN config is valid.

4. Check executor delivery. If verified but not delivered, the Executor may have failed. Common cause: insufficient gas in options. Increase lzReceiveOption gas limit.

5. Retry failed messages. If lzReceive reverted on destination, the message is stored and can be retried:

const endpointAbi = parseAbi([
  "function retryPayload(uint32 srcEid, bytes32 sender, uint64 nonce, bytes calldata payload) external payable",
]);

6. Common debugging commands:

# Check if peer is set
cast call <oapp_address> "peers(uint32)(bytes32)" 30110 --rpc-url $RPC_URL

# Check endpoint delegate
cast call <oapp_address> "endpoint()(address)" --rpc-url $RPC_URL

# Verify contract has code
cast code <oapp_address> --rpc-url $RPC_URL

Contract Addresses

Last verified: February 2026

EndpointV2

Chain	eid	EndpointV2
Ethereum	30101	0x1a44076050125825900e736c501f859c50fE728c
Arbitrum	30110	0x1a44076050125825900e736c501f859c50fE728c
Optimism	30111	0x1a44076050125825900e736c501f859c50fE728c
Polygon	30109	0x1a44076050125825900e736c501f859c50fE728c
Base	30184	0x1a44076050125825900e736c501f859c50fE728c

Send/Receive Libraries (ULN302)

Chain	SendUln302	ReceiveUln302
Ethereum	0xbB2Ea70C9E858123480642Cf96acbcCE1372dCe1	0xc02Ab410f0734EFa3F14628780e6e695156024C2
Arbitrum	0x975bcD720be66659e3EB3C0e4F1866a3020E493A	0x7B9E184e07a6EE1aC23eAe0fe8D6Be60f4f19eF3
Base	0xB5320B0B3a13cC860893E2Bd79FCd7e13484Dda2	0xc70AB6f32772f59fBfc23889Caf4Ba3376C84bAf
Optimism	0x1322871e4ab09Bc7f5717189434f97bBD9546e95	0x3c4962Ff6258dcfCafD23a814237571571899985
Polygon	0x6c26c61a97006888ea9E4FA36584c7df57Cd9dA3	0x1322871e4ab09Bc7f5717189434f97bBD9546e95

LayerZero Labs DVN

Chain	Address
Ethereum	0x589dEDbD617eE7783Ae3a7427E16b13280a2C00C
Arbitrum	0x2f55C492897526677C5B68fb199ea31E2c126416
Base	0x9e059a54699a285714207b43B055483E78FAac25
Optimism	0x6A02D83e8d433304bba74EF1c427913958187142
Polygon	0x23DE2FE932d9043291f870F07B7D2Bbca42e46c6

Default Executor

Chain	Address
Ethereum	0x173272739Bd7Aa6e4e214714048a9fE699453059
Arbitrum	0x31CAe3B7fB82d847621859571BF619D4600e37c8
Base	0x2CCA08ae69E0C44b18a57Ab36A1CCb013C54B1d3
Optimism	0x2D2ea0697bdbede3F01553D2Ae4B8d0c486B666e
Polygon	0xCd3F213AD101472e1713C72B1697E727C803885b

References

• LayerZero V2 Docs
• OApp Developer Guide
• OFT Developer Guide
• EndpointV2 Reference
• DVN Addresses
• LayerZero Scan
• LayerZero V2 GitHub
• OptionsBuilder Reference
• @layerzerolabs/oapp-evm