IOTA L1 OFT SDK - LayerZero

The LayerZero IOTA L1 OFT SDK provides TypeScript utilities for interacting with OFT contracts on the IOTA L1 blockchain, enabling seamless crosschain token transfers.

Installation

Install both the core IOTA SDK and the OFT-specific SDK:

npm install @layerzerolabs/lz-iotal1-sdk-v2 @layerzerolabs/lz-iotal1-oft-sdk-v2

Or with yarn:

yarn add @layerzerolabs/lz-iotal1-sdk-v2 @layerzerolabs/lz-iotal1-oft-sdk-v2

Setup

Initialize the SDKs

The recommended pattern uses automatic address fetching from the protocol SDK:

import {IOTAClient} from '@iota/iota-sdk/client';
import {SDK} from '@layerzerolabs/lz-iotal1-sdk-v2';
import {OFT} from '@layerzerolabs/lz-iotal1-oft-sdk-v2';
import {Stage} from '@layerzerolabs/lz-definitions';

// Setup IOTA client
const client = new IOTAClient({url: 'https://fullnode.mainnet.iota.io:443'});

// Initialize protocol SDK (automatically fetches LayerZero protocol addresses)
const sdk = new SDK({client, stage: Stage.MAINNET});

// Initialize OFT SDK with your OFT package ID
const oft = new OFT(
  sdk, // Protocol SDK instance
  oftPackageId, // Your OFT package ID (NOT OFT CallCap ID!)
  oftObjectId, // Optional: OFT object ID (set after init)
  tokenType, // Optional: "0x123::mycoin::MYCOIN"
  oappObjectId, // Optional: OApp object ID
  adminCapId, // Optional: Admin cap ID (can query later)
);

Critical Notes:

First parameter: Use your OFT package ID (where your code is deployed)
SDK automatic addresses: No need to hardcode LayerZero protocol addresses
Optional parameters: Can be undefined initially and set later
After initialization: Update oft.oftObjectId = newObjectId

Getting OApp Instance (for peer/DVN configuration):

// Use SDK to get OApp instance (recommended)
const oapp = sdk.getOApp(oftPackageId); // Use package ID

// Configure peers and DVNs through OApp
await oapp.setPeerMoveCall(tx, dstEid, peerBytes);
await oapp.setConfigMoveCall(tx, lib, eid, configType, config);

Do NOT manually instantiate new OApp(...) - this will fail to find your OApp in the registry. Always use sdk.getOApp(packageId).

SDK Architecture

The IOTA OFT SDK consists of two complementary SDKs:

Base SDK (`@layerzerolabs/lz-iotal1-sdk-v2`)

Provides core LayerZero protocol functionality:

OApp operations: Peer configuration, messaging, registration
Endpoint interaction: Channel initialization, library configuration
DVN/Executor configuration: Security stack setup
Protocol address exports: All deployed contract addresses

When to use: For OApp configuration, peer setup, DVN configuration, and general protocol interactions.

OFT SDK (`@layerzerolabs/lz-iotal1-oft-sdk-v2`)

Extends the base SDK with OFT-specific functionality:

OFT initialization: initOftMoveCall(), initOftAdapterMoveCall()
Registration: registerOAppMoveCall() (auto-generates lz_receive_info)
Rate limiting: Per-pathway token flow limits
Fee management: Crosschain fee configuration
Pause control: Emergency pause functionality

When to use: For OFT deployment, token-specific operations, and OFT lifecycle management.

Relationship

// Base SDK provides OApp functionality
const sdk = new SDK({ client, stage: Stage.MAINNET });
const oapp = sdk.getOApp(packageId); // OApp configuration

// OFT SDK extends with token-specific features
const oft = new OFT(sdk, oftPackageId, ...); // OFT operations

SDK Address Exports

The SDK provides address exports for all protocol contracts, eliminating hardcoded values:

import {
  // Object addresses (shared instances everyone uses)
  OBJECT_ENDPOINT_V2_ADDRESS,
  OBJECT_ULN_302_ADDRESS,

  // Package addresses (where code lives)
  PACKAGE_OAPP_ADDRESS,
  PACKAGE_ULN_302_ADDRESS,
  PACKAGE_DVN_LAYERZERO_ADDRESS,

  // Helpers
  OAppUlnConfigBcs,
  Stage,
} from '@layerzerolabs/lz-iotal1-sdk-v2';

