Comparing arbitrum with layerzero

arbitrum

View full →

Author

@0xinit

Stars

Repository

0xinit/cryptoskills

skills/arbitrum/SKILL.md

Arbitrum

Arbitrum is the largest Ethereum L2 by TVL, running an optimistic rollup via the Nitro execution engine. Nitro compiles a modified Geth (go-ethereum) to WASM, enabling full EVM equivalence with fraud proofs. Arbitrum One targets general-purpose DeFi, Arbitrum Nova uses AnyTrust (data availability committee) for high-throughput gaming/social, and Orbit lets teams launch custom L3s settling to Arbitrum.

What You Probably Got Wrong

AI models trained before late 2024 carry stale assumptions about Arbitrum. These corrections are critical.

block.number returns the L1 block number, not L2 — On Arbitrum, block.number in Solidity returns the L1 Ethereum block number at the time the sequencer processed the transaction. Use ArbSys(0x64).arbBlockNumber() for the actual L2 block number.
block.timestamp is the L1 timestamp — Same issue. block.timestamp reflects L1 time. For L2ley timing use ArbSys(0x64).arbBlockNumber() and correlate.
Arbitrum does NOT have the same gas model as Ethereum — Every Arbitrum transaction pays two gas components: (1) L2 execution gas (similar to Ethereum but cheaper), and (2) L1 data posting cost (calldata compressed and posted to Ethereum). The L1 component often dominates for data-heavy transactions. Use NodeInterface.gasEstimateComponents() to get the breakdown.
You need --legacy for Foundry deployments — Arbitrum's sequencer does not support EIP-1559 type-2 transactions natively in forge scripts. Use --legacy flag or your deployment will fail with a cryptic RPC error.
msg.sender in cross-chain calls is aliased — When an L1 contract sends a message to L2 via retryable tickets, msg.sender on L2 is NOT the L1 contract address. It is the L1 address + 0x1111000000000000000000000000000000001111 (the "address alias"). This prevents L1/L2 address collision attacks.
Retryable tickets can fail silently — An L1-to-L2 retryable ticket that runs out of gas on L2 does NOT revert on L1. It sits in the retry buffer for 7 days. You must monitor and manually redeem failed retryables, or your cross-chain message is lost after the TTL.
Withdrawals take 7 days, not minutes — L2-to-L1 messages go through the optimistic rollup challenge period. After calling ArbSys.sendTxToL1(), the user must wait ~7 days, then execute the message on L1 via the Outbox contract. There is no fast path in the native bridge.
There is no mempool — Arbitrum uses a centralized sequencer that orders transactions on a first-come-first-served basis. There is no traditional mempool, so MEV extraction works differently (no frontrunning via gas price bidding).

Quick Start

Chain Configuration

import { defineChain } from "viem";
import { arbitrum, arbitrumNova, arbitrumSepolia } from "viem/chains";

// Arbitrum One — mainnet
// Chain ID: 42161
// RPC: https://arb1.arbitrum.io/rpc (public, rate-limited)

// Arbitrum Nova — AnyTrust chain for gaming/social
// Chain ID: 42170
// RPC: https://nova.arbitrum.io/rpc

// Arbitrum Sepolia — testnet
// Chain ID: 421614
// RPC: https://sepolia-rollup.arbitrum.io/rpc

Client Setup

import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { arbitrum } from "viem/chains";

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

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

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

Chain Details

Property	Arbitrum One	Arbitrum Nova	Arbitrum Sepolia
Chain ID	42161	42170	421614
RPC	`https://arb1.arbitrum.io/rpc`	`https://nova.arbitrum.io/rpc`	`https://sepolia-rollup.arbitrum.io/rpc`
Explorer	`https://arbiscan.io`	`https://nova.arbiscan.io`	`https://sepolia.arbiscan.io`
Bridge	`https://bridge.arbitrum.io`	`https://bridge.arbitrum.io`	`https://bridge.arbitrum.io`
Native Token	ETH	ETH	ETH
Block Time	~0.25s	~0.25s	~0.25s
Finality	~7 days (challenge period)	~7 days	~7 days

