@0xaibridge/sdk

0xBridge Cross-Chain SDK — one-line cross-chain ERC20 transfers with fee estimation and route discovery.

npm install @0xaibridge/sdk

Quick Start

Dual-Mode API

import { bridge, estimateFee, getRoute } from '@0xaibridge/sdk';

// Mode 1: Quick cross-chain transfer (requires PRIVATE_KEY env)
const { txHash, estimatedTime } = await bridge({
  fromChain: '11155111',   // Sepolia
  toChain: '19505',         // OxaChain L1
  token: '0x87dec5277dA56Bc843C76A1fFc26Fe5964Bee9e4',
  amount: '1000000',        // in wei
  recipient: '0x...',
});

// Mode 2: SDK instance (full control)
const sdk = bridge({
  bridgeAddress: '0x139632f19355bF58f95818553CbB9E0F77f62202',
  rpcUrl: 'https://ethereum-sepolia.publicnode.com',
  signerKey: process.env.PRIVATE_KEY,
});

const { tx, sequence } = await sdk.transfer({
  token: '0x...',
  amount: '1000000',
  toChain: 19505,
  to: '0x...',
});

API Reference

Functions

| Function | Description | |----------|-------------| | bridge(opts) | Dual-mode: with bridgeAddress → returns BridgeSDK instance; with fromChain → executes transfer directly | | estimateFee({fromChain, toChain, token, amount}) | Estimate gas fee for a bridge transfer. Returns { fee, feeToken, estimatedTime } | | getRoute({fromChain, toChain, token}) | Query available bridge routes. Returns { available, routes } | | hashTransfer(transfer) | Hash a Transfer struct for signing | | encodeTransfer(transfer) | ABI-encode a Transfer struct |

BridgeSDK Class

class BridgeSDK {
  constructor(opts: BridgeOptions)
  
  // Read
  chainId(): Promise<number>
  isWrapped(token: string): Promise<boolean>
  wrappedAsset(tokenChain: number, tokenAddress: string): Promise<string>
  isTransferCompleted(tokenChain: number, tokenAddress: string, sequence: bigint): Promise<boolean>
  
  // Write
  transfer(params: TransferParams): Promise<{ tx, sequence }>
  
  // Events
  onTransfer(chainId: number, callback): ethers.Contract
  
  // Static
  static signAndComplete(params): Promise<{ tx, blockNumber }>
  static parseTransferFromLog(log): BridgeTransfer
}

BridgeOptions

interface BridgeOptions {
  bridgeAddress: string;         // Bridge contract address
  rpcUrl?: string;               // RPC endpoint (or use provider)
  provider?: ethers.Provider;    // ethers Provider instance
  signerKey?: string;            // Private key for signing
  signer?: ethers.Signer;        // ethers Signer instance
  gasLimitTransfer?: number;     // Default: 400000
  gasLimitComplete?: number;     // Default: 300000
}

TransferParams

interface TransferParams {
  token: string;       // ERC20 token address
  amount: string | bigint;  // Amount in wei
  toChain: number;     // Destination chain ID
  to: string;          // Recipient address
}

Supported Chains

| Chain | ID | Bridge Address | |-------|----|----------------| | Sepolia | 11155111 | 0x139632f19355bF58f95818553CbB9E0F77f62202（bridgeChainId=10002） | | OxaChain L1 | 19505 | 0x86a81a183085Ce7F44813982b06ad5b3C57B8d83 | | BSC Testnet | 97 | 0x0000000000000000000000000000000000000000 |

Examples

Estimate Fees

const { fee, feeToken, estimatedTime } = await estimateFee({
  fromChain: '11155111',
  toChain: '19505',
  token: '0x87dec5277dA56Bc843C76A1fFc26Fe5964Bee9e4',
  amount: '1000000',
});
console.log(`Fee: ${fee} ${feeToken}, ETA: ${estimatedTime}s`);

Check Available Routes

const { available, routes } = await getRoute({
  fromChain: '11155111',
  toChain: '19505',
  token: '0x...',
});
// routes[0] → { bridge: '0xBridge', fee: '~0.001 ETH', time: 60 }

Listen for Incoming Transfers

const sdk = bridge({
  bridgeAddress: '0x86a81a183085Ce7F44813982b06ad5b3C57B8d83',
  rpcUrl: 'http://43.156.99.215:18545',
});

// Listen for transfers targeting chain 19505
sdk.onTransfer(19505, ({ transfer, log }) => {
  console.log(`Incoming transfer: seq=${transfer.sequence}, amount=${transfer.amount}`);
});

Release Notes

1.0.4 (2026-08-10)

• Fixed: LogTransfer event ABI declared indexed params while the on-chain event has no indexed params (topics contain only topic0; all fields are encoded in data). This caused parseLog to fail and transfer() to return sequence = 0. The ABI now matches the deployed contracts — transfer() returns the correct sequence, verified against on-chain events (SDK result == on-chain event sequence).
• No breaking changes to the public API.

1.0.3 (2026-08-10)

• Added: New Bridge addresses for the re-deployed contracts — Sepolia 0x139632f19355bF58f95818553CbB9E0F77f62202 (bridgeChainId 10002), OxaChain L1 0x86a81a183085Ce7F44813982b06ad5b3C57B8d83 (chainId 19505).
• Added: isTransferCompleted(tokenChain, tokenAddress, sequence) — three-argument completion query keyed by (tokenChain, tokenAddress, sequence), matching the on-chain fix for cross-chain sequence collisions.
• Fixed: signAndComplete now signs the raw digest (signingKey.sign) instead of signMessage(), which added the EIP-191 prefix and produced signatures the contract's verifyMessage (raw ecrecover) rejected.

1.0.2 (2026-08-10)

• Fixed: Corrected the default OxaChain L1 Bridge address in DEFAULT_CHAINS (0xd43Eba… → correct deployment).
• Fixed: Replaced the dead drpc Sepolia RPC with https://ethereum-sepolia.publicnode.com.

1.0.1 (2026-08-10)

• Fixed: gasLimit applied on the transferTokens transaction.

1.0.0 (2026-07-17)

• Initial release: cross-chain ERC20 transfers (Native Lock/Unlock), fee estimation, route discovery, event listening.