// Get addresses for your network
const endpointObj = OBJECT_ENDPOINT_V2_ADDRESS[Stage.MAINNET];
const uln302Obj = OBJECT_ULN_302_ADDRESS[Stage.MAINNET];
const uln302Pkg = PACKAGE_ULN_302_ADDRESS[Stage.MAINNET];
const dvnLayerZero = PACKAGE_DVN_LAYERZERO_ADDRESS[Stage.MAINNET];

Benefits:

Network switching: Toggle between mainnet/testnet via Stage enum
SDK updates: Address changes handled automatically
No magic numbers: Self-documenting configuration
Type safety: TypeScript ensures correct usage

Available exports:

Export	Description	Usage
`OBJECT_ENDPOINT_V2_ADDRESS`	Endpoint shared object	Pass to Endpoint functions
`OBJECT_ULN_302_ADDRESS`	ULN302 shared object	Pass to ULN302 functions
`PACKAGE_OAPP_ADDRESS`	OApp package ID	Reference for OApp code
`PACKAGE_ULN_302_ADDRESS`	ULN302 package ID	Use in move call targets
`PACKAGE_DVN_LAYERZERO_ADDRESS`	LayerZero DVN package	DVN configuration
`OAppUlnConfigBcs`	Config serializer	Encode DVN configuration

Complete Working Example

Reference Implementation

All examples on this page are based on proven mainnet deployments. The complete reference implementation demonstrating these patterns is available in the LayerZero test repository at test-repo/iota-oft-complete/deploy_with_oft_sdk.mjs.

Based on proven mainnet deployment:

import {IOTAClient} from '@iota/iota-sdk/client';
import {Transaction} from '@iota/iota-sdk/transactions';
import {Ed25519Keypair} from '@iota/iota-sdk/keypairs/ed25519';
import {SDK} from '@layerzerolabs/lz-iotal1-sdk-v2';
import {OFT} from '@layerzerolabs/lz-iotal1-oft-sdk-v2';
import {Stage} from '@layerzerolabs/lz-definitions';

const client = new IOTAClient({url: 'https://fullnode.mainnet.iota.io:443'});
const keypair = Ed25519Keypair.fromSecretKey(secretKeyBytes);

// Initialize protocol SDK
const sdk = new SDK({client, stage: Stage.MAINNET});

// Initialize OFT SDK
const oft = new OFT(sdk, oftPackageId, undefined, tokenType, oappObjectId);

// Step 1: Initialize OFT
const initTx = new Transaction();
const [adminCap, migrationCap] = oft.initOftMoveCall(
  initTx,
  tokenType,
  ticketObjectId,
  oappObjectId,
  treasuryCapId,
  coinMetadataId,
  6, // shared_decimals
);
initTx.transferObjects([adminCap, migrationCap], sender);

const initResult = await client.signAndExecuteTransaction({
  transaction: initTx,
  signer: keypair,
  options: {showObjectChanges: true},
});

// ✅ CRITICAL: Wait for finality before referencing created objects
await client.waitForTransaction({digest: initResult.digest});

const oftObjectId = initResult.objectChanges.find(
  (c) => c.type === 'created' && c.objectType.includes('oft::OFT<'),
).objectId;

// Update OFT SDK with object ID
oft.oftObjectId = oftObjectId;

// Step 2: Register (SDK auto-generates lz_receive_info)
const regTx = new Transaction();
await oft.registerOAppMoveCall(
  regTx,
  tokenType,
  oftObjectId,
  oappObjectId,
  '0xfe5be5a2d5b11e635e3e4557bb125fb24a3dd09111eded06fd6058b2aee1d054', // OFTComposerManager (IOTA mainnet)
);

const regResult = await client.signAndExecuteTransaction({transaction: regTx, signer: keypair});

// Wait for finality before next operation
await client.waitForTransaction({digest: regResult.digest});

// Step 3: Configure via OApp SDK
const oapp = sdk.getOApp(oftPackageId);

const peerTx = new Transaction();
await oapp.setPeerMoveCall(peerTx, dstEid, peerBytes);
await client.signAndExecuteTransaction({transaction: peerTx, signer: keypair});

console.log('Deployment complete!');

Key SDK Methods Used:

oft.initOftMoveCall() - Initialize OFT with treasury
oft.registerOAppMoveCall() - Register and auto-generate lz_receive_info
sdk.getOApp() - Get OApp instance for configuration
oapp.setPeerMoveCall() - Configure peer addresses
oapp.setConfigMoveCall() - Configure DVNs/executors

Available SDK Methods