Deployment

Foundry Deployment

The --legacy flag is required — Arbitrum's sequencer does not natively support EIP-1559 type-2 transaction envelopes in forge broadcast.

# Deploy to Arbitrum One
forge create src/MyContract.sol:MyContract \
  --rpc-url $ARBITRUM_RPC_URL \
  --private-key $PRIVATE_KEY \
  --legacy

# Deploy to Arbitrum Sepolia (testnet)
forge create src/MyContract.sol:MyContract \
  --rpc-url https://sepolia-rollup.arbitrum.io/rpc \
  --private-key $PRIVATE_KEY \
  --legacy

# Using forge script
forge script script/Deploy.s.sol:DeployScript \
  --rpc-url $ARBITRUM_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --legacy

Hardhat Deployment

// hardhat.config.ts
import { HardhatUserConfig } from "hardhat/config";

const config: HardhatUserConfig = {
  solidity: "0.8.24",
  networks: {
    arbitrumOne: {
      url: process.env.ARBITRUM_RPC_URL ?? "https://arb1.arbitrum.io/rpc",
      accounts: [process.env.PRIVATE_KEY!],
      chainId: 42161,
    },
    arbitrumSepolia: {
      url: "https://sepolia-rollup.arbitrum.io/rpc",
      accounts: [process.env.PRIVATE_KEY!],
      chainId: 421614,
    },
  },
  etherscan: {
    apiKey: {
      arbitrumOne: process.env.ARBISCAN_API_KEY!,
      arbitrumSepolia: process.env.ARBISCAN_API_KEY!,
    },
  },
};

export default config;

Contract Verification

# Verify on Arbiscan (Foundry)
forge verify-contract \
  --chain-id 42161 \
  --etherscan-api-key $ARBISCAN_API_KEY \
  --compiler-version v0.8.24 \
  $CONTRACT_ADDRESS \
  src/MyContract.sol:MyContract

# Verify with constructor args
forge verify-contract \
  --chain-id 42161 \
  --etherscan-api-key $ARBISCAN_API_KEY \
  --constructor-args $(cast abi-encode "constructor(address,uint256)" 0xYourAddress 1000) \
  $CONTRACT_ADDRESS \
  src/MyContract.sol:MyContract

# Verify on Sourcify
forge verify-contract \
  --chain-id 42161 \
  --verifier sourcify \
  $CONTRACT_ADDRESS \
  src/MyContract.sol:MyContract

Cross-Chain Messaging

L1 to L2: Retryable Tickets

Retryable tickets are Arbitrum's mechanism for sending messages from Ethereum L1 to Arbitrum L2. The L1 Inbox contract accepts the message and ETH for L2 gas, then the sequencer auto-executes it on L2.

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

interface IInbox {
    /// @notice Create a retryable ticket to send an L1→L2 message
    /// @param to L2 destination address
    /// @param l2CallValue ETH value to send to L2 destination
    /// @param maxSubmissionCost Max cost for L2 submission (refund if overestimated)
    /// @param excessFeeRefundAddress L2 address to refund excess fees
    /// @param callValueRefundAddress L2 address to refund call value on failure
    /// @param gasLimit L2 gas limit for execution
    /// @param maxFeePerGas Max L2 gas price
    /// @param data L2 calldata
    function createRetryableTicket(
        address to,
        uint256 l2CallValue,
        uint256 maxSubmissionCost,
        address excessFeeRefundAddress,
        address callValueRefundAddress,
        uint256 gasLimit,
        uint256 maxFeePerGas,
        bytes calldata data
    ) external payable returns (uint256);
}

// TypeScript: send L1→L2 message via retryable ticket
import { createPublicClient, createWalletClient, http, parseEther } from "viem";
import { mainnet } from "viem/chains";