Base SDK (OApp Operations)

The base SDK provides methods for OApp configuration through sdk.getOApp(packageId):

const oapp = sdk.getOApp(packageId);

// Peer Configuration
await oapp.setPeerMoveCall(tx, eid, peerBytes); // Set peer for destination
await oapp.hasPeer(eid); // Check if peer configured
await oapp.getPeer(eid); // Get peer address

// DVN/Executor Configuration
await oapp.setConfigMoveCall(tx, lib, eid, configType, config); // Set DVN/executor config
await oapp.getConfig(lib, eid, configType); // Get current config

// OApp Registration
await oapp.registerOAppMoveCall(tx, oappObjectId, oappInfo); // Register with Endpoint
await oapp.setOAppInfoMoveCall(tx, oappInfo); // Update OApp info

// Enforced Options
await oapp.setEnforcedOptionsMoveCall(tx, eid, msgType, options); // Set minimum execution params
await oapp.getEnforcedOptions(eid, msgType); // Get enforced options
await oapp.combineOptions(eid, msgType, extraOptions); // Combine with user options

// Admin Operations
await oapp.setDelegateMoveCall(tx, newDelegate); // Transfer admin rights
await oapp.setSendLibraryMoveCall(tx, dstEid, library); // Set custom send library
await oapp.setReceiveLibraryMoveCall(tx, srcEid, library, grace); // Set custom receive library

// Channel Management
await oapp.initChannelMoveCall(tx, remoteEid, remoteOApp); // Initialize messaging channel
await oapp.skipMoveCall(tx, srcEid, sender, nonce); // Skip stuck message
await oapp.clearMoveCall(tx, srcEid, sender, nonce, guid, msg); // Clear verified message

OFT SDK Methods

The OFT SDK provides token-specific operations:

const oft = new OFT(sdk, oftPackageId, oftObjectId, tokenType, oappObjectId);

// Initialization
initOftMoveCall(tx, coinType, ticket, oapp, treasury, metadata, sharedDecimals);
initOftAdapterMoveCall(tx, coinType, ticket, oapp, metadata, sharedDecimals);

// Registration (auto-generates lz_receive_info!)
await registerOAppMoveCall(tx, coinType, oftObj, oappObj, composerMgr);

// Rate Limiting
await setRateLimitMoveCall(tx, eid, inbound, limit, windowSeconds); // Set rate limit
await unsetRateLimitMoveCall(tx, eid, inbound); // Remove rate limit
await rateLimitConfig(eid, inbound); // Get config
await rateLimitCapacity(eid, inbound); // Get remaining capacity
await rateLimitInFlight(eid, inbound); // Get current usage

// Fee Management
await setFeeBpsMoveCall(tx, eid, feeBps); // Set fee for pathway
await setDefaultFeeBpsMoveCall(tx, feeBps); // Set default fee
await setFeeDepositAddressMoveCall(tx, address); // Set fee recipient
await unsetFeeBpsMoveCall(tx, eid); // Remove pathway fee
await effectiveFeeBps(eid); // Get effective fee
await defaultFeeBps(); // Get default fee
await feeDepositAddress(); // Get fee recipient
await hasOftFee(eid); // Check if fee configured

// Pause Control
await setPauseMoveCall(tx, paused); // Pause/unpause OFT
await isPaused(); // Check pause status

// Queries
await sharedDecimals(); // Get shared decimals
await decimalConversionRate(); // Get conversion rate
await isAdapter(); // Check if adapter mode
await adminCap(); // Get AdminCap address
await oappObject(); // Get OApp object ID
await oftVersion(); // Get OFT version
await coinMetadata(); // Get metadata ID

Core Methods

quote()

Get a fee quote for sending tokens crosschain:

const {nativeFee, lzTokenFee} = await oft.quote(
  client,
  {
    payer: keypair.toIOTAAddress(),
    tokenMint: '0x...', // Coin type
    tokenEscrow: '0x...', // OFT escrow object
  },
  {
    dstEid: 30101, // Destination endpoint ID (e.g., Ethereum)
    to: Buffer.from('0x' + '1'.repeat(64), 'hex'), // 32-byte recipient address
    amountLD: BigInt(1000000), // Amount in local decimals
    minAmountLD: BigInt(950000), // Minimum amount (slippage)
    options: Buffer.from([]), // Execution options
    composeMsg: undefined, // Optional compose message
    payInLzToken: false, // Pay fee in native or LZ token
  },
);

console.log(`Native fee: ${nativeFee} wei`);
console.log(`LZ token fee: ${lzTokenFee} wei`);

send()

Send tokens crosschain:

const receipt = await oft.send(
  client,
  {
    payer: keypair, // Signer keypair
    tokenMint: '0x...', // Coin type
    tokenEscrow: '0x...', // OFT escrow object
    tokenSource: '0x...', // Source token account
  },
  {
    dstEid: 30101,
    to: Buffer.from(recipientBytes32),
    amountLD: BigInt(1000000),
    minAmountLD: BigInt(950000),
    options: Buffer.from([]),
    composeMsg: undefined,
    nativeFee: nativeFee,
    lzTokenFee: BigInt(0),
  },
);

console.log('Transaction:', receipt.digest);

getOFTConfig()

Read OFT configuration:

const config = await oft.getOFTConfig(client);

console.log('Token type:', config.tokenType);
console.log('Shared decimals:', config.sharedDecimals);
console.log('Endpoint:', config.endpoint);

getPeer()

Get peer OFT address for a specific chain:

const peer = await oft.getPeer(client, 30101); // Ethereum

console.log('Peer address:', Buffer.from(peer).toString('hex'));

Building Execution Options

Use the Options helper from the core SDK:

import {Options} from '@layerzerolabs/lz-v2-utilities';

// For EVM destination
const options = Options.newOptions()
  .addExecutorLzReceiveOption(60000, 0) // gas limit, msg.value
  .toBytes();

// For IOTA/Solana destination with ATA/object creation
const optionsWithValue = Options.newOptions()
  .addExecutorLzReceiveOption(200000, 2039280) // gas + rent
  .toBytes();

Gas Limits by Destination

Destination	Recommended Gas Limit	Notes
EVM chains	60,000 - 200,000	Higher for complex logic
Solana	200,000	May need msg.value for ATA
IOTA	200,000+	May need msg.value for object creation
Aptos	100,000	Adjust based on complexity

msg.value Considerations

When sending to IOTA, you may need to include msg.value for:

Creating a new coin object for the recipient
Storage rent for the new object

Calculate rent based on object size (typically ~0.002 IOTA).

Complete Example

Sending Tokens from IOTA to Ethereum

import {IOTAClient, getFullnodeUrl} from '@iota/iota-sdk/client';
import {Ed25519Keypair} from '@iota/iota-sdk/keypairs/ed25519';
import {OFT} from '@layerzerolabs/lz-iotal1-oft-sdk-v2';
import {Options} from '@layerzerolabs/lz-v2-utilities';

async function sendTokens() {
  // Setup
  const client = new IOTAClient({url: getFullnodeUrl('mainnet')});
  const keypair = Ed25519Keypair.deriveKeypair(process.env.MNEMONIC!);

  const oft = new OFT({
    client,
    oftAddress: process.env.OFT_PACKAGE!,
    oftStoreId: process.env.OFT_STORE!,
  });

  // Prepare params
  const dstEid = 30101; // Ethereum
  const recipient = '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'; // Remove 0x, pad to 32 bytes
  const recipientBytes32 = Buffer.from(recipient.padStart(64, '0'), 'hex');
  const amount = BigInt(1_000000); // 1 token (6 decimals)
  const minAmount = BigInt(950000); // 5% slippage

  // Build options
  const options = Options.newOptions().addExecutorLzReceiveOption(60000, 0).toBytes();

  // Quote fee
  console.log('Getting quote...');
  const {nativeFee} = await oft.quote(
    client,
    {
      payer: keypair.toIOTAAddress(),
      tokenMint: process.env.TOKEN_TYPE!,
      tokenEscrow: process.env.OFT_ESCROW!,
    },
    {
      dstEid,
      to: recipientBytes32,
      amountLD: amount,
      minAmountLD: minAmount,
      options: Buffer.from(options),
      composeMsg: undefined,
      payInLzToken: false,
    },
  );

  console.log(`Fee: ${nativeFee / BigInt(1e9)} IOTA`);

  // Send tokens
  console.log('Sending tokens...');
  const receipt = await oft.send(
    client,
    {
      payer: keypair,
      tokenMint: process.env.TOKEN_TYPE!,
      tokenEscrow: process.env.OFT_ESCROW!,
      tokenSource: process.env.TOKEN_ACCOUNT!,
    },
    {
      dstEid,
      to: recipientBytes32,
      amountLD: amount,
      minAmountLD: minAmount,
      options: Buffer.from(options),
      composeMsg: undefined,
      nativeFee,
      lzTokenFee: BigInt(0),
    },
  );

  console.log('- Sent!');
  console.log('Transaction:', receipt.digest);
  console.log('Track at: https://layerzeroscan.com');
}