const INBOX = "0x4Dbd4fc535Ac27206064B68FfCf827b0A60BAB3f" as const;

const inboxAbi = [
  {
    name: "createRetryableTicket",
    type: "function",
    stateMutability: "payable",
    inputs: [
      { name: "to", type: "address" },
      { name: "l2CallValue", type: "uint256" },
      { name: "maxSubmissionCost", type: "uint256" },
      { name: "excessFeeRefundAddress", type: "address" },
      { name: "callValueRefundAddress", type: "address" },
      { name: "gasLimit", type: "uint256" },
      { name: "maxFeePerGas", type: "uint256" },
      { name: "data", type: "bytes" },
    ],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

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

const maxSubmissionCost = parseEther("0.001");
const gasLimit = 1_000_000n;
const maxFeePerGas = 100_000_000n; // 0.1 gwei

// Total ETH needed: l2CallValue + maxSubmissionCost + (gasLimit * maxFeePerGas)
const totalValue = 0n + maxSubmissionCost + gasLimit * maxFeePerGas;

const { request } = await l1PublicClient.simulateContract({
  address: INBOX,
  abi: inboxAbi,
  functionName: "createRetryableTicket",
  args: [
    "0xYourL2ContractAddress",     // to
    0n,                             // l2CallValue
    maxSubmissionCost,              // maxSubmissionCost
    account.address,                // excessFeeRefundAddress
    account.address,                // callValueRefundAddress
    gasLimit,                       // gasLimit
    maxFeePerGas,                   // maxFeePerGas
    "0x",                           // data (encoded L2 function call)
  ],
  value: totalValue,
  account: account.address,
});

const hash = await walletClient.writeContract(request);

L2 to L1: ArbSys.sendTxToL1

L2-to-L1 messages go through the 7-day challenge period before they can be executed on L1.

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

interface IArbSys {
    /// @notice Send a transaction from L2 to L1
    /// @param destination L1 destination address
    /// @param data L1 calldata
    /// @return unique message ID
    function sendTxToL1(
        address destination,
        bytes calldata data
    ) external payable returns (uint256);

    /// @notice Get the current L2 block number
    function arbBlockNumber() external view returns (uint256);
}

// ArbSys is at a fixed precompile address on all Arbitrum chains
IArbSys constant ARBSYS = IArbSys(0x0000000000000000000000000000000000000064);

contract L2ToL1Sender {
    event L2ToL1MessageSent(uint256 indexed messageId, address destination);

    function sendMessageToL1(
        address l1Target,
        bytes calldata l1Calldata
    ) external payable {
        uint256 messageId = ARBSYS.sendTxToL1{value: msg.value}(
            l1Target,
            l1Calldata
        );
        emit L2ToL1MessageSent(messageId, l1Target);
    }
}

Address Aliasing

When an L1 contract sends a retryable ticket, the msg.sender seen on L2 is the aliased address:

L2 alias = L1 address + 0x1111000000000000000000000000000000001111

// Reverse the alias to get the original L1 sender
function undoL1ToL2Alias(address l2Address) internal pure returns (address) {
    uint160 offset = uint160(0x1111000000000000000000000000000000001111);
    unchecked {
        return address(uint160(l2Address) - offset);
    }
}

// Verify an L2 call came from a specific L1 contract
modifier onlyFromL1Contract(address expectedL1Sender) {
    require(
        undoL1ToL2Alias(msg.sender) == expectedL1Sender,
        "NOT_FROM_L1_CONTRACT"
    );
    _;
}

ArbOS Precompiles

Arbitrum provides system-level functionality through precompile contracts at fixed addresses. These are available on all Arbitrum chains.

ArbSys (0x0000000000000000000000000000000000000064)

Core system functions for L2 operations.

interface IArbSys {
    function arbBlockNumber() external view returns (uint256);
    function arbBlockHash(uint256 blockNumber) external view returns (bytes32);
    function arbChainID() external view returns (uint256);
    function arbOSVersion() external view returns (uint256);
    function sendTxToL1(address dest, bytes calldata data) external payable returns (uint256);
    function withdrawEth(address dest) external payable returns (uint256);
}

const arbSysAbi = [
  {
    name: "arbBlockNumber",
    type: "function",
    stateMutability: "view",
    inputs: [],
    outputs: [{ name: "", type: "uint256" }],
  },
  {
    name: "withdrawEth",
    type: "function",
    stateMutability: "payable",
    inputs: [{ name: "destination", type: "address" }],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

const ARBSYS = "0x0000000000000000000000000000000000000064" as const;

const l2BlockNumber = await publicClient.readContract({
  address: ARBSYS,
  abi: arbSysAbi,
  functionName: "arbBlockNumber",
});

ArbRetryableTx (0x000000000000000000000000000000000000006E)

Manage retryable tickets on L2.

interface IArbRetryableTx {
    /// @notice Redeem a retryable ticket that failed auto-execution
    function redeem(bytes32 ticketId) external;
    /// @notice Get the TTL for retryable tickets (default: 7 days)
    function getLifetime() external view returns (uint256);
    /// @notice Get the timeout timestamp for a specific ticket
    function getTimeout(bytes32 ticketId) external view returns (uint256);
    /// @notice Extend the lifetime of a retryable ticket
    function keepalive(bytes32 ticketId) external returns (uint256);
}

ArbGasInfo (0x000000000000000000000000000000000000006C)

Gas pricing information, especially the L1 data cost component.

interface IArbGasInfo {
    /// @notice Get gas prices: [perL2Tx, perL1CalldataUnit, perStorageAlloc, perArbGasBase, perArbGasCongestion, perArbGasTotal]
    function getPricesInWei() external view returns (uint256, uint256, uint256, uint256, uint256, uint256);
    /// @notice Get estimated L1 base fee
    function getL1BaseFeeEstimate() external view returns (uint256);
    /// @notice Get L1 gas pricing parameters
    function getL1GasPriceEstimate() external view returns (uint256);
}

const arbGasInfoAbi = [
  {
    name: "getPricesInWei",
    type: "function",
    stateMutability: "view",
    inputs: [],
    outputs: [
      { name: "perL2Tx", type: "uint256" },
      { name: "perL1CalldataUnit", type: "uint256" },
      { name: "perStorageAlloc", type: "uint256" },
      { name: "perArbGasBase", type: "uint256" },
      { name: "perArbGasCongestion", type: "uint256" },
      { name: "perArbGasTotal", type: "uint256" },
    ],
  },
  {
    name: "getL1BaseFeeEstimate",
    type: "function",
    stateMutability: "view",
    inputs: [],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

const ARBGASINFO = "0x000000000000000000000000000000000000006C" as const;

const prices = await publicClient.readContract({
  address: ARBGASINFO,
  abi: arbGasInfoAbi,
  functionName: "getPricesInWei",
});

const l1BaseFee = await publicClient.readContract({
  address: ARBGASINFO,
  abi: arbGasInfoAbi,
  functionName: "getL1BaseFeeEstimate",
});

NodeInterface (0x00000000000000000000000000000000000000C8)

Virtual contract for gas estimation — not callable from other contracts, only via eth_call / eth_estimateGas.

interface INodeInterface {
    /// @notice Estimate gas for a retryable ticket submission
    function estimateRetryableTicket(
        address sender,
        uint256 deposit,
        address to,
        uint256 l2CallValue,
        address excessFeeRefundAddress,
        address callValueRefundAddress,
        bytes calldata data
    ) external;

    /// @notice Get gas cost breakdown: gasEstimate, gasEstimateForL1, baseFee, l1BaseFeeEstimate
    function gasEstimateComponents(
        address to,
        bool contractCreation,
        bytes calldata data
    ) external payable returns (uint64, uint64, uint256, uint256);
}

const nodeInterfaceAbi = [
  {
    name: "gasEstimateComponents",
    type: "function",
    stateMutability: "payable",
    inputs: [
      { name: "to", type: "address" },
      { name: "contractCreation", type: "bool" },
      { name: "data", type: "bytes" },
    ],
    outputs: [
      { name: "gasEstimate", type: "uint64" },
      { name: "gasEstimateForL1", type: "uint64" },
      { name: "baseFee", type: "uint256" },
      { name: "l1BaseFeeEstimate", type: "uint256" },
    ],
  },
] as const;

const NODE_INTERFACE = "0x00000000000000000000000000000000000000C8" as const;

// Estimate gas with L1/L2 breakdown
const result = await publicClient.simulateContract({
  address: NODE_INTERFACE,
  abi: nodeInterfaceAbi,
  functionName: "gasEstimateComponents",
  args: [
    "0xTargetContract",
    false,
    "0xEncodedCalldata",
  ],
});

const [totalGas, l1Gas, baseFee, l1BaseFee] = result.result;
// L2 gas = totalGas - l1Gas

Gas Model

Arbitrum's gas model has two components. Understanding this is critical for accurate cost estimation.

Two-Component Gas

Component	Source	Scales With
L2 execution gas	ArbOS computation	Opcodes executed (similar to Ethereum)
L1 data posting cost	Calldata posted to Ethereum	Transaction size in bytes

The L1 data cost is computed as:

L1 cost = L1 base fee * (calldata bytes * 16 + overhead)

This L1 cost is converted to L2 gas units and added to the total gas used. For data-heavy transactions (large calldata, many storage writes that get batched), the L1 component can be 80%+ of total cost.

Gas Estimation

import { encodeFunctionData, formatEther } from "viem";

async function estimateArbitrumGas(
  publicClient: PublicClient,
  to: `0x${string}`,
  data: `0x${string}`
) {
  const nodeInterfaceAbi = [
    {
      name: "gasEstimateComponents",
      type: "function",
      stateMutability: "payable",
      inputs: [
        { name: "to", type: "address" },
        { name: "contractCreation", type: "bool" },
        { name: "data", type: "bytes" },
      ],
      outputs: [
        { name: "gasEstimate", type: "uint64" },
        { name: "gasEstimateForL1", type: "uint64" },
        { name: "baseFee", type: "uint256" },
        { name: "l1BaseFeeEstimate", type: "uint256" },
      ],
    },
  ] as const;

  const { result } = await publicClient.simulateContract({
    address: "0x00000000000000000000000000000000000000C8",
    abi: nodeInterfaceAbi,
    functionName: "gasEstimateComponents",
    args: [to, false, data],
  });

  const [totalGas, l1Gas, baseFee, l1BaseFee] = result;
  const l2Gas = totalGas - l1Gas;

  return {
    totalGas,
    l1Gas,
    l2Gas,
    baseFee,
    l1BaseFee,
    estimatedCostWei: BigInt(totalGas) * baseFee,
    estimatedCostEth: formatEther(BigInt(totalGas) * baseFee),
  };
}

Token Bridge

Bridging ETH (L1 to L2)

const INBOX = "0x4Dbd4fc535Ac27206064B68FfCf827b0A60BAB3f" as const;

const inboxAbi = [
  {
    name: "depositEth",
    type: "function",
    stateMutability: "payable",
    inputs: [],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

// Deposit 0.1 ETH from L1 to L2 (arrives at same address on L2)
const { request } = await l1PublicClient.simulateContract({
  address: INBOX,
  abi: inboxAbi,
  functionName: "depositEth",
  value: parseEther("0.1"),
  account: account.address,
});

const hash = await l1WalletClient.writeContract(request);
const receipt = await l1PublicClient.waitForTransactionReceipt({ hash });
if (receipt.status !== "success") throw new Error("ETH deposit failed");
// ETH appears on L2 within ~10 minutes

Bridging ETH (L2 to L1)

// Withdraw ETH from L2 to L1 via ArbSys precompile
const ARBSYS = "0x0000000000000000000000000000000000000064" as const;

const arbSysAbi = [
  {
    name: "withdrawEth",
    type: "function",
    stateMutability: "payable",
    inputs: [{ name: "destination", type: "address" }],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

const { request } = await l2PublicClient.simulateContract({
  address: ARBSYS,
  abi: arbSysAbi,
  functionName: "withdrawEth",
  args: [account.address], // L1 destination
  value: parseEther("0.1"),
  account: account.address,
});

const hash = await l2WalletClient.writeContract(request);
// After 7-day challenge period, claim on L1 via Outbox contract

Bridging ERC20 Tokens (L1 to L2)

ERC20 tokens bridge through the Gateway Router, which routes to the appropriate gateway (standard, custom, or WETH).

const GATEWAY_ROUTER = "0x72Ce9c846789fdB6fC1f34aC4AD25Dd9ef7031ef" as const;

const gatewayRouterAbi = [
  {
    name: "outboundTransfer",
    type: "function",
    stateMutability: "payable",
    inputs: [
      { name: "_token", type: "address" },
      { name: "_to", type: "address" },
      { name: "_amount", type: "uint256" },
      { name: "_maxGas", type: "uint256" },
      { name: "_gasPriceBid", type: "uint256" },
      { name: "_data", type: "bytes" },
    ],
    outputs: [{ name: "", type: "bytes" }],
  },
  {
    name: "getGateway",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "_token", type: "address" }],
    outputs: [{ name: "", type: "address" }],
  },
] as const;

const USDC_L1 = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" as const;

// Step 1: Approve the gateway (not the router) to spend tokens
const gateway = await l1PublicClient.readContract({
  address: GATEWAY_ROUTER,
  abi: gatewayRouterAbi,
  functionName: "getGateway",
  args: [USDC_L1],
});

// Step 2: approve gateway, then call outboundTransfer on the router
// The _data param encodes maxSubmissionCost and extra data
import { encodeAbiParameters, parseAbiParameters } from "viem";

const maxSubmissionCost = parseEther("0.001");
const extraData = encodeAbiParameters(
  parseAbiParameters("uint256, bytes"),
  [maxSubmissionCost, "0x"]
);

const bridgeAmount = 1000_000000n; // 1000 USDC (6 decimals)
const gasLimit = 300_000n;
const gasPriceBid = 100_000_000n; // 0.1 gwei

const totalValue = maxSubmissionCost + gasLimit * gasPriceBid;

const { request } = await l1PublicClient.simulateContract({
  address: GATEWAY_ROUTER,
  abi: gatewayRouterAbi,
  functionName: "outboundTransfer",
  args: [
    USDC_L1,
    account.address,
    bridgeAmount,
    gasLimit,
    gasPriceBid,
    extraData,
  ],
  value: totalValue,
  account: account.address,
});

Gateway Types

Gateway	Address (L1)	Purpose
Standard ERC20	`0xa3A7B6F88361F48403514059F1F16C8E78d60EeC`	Default for most ERC20 tokens
Custom	Varies per token	Tokens needing custom L1/L2 logic
WETH	`0xd92023E9d9911199a6711321D1277285e6d4e2db`	Handles WETH unwrap/wrap across bridge

Orbit Chains

Orbit allows teams to launch custom L3 chains that settle to Arbitrum One or Nova. These are independent chains with configurable parameters.

Orbit Architecture

Ethereum L1 (settlement)
  └── Arbitrum One L2 (execution + DA)
       └── Your Orbit L3 (custom chain)

Orbit SDK Setup

import { createRollupPrepareConfig, createRollupPrepareTransactionRequest } from "@arbitrum/orbit-sdk";

// Prepare Orbit chain configuration
const config = createRollupPrepareConfig({
  chainId: BigInt(YOUR_CHAIN_ID),
  owner: "0xYourOwnerAddress",
  chainConfig: {
    // Custom gas token, data availability, etc.
    homesteadBlock: 0,
    daoForkBlock: null,
    daoForkSupport: true,
    eip150Block: 0,
    eip150Hash: "0x0000000000000000000000000000000000000000000000000000000000000000",
    eip155Block: 0,
    eip158Block: 0,
    byzantiumBlock: 0,
    constantinopleBlock: 0,
    petersburgBlock: 0,
    istanbulBlock: 0,
    muirGlacierBlock: 0,
    berlinBlock: 0,
    londonBlock: 0,
    clique: { period: 0, epoch: 0 },
    arbitrum: {
      EnableArbOS: true,
      AllowDebugPrecompiles: false,
      DataAvailabilityCommittee: false, // true for AnyTrust
      InitialArbOSVersion: 20,
      InitialChainOwner: "0xYourOwnerAddress",
      GenesisBlockNum: 0,
    },
  },
});

When to Use Orbit

Use Case	Recommendation
App-specific chain with custom gas token	Orbit L3
High-throughput gaming with cheap DA	Orbit L3 + AnyTrust
General DeFi app	Deploy to Arbitrum One directly
Cross-chain interop needed	Deploy to Arbitrum One (better liquidity)

Key Differences from Ethereum

Behavior	Ethereum	Arbitrum
`block.number`	Current L1 block	L1 block number (NOT L2)
`block.timestamp`	L1 timestamp	L1 timestamp
L2 block number	N/A	`ArbSys(0x64).arbBlockNumber()`
Gas model	Single gas price	L2 gas + L1 data posting cost
Transaction type	EIP-1559 (type 2)	Legacy (type 0) recommended
Mempool	Public, competitive	No mempool (FCFS sequencer)
Finality	~12 seconds (1 epoch)	~0.25s soft, ~7 days hard
`msg.sender` cross-chain	Same address	Aliased (+0x1111...1111 offset)
`SELFDESTRUCT`	Deprecated (EIP-6780)	Same as Ethereum post-Dencun
Contract size limit	24KB (EIP-170)	24KB (same)
`PUSH0` opcode	Supported (Shanghai)	Supported (Nitro supports it)

Contract Addresses

Last verified: February 2026

Core Contracts (Arbitrum One)

Contract	Address
Rollup	`0x5eF0D09d1E6204141B4d37530808eD19f60FBa35`
Inbox	`0x4Dbd4fc535Ac27206064B68FfCf827b0A60BAB3f`
Outbox	`0x0B9857ae2D4A3DBe74ffE1d7DF045bb7F96E4840`
Bridge	`0x8315177aB297bA92A06054cE80a67Ed4DBd7ed3a`
SequencerInbox	`0x1c479675ad559DC151F6Ec7ed3FbF8ceE79582B6`
Gateway Router (L1)	`0x72Ce9c846789fdB6fC1f34aC4AD25Dd9ef7031ef`
Standard Gateway (L1)	`0xa3A7B6F88361F48403514059F1F16C8E78d60EeC`
WETH Gateway (L1)	`0xd92023E9d9911199a6711321D1277285e6d4e2db`
Gateway Router (L2)	`0x5288c571Fd7aD117beA99bF60FE0846C4E84F933`
Standard Gateway (L2)	`0x09e9222E96E7B4AE2a407B98d48e330053351EEe`

ArbOS Precompiles

Precompile	Address
ArbSys	`0x0000000000000000000000000000000000000064`
ArbInfo	`0x0000000000000000000000000000000000000065`
ArbAddressTable	`0x0000000000000000000000000000000000000066`
ArbBLS (deprecated)	`0x0000000000000000000000000000000000000067`
ArbFunctionTable (deprecated)	`0x0000000000000000000000000000000000000068`
ArbosTest	`0x0000000000000000000000000000000000000069`
ArbOwner	`0x0000000000000000000000000000000000000070`
ArbGasInfo	`0x000000000000000000000000000000000000006C`
ArbAggregator	`0x000000000000000000000000000000000000006D`
ArbRetryableTx	`0x000000000000000000000000000000000000006E`
ArbStatistics	`0x000000000000000000000000000000000000006F`
NodeInterface	`0x00000000000000000000000000000000000000C8`

Token Addresses (Arbitrum One)

Token	Address
ARB	`0x912CE59144191C1204E64559FE8253a0e49E6548`
WETH	`0x82aF49447D8a07e3bd95BD0d56f35241523fBab1`
USDC (native)	`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`
USDC.e (bridged)	`0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8`
USDT	`0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9`
DAI	`0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1`
WBTC	`0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f`
GMX	`0xfc5A1A6EB076a2C7aD06eD22C90d7E710E35ad0a`

Error Handling

Error	Cause	Fix
`NOT_ENOUGH_FUNDS`	Insufficient ETH for L2 gas + L1 data cost	Account for both gas components in estimation
`RETRYABLE_TICKET_CREATION_FAILED`	Retryable ticket underfunded	Increase `maxSubmissionCost` or `gasLimit * maxFeePerGas`
`ONLY_ROLLUP_OR_OWNER`	Calling admin precompile without permission	These are restricted to chain owner
`NO_TICKET_WITH_ID`	Redeeming non-existent or expired retryable	Check ticket still exists with `getTimeout()`
`ALREADY_REDEEMED`	Retryable ticket already executed	No action needed — message was delivered
`L1_MSG_NOT_CONFIRMED`	Trying to execute L2→L1 message too early	Wait for the 7-day challenge period to elapse
Nonce too high/low	Sequencer nonce mismatch	Reset nonce or wait for pending transactions

Security

Cross-Chain Message Validation

// Always verify the sender of cross-chain messages
// L1→L2: check aliased sender
modifier onlyL1Contract(address expectedL1Sender) {
    uint160 offset = uint160(0x1111000000000000000000000000000000001111);
    unchecked {
        require(
            address(uint160(msg.sender) - offset) == expectedL1Sender,
            "ONLY_L1_CONTRACT"
        );
    }
    _;
}

// L2→L1: verify via Outbox on L1
modifier onlyL2Contract(address outbox) {
    // The Outbox contract provides l2ToL1Sender() during execution
    IOutbox(outbox).l2ToL1Sender();
    _;
}

Gas Estimation Safety

Always use NodeInterface.gasEstimateComponents() instead of plain eth_estimateGas — the latter may not account for L1 data costs correctly in all cases.
Add a 20-30% buffer to gas estimates for L1 data cost fluctuations.
For retryable tickets, overestimate maxSubmissionCost — excess is refunded.

Retryable Ticket Monitoring

Monitor all retryable tickets for auto-redeem failure.
Failed retryables expire after 7 days — set up alerts.
Use the ArbRetryableTx precompile to check status and manually redeem.

References

layerzero

View full →

Author

@0xinit

Stars

Repository

0xinit/cryptoskills

skills/layerzero/SKILL.md

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

Deploy OApp on each chain (with that chain's EndpointV2 address)
Set peers bidirectionally between every chain pair
Configure DVNs for each pathway
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

Check source chain transaction. If it reverted, the message was never sent. Fix the source-side issue (fee, peer, options).
Use LayerZero Scan. Go to layerzeroscan.com and enter the source tx hash. It shows message status: Sent, Verifying, Verified, Delivered, or Failed.
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.
Check executor delivery. If verified but not delivered, the Executor may have failed. Common cause: insufficient gas in options. Increase lzReceiveOption gas limit.
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",
]);

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`