sendTokens().catch(console.error);

Reading Token Balances

Check OFT token balances using the IOTA client:

import {IOTAClient} from '@iota/iota-sdk/client';

const client = new IOTAClient({url: getFullnodeUrl('mainnet')});

// Get all coins of a specific type for an address
const coins = await client.getCoins({
  owner: '0x...',
  coinType: '0x...::token::TOKEN',
});

const totalBalance = coins.data.reduce((sum, coin) => sum + BigInt(coin.balance), BigInt(0));

console.log('Balance:', totalBalance.toString());

Integration with Core SDK

The OFT SDK builds on the core IOTA SDK:

import {createEndpointClient, createOAppClient} from '@layerzerolabs/lz-iotal1-sdk-v2';

// For lower-level Endpoint interactions
const endpoint = createEndpointClient({
  address: '0x...',
});

// For OApp functionality
const oapp = createOAppClient({
  address: '0x...',
});

Error Handling

Common errors and how to handle them:

try {
  const receipt = await oft.send(/* ... */);
} catch (error) {
  if (error.message.includes('Insufficient funds')) {
    console.error('Not enough tokens or IOTA for gas');
  } else if (error.message.includes('Invalid peer')) {
    console.error('Peer not configured for destination chain');
  } else if (error.message.includes('Channel not initialized')) {
    console.error('Must initialize channel first');
  } else {
    console.error('Unknown error:', error);
  }
}

Admin Functions

The SDK provides admin functions for OFT management (requires AdminCap):

Pause/Unpause

// Pause OFT operations (emergency)
await oft.setPauseMoveCall(tx, true);

// Unpause
await oft.setPauseMoveCall(tx, false);

Fee Configuration

// Set default fee rate (in basis points, 10000 = 100%)
await oft.setDefaultFeeBpsMoveCall(tx, 30); // 0.3% fee

// Set fee for specific destination
await oft.setFeeBpsMoveCall(tx, 30101, 50); // 0.5% for Ethereum

// Set fee deposit address
await oft.setFeeDepositAddressMoveCall(tx, feeRecipientAddress);

Rate Limiting

// Set outbound rate limit
await oft.setOutboundRateLimitMoveCall(tx, {
  dstEid: 30101,
  limit: BigInt(1000000), // Max tokens per window
  window: 86400, // 24 hours in seconds
});

// Set inbound rate limit
await oft.setInboundRateLimitMoveCall(tx, {
  srcEid: 30101,
  limit: BigInt(1000000),
  window: 86400,
});

Peer Configuration

// Set peer OFT on destination chain
await oft.setPeerMoveCall(tx, 30101, peerBytes32);

Best Practices

Always Quote First: Get fee estimates before sending
Set Slippage: Use minAmountLD to protect against dust/precision loss
Check Balances: Verify sufficient tokens and IOTA for gas
Use TypeScript: Leverage type safety for parameter validation
Test on Testnet: Always test on testnet before mainnet deployments
Monitor Rate Limits: Configure appropriate limits for production
Secure Admin Cap: Use multisig or hardware wallet for admin operations

Next Steps

OFT Overview - OFT architecture and deployment guide
Configuration Guide - DVN, executor, and gas setup
OApp Overview - Base messaging standard
Technical Overview - IOTA fundamentals and architecture
Protocol Overview - Complete message workflows
Troubleshooting - Common SDK issues

​Installation

​Setup

​Initialize the SDKs

​SDK Architecture

​Base SDK (@layerzerolabs/lz-iotal1-sdk-v2)

​OFT SDK (@layerzerolabs/lz-iotal1-oft-sdk-v2)

​Relationship

​SDK Address Exports

​Complete Working Example

​Reference Implementation

​Available SDK Methods

​Base SDK (OApp Operations)

​OFT SDK Methods

​Core Methods

​quote()

​send()

​getOFTConfig()

​getPeer()

​Building Execution Options

​Gas Limits by Destination

​msg.value Considerations

​Complete Example

​Sending Tokens from IOTA to Ethereum

​Reading Token Balances

​Integration with Core SDK

​Error Handling

​Admin Functions

​Pause/Unpause

​Fee Configuration

​Rate Limiting

​Peer Configuration

​Best Practices

​Next Steps