@omni-bridge/core - Omni Bridge SDK

Import

import {
  // Bridge factory
  createBridge,
  type Bridge,
  type BridgeConfig,

  // API client
  BridgeAPI,
  type BridgeAPIConfig,
  type ApiFeeResponse,
  type Transfer,
  type TransferStatus,
  type Chain,
  type PostAction,
  type UtxoChainParam,
  type UtxoDepositAddressResponse,

  // Types
  ChainKind,
  type Network,
  type OmniAddress,
  type ChainPrefix,
  type TransferParams,
  type ValidatedTransfer,
  type TokenDecimals,
  type Fee,
  type Nonce,
  type U128,
  type AccountId,
  type UtxoChain,
  type UTXO,

  // Unsigned transaction types
  type EvmUnsignedTransaction,
  type NearUnsignedTransaction,
  type NearAction,
  type SolanaUnsignedTransaction,
  type SolanaInstruction,
  type BtcUnsignedTransaction,

  // Address utilities
  getChain,
  getAddress,
  omniAddress,
  getChainPrefix,
  isEvmChain,
  type EvmChainKind,

  // Decimal utilities
  normalizeAmount,
  validateTransferAmount,
  verifyTransferAmount,
  getMinimumTransferableAmount,

  // Configuration
  getAddresses,
  EVM_CHAIN_IDS,
  API_BASE_URLS,
  type ChainAddresses,
  type EvmAddresses,
  type NearAddresses,
  type SolanaAddresses,
  type BtcAddresses,
  type ZcashAddresses,

  // Wormhole utilities
  getWormholeVaa,
  getVaa,
  type WormholeNetwork,

  // Errors
  OmniBridgeError,
  ValidationError,
  RpcError,
  ProofError,
  type ValidationErrorCode,
} from "@omni-bridge/core"

createBridge

Factory function to create a Bridge instance for validating transfers and accessing the API.

Signature

function createBridge(config: BridgeConfig): Bridge

Parameters

config

BridgeConfig

required

Configuration object for the bridge.

Show BridgeConfig properties

network

'mainnet' | 'testnet'

required

The network to connect to.

rpcUrls

Partial<Record<ChainKind, string>>

Optional custom RPC URLs for each chain. Overrides default RPC endpoints.

Returns

Bridge

A Bridge instance with properties and methods for transfer validation.

Show Bridge interface

network

'mainnet' | 'testnet'

The network this bridge is connected to.

addresses

ChainAddresses

Contract addresses for all supported chains.

api

BridgeAPI

Direct access to the API client instance.

validateTransfer

(params: TransferParams) => Promise<ValidatedTransfer>

Validates transfer parameters and prepares for execution.

getTokenDecimals

(token: OmniAddress) => Promise<TokenDecimals | null>

Gets decimal information for a token.

getBridgedToken

(token: OmniAddress, destChain: ChainKind) => Promise<OmniAddress | null>

Gets the bridged token address on a destination chain.

getUtxoDepositAddress

(chain: UtxoChain, recipient: string, options?: UtxoDepositOptions) => Promise<UtxoDepositResult>

Gets a deposit address for Bitcoin or Zcash.

Example

import { createBridge, ChainKind } from "@omni-bridge/core"

// Basic usage
const bridge = createBridge({ network: "mainnet" })

// With custom RPC URLs
const bridgeWithRpc = createBridge({
  network: "mainnet",
  rpcUrls: {
    [ChainKind.Eth]: "https://my-custom-rpc.com",
    [ChainKind.Near]: "https://rpc.mainnet.near.org",
  },
})

// Accessing addresses
console.log(bridge.addresses.eth.bridge)    // EVM bridge contract
console.log(bridge.addresses.near.contract) // NEAR contract
console.log(bridge.addresses.sol.locker)    // Solana locker program

Bridge.validateTransfer

Validates transfer parameters and prepares a ValidatedTransfer object for building transactions.

Signature

bridge.validateTransfer(params: TransferParams): Promise<ValidatedTransfer>

Parameters

params

TransferParams

required

The transfer parameters to validate.

Show TransferParams properties

token

OmniAddress

required

The token to transfer, in OmniAddress format (e.g., eth:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48).

amount

bigint

required

Amount to transfer in the token’s smallest unit (e.g., wei for ETH, lamports for SOL).

fee

bigint

required

Relayer fee in the transfer token. Set to 0n for manual finalization.

nativeFee

bigint

required

Relayer fee in the source chain’s native token. Set to 0n for manual finalization.

sender

OmniAddress

required

Sender address in OmniAddress format.

recipient

OmniAddress

required

Recipient address in OmniAddress format.

message

string

Optional message or memo to include with the transfer.

Returns

ValidatedTransfer

A validated transfer object ready for building.

Show ValidatedTransfer properties

params

TransferParams

The original transfer parameters.

sourceChain

ChainKind

The source chain extracted from the sender address.

destChain

ChainKind

The destination chain extracted from the recipient address.

normalizedAmount

bigint

Amount normalized for decimal differences between chains.

normalizedFee

bigint

Fee normalized for decimal differences between chains.

contractAddress

string

The bridge contract address on the source chain.

bridgedToken

OmniAddress | undefined

The token address on the destination chain (if different from source).

Validation Checks

The method performs these validations:

Amount validation: Amount must be positive, fee cannot be negative
Address format: Sender and recipient must be valid OmniAddresses
EVM address validation: EVM addresses must be valid hex format
Token registration: Token must be registered on the bridge
Decimal normalization: Amount must survive conversion between chains
Minimum amount: Amount minus fee must be greater than zero after normalization

Errors

Throws ValidationError with one of these codes:

Code	Description
`INVALID_AMOUNT`	Amount is invalid (zero, negative, or less than fee)
`INVALID_ADDRESS`	Address format is invalid
`INVALID_CHAIN`	Chain prefix is not recognized
`TOKEN_NOT_REGISTERED`	Token is not registered on the bridge
`AMOUNT_TOO_SMALL`	Amount too small after decimal normalization

Example

import { createBridge, ValidationError } from "@omni-bridge/core"

const bridge = createBridge({ network: "mainnet" })

try {
  const validated = await bridge.validateTransfer({
    token: "eth:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    amount: 1000000n, // 1 USDC
    fee: 0n,
    nativeFee: 0n,
    sender: "eth:0x1234567890123456789012345678901234567890",
    recipient: "near:alice.near",
  })

  console.log(validated.sourceChain)      // ChainKind.Eth
  console.log(validated.destChain)        // ChainKind.Near
  console.log(validated.normalizedAmount) // Scaled for NEAR decimals
  console.log(validated.contractAddress)  // Bridge contract on Ethereum
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Validation failed: ${error.code}`, error.details)
  }
}

Bridge.getTokenDecimals

Gets decimal information for a token from the NEAR bridge contract.

Signature

bridge.getTokenDecimals(token: OmniAddress): Promise<TokenDecimals | null>

Parameters

token

OmniAddress

required

The token address in OmniAddress format.

Returns

TokenDecimals | null

Token decimal information, or null if the token is not registered.

Show TokenDecimals properties

decimals

number

Decimals on the foreign chain.

origin_decimals

number

Decimals on NEAR.

Example

const decimals = await bridge.getTokenDecimals(
  "eth:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
)

if (decimals) {
  console.log(`Foreign decimals: ${decimals.decimals}`)
  console.log(`NEAR decimals: ${decimals.origin_decimals}`)
}

Bridge.getBridgedToken

Gets the bridged token address on a destination chain.

Signature

bridge.getBridgedToken(token: OmniAddress, destChain: ChainKind): Promise<OmniAddress | null>

Parameters

token

OmniAddress

required

The source token address in OmniAddress format.

destChain

ChainKind

required

The destination chain to look up the bridged token on.

Returns

OmniAddress | null

The bridged token address on the destination chain, or null if not found.

Example

import { ChainKind } from "@omni-bridge/core"

const bridgedToken = await bridge.getBridgedToken(
  "eth:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  ChainKind.Near
)

if (bridgedToken) {
  console.log(`Bridged token on NEAR: ${bridgedToken}`)
}

Bridge.getUtxoDepositAddress

Gets a deposit address for Bitcoin or Zcash. Funds sent to this address will be bridged to NEAR.

Signature

bridge.getUtxoDepositAddress(
  chain: UtxoChain,
  recipient: string,
  options?: UtxoDepositOptions
): Promise<UtxoDepositResult>

Parameters

chain

UtxoChain

required

The UTXO chain (ChainKind.Btc or ChainKind.Zcash).

recipient

string

required

NEAR account ID to receive the bridged tokens.

options

UtxoDepositOptions

Optional configuration for the deposit.

Show UtxoDepositOptions properties

postActions

PostAction[]

Post-actions to execute after the deposit is finalized on NEAR. Used for automatic bridging to other chains.

extraMsg

string

Extra message to include in the deposit.

Returns

UtxoDepositResult

The deposit address and related information.

Show UtxoDepositResult properties

address

string

The BTC/Zcash address to send funds to.

chain

'btc' | 'zcash'

The chain type.

recipient

string

The recipient on NEAR.

postActions

PostAction[]

Post-actions if any were provided.

Example

import { ChainKind } from "@omni-bridge/core"

// Get a Bitcoin deposit address
const deposit = await bridge.getUtxoDepositAddress(
  ChainKind.Btc,
  "alice.near"
)

console.log(`Send BTC to: ${deposit.address}`)

// With post-actions for automatic bridging to Ethereum
const depositWithBridge = await bridge.getUtxoDepositAddress(
  ChainKind.Btc,
  "alice.near",
  {
    postActions: [{
      receiver_id: "omni.bridge.near",
      amount: "0",
      msg: JSON.stringify({ recipient: "eth:0x..." }),
    }]
  }
)

BridgeAPI

REST API client for interacting with the Omni Bridge backend services.

Constructor

new BridgeAPI(network: Network, config?: BridgeAPIConfig)

network

'mainnet' | 'testnet'

required

The network to connect to.

config

BridgeAPIConfig

Optional configuration.

Show BridgeAPIConfig properties

baseUrl

string

Override the default API base URL.

Example

import { BridgeAPI } from "@omni-bridge/core"

const api = new BridgeAPI("mainnet")

// With custom base URL
const customApi = new BridgeAPI("mainnet", {
  baseUrl: "https://my-api.example.com"
})

BridgeAPI.getTransferStatus

Gets the status of a transfer.

Signature

api.getTransferStatus(
  options: { originChain: Chain; originNonce: number } | { transactionHash: string }
): Promise<TransferStatus[]>

Parameters

options

object

required

Lookup options. Provide either transactionHash OR originChain + originNonce.

Show options

transactionHash

string

The transaction hash on the source chain.

originChain

Chain

The origin chain name ("Eth", "Near", "Sol", "Arb", "Base", "Bnb", "Btc", "Zcash", "Pol").

originNonce

number

The transfer nonce on the origin chain.

Returns

TransferStatus[]

Array of status values representing the transfer’s progression.Possible values:

"Initialized" - Transfer initiated on source chain
"Signed" - MPC signature obtained
"FastFinalisedOnNear" - Fast finalized on NEAR
"FinalisedOnNear" - Finalized on NEAR
"FastFinalised" - Fast finalized on destination
"Finalised" - Fully finalized
"Claimed" - Tokens claimed

Example

// By transaction hash
const status = await api.getTransferStatus({
  transactionHash: "0x..."
})

// By chain and nonce
const status = await api.getTransferStatus({
  originChain: "Eth",
  originNonce: 12345
})

console.log(`Latest status: ${status[status.length - 1]}`)

BridgeAPI.getFee

Gets a fee quote for a transfer.

Signature

api.getFee(
  sender: OmniAddress,
  recipient: OmniAddress,
  tokenAddress: OmniAddress,
  amount: string | bigint
): Promise<ApiFeeResponse>

Parameters

sender

OmniAddress

required

Sender address in OmniAddress format.

recipient

OmniAddress

required

Recipient address in OmniAddress format.

tokenAddress

OmniAddress

required

Token address in OmniAddress format.

amount

string | bigint

required

Transfer amount in the token’s smallest unit.

Returns

ApiFeeResponse

Fee quote information.

Show ApiFeeResponse properties

native_token_fee

bigint

Fee in the source chain’s native token.

gas_fee

bigint | null

Gas fee component (optional).

protocol_fee

bigint | null

Protocol fee component (optional).

usd_fee

number

Fee in USD.

transferred_token_fee

string | null

Fee in the transfer token (optional).

min_amount

string | null

Minimum transfer amount (optional).

insufficient_utxo

boolean

Whether there are insufficient UTXOs for UTXO chain transfers.

Example

const fee = await api.getFee(
  "eth:0xSender...",
  "near:recipient.near",
  "eth:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "1000000"
)

console.log(`Token fee: ${fee.transferred_token_fee}`)
console.log(`Native fee: ${fee.native_token_fee}`)
console.log(`USD fee: $${fee.usd_fee}`)

BridgeAPI.getTransfer

Gets full details of a transfer.

Signature

api.getTransfer(
  options: { originChain: Chain; originNonce: number } | { transactionHash: string }
): Promise<Transfer[]>

Parameters

Same as getTransferStatus.

Returns

Transfer[]

Array of transfer objects with full details.

Show Transfer properties

object | null

Transfer identifier containing origin_chain and kind (either Nonce or Utxo).

initialized

Transaction | null

Transaction when transfer was initialized.

signed

Transaction | null

Transaction when MPC signature was obtained.

fast_finalised_on_near

Transaction | null

Transaction when fast finalized on NEAR.

finalised_on_near

Transaction | null

Transaction when finalized on NEAR.

fast_finalised

Transaction | null

Transaction when fast finalized on destination.

finalised

Transaction | null

Transaction when fully finalized.

claimed

Transaction | null

Transaction when tokens were claimed.

transfer_message

object | null

Transfer message containing token, amount, sender, recipient, fee, and msg.

updated_fee

Transaction[]

Array of fee update transactions.

utxo_transfer

object | null

UTXO-specific transfer data for BTC/Zcash transfers.

Example

const transfers = await api.getTransfer({
  transactionHash: "0x..."
})

if (transfers.length > 0) {
  const transfer = transfers[0]
  console.log(`Token: ${transfer.transfer_message?.token}`)
  console.log(`Amount: ${transfer.transfer_message?.amount}`)
}

BridgeAPI.findTransfers

Searches for transfers by sender or transaction ID.

Signature

api.findTransfers(params: {
  sender?: string
  transactionId?: string
  offset?: number
  limit?: number
}): Promise<Transfer[]>

Parameters

params

object

required

Search parameters. At least one of sender or transactionId must be provided.

Show params

sender

string

Filter by sender address.

transactionId

string

Filter by transaction ID.

offset

number

Pagination offset. Defaults to 0.

limit

number

Maximum results to return. Defaults to 10.

Returns

Transfer[]

Array of matching transfers.

Example

const transfers = await api.findTransfers({
  sender: "eth:0x1234567890123456789012345678901234567890",
  limit: 10
})

console.log(`Found ${transfers.length} transfers`)

BridgeAPI.getAllowlistedTokens

Gets all tokens supported by the bridge.

Signature

api.getAllowlistedTokens(): Promise<Record<string, OmniAddress>>

Returns

Record<string, OmniAddress>

Map of token symbols to their OmniAddress.

Example

const tokens = await api.getAllowlistedTokens()

console.log(tokens)
// { "USDC": "eth:0x...", "wNEAR": "near:wrap.near", ... }

BridgeAPI.getUtxoDepositAddress

Gets a deposit address for Bitcoin or Zcash.

Signature

api.getUtxoDepositAddress(
  chain: UtxoChainParam,
  recipient: string,
  postActions?: PostAction[] | null,
  extraMsg?: string | null
): Promise<UtxoDepositAddressResponse>

Parameters

chain

'btc' | 'zcash'

required

The UTXO chain.

recipient

string

required

NEAR recipient account ID.

postActions

PostAction[] | null

Optional post-actions to execute after deposit finalization.

Show PostAction properties

receiver_id

string

required

NEAR account to receive the action.

amount

string

required

Amount to send with the action.

msg

string

required

Message/arguments for the action.

gas

string

Optional gas limit.

memo

string | null

Optional memo.

extraMsg

string | null

Optional extra message.

Returns

UtxoDepositAddressResponse

Show UtxoDepositAddressResponse properties

address

string

The deposit address on the UTXO chain.

Example

const result = await api.getUtxoDepositAddress(
  "btc",
  "alice.near"
)

console.log(`Deposit address: ${result.address}`)

Types

OmniAddress

Cross-chain address format with chain prefix.

type OmniAddress =
  | `eth:${string}`
  | `near:${string}`
  | `sol:${string}`
  | `arb:${string}`
  | `base:${string}`
  | `bnb:${string}`
  | `btc:${string}`
  | `zec:${string}`
  | `pol:${string}`

Examples:

"eth:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" - USDC on Ethereum
"near:alice.near" - NEAR account
"sol:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" - Token on Solana
"btc:bc1q..." - Bitcoin address

ChainKind

Enum representing supported chains, matching on-chain values.

enum ChainKind {
  Eth = 0,
  Near = 1,
  Sol = 2,
  Arb = 3,
  Base = 4,
  Bnb = 5,
  Btc = 6,
  Zcash = 7,
  Pol = 8,
}

ChainPrefix

Chain prefix strings used in OmniAddress format.

type ChainPrefix = "eth" | "near" | "sol" | "arb" | "base" | "bnb" | "btc" | "zec" | "pol"

Network

Network type for mainnet or testnet.

type Network = "mainnet" | "testnet"

Chain

API chain name strings.

type Chain = "Eth" | "Near" | "Sol" | "Arb" | "Base" | "Bnb" | "Btc" | "Zcash" | "Pol"

TransferParams

Parameters for initiating a transfer.

interface TransferParams {
  token: OmniAddress
  amount: bigint
  fee: bigint
  nativeFee: bigint
  sender: OmniAddress
  recipient: OmniAddress
  message?: string
}

token

OmniAddress

The token to transfer in OmniAddress format.

amount

bigint

Amount in the token’s smallest unit.

fee

bigint

Relayer fee in the transfer token.

nativeFee

bigint

Relayer fee in the source chain’s native token.

sender

OmniAddress

Sender address in OmniAddress format.

recipient

OmniAddress

Recipient address in OmniAddress format.

message

string

Optional message or memo.

ValidatedTransfer

Result of transfer validation, ready for building transactions.

interface ValidatedTransfer {
  params: TransferParams
  sourceChain: ChainKind
  destChain: ChainKind
  normalizedAmount: bigint
  normalizedFee: bigint
  contractAddress: string
  bridgedToken?: OmniAddress | undefined
}

params

TransferParams

The original transfer parameters.

sourceChain

ChainKind

Source chain extracted from sender address.

destChain

ChainKind

Destination chain extracted from recipient address.

normalizedAmount

bigint

Amount normalized for decimal differences.

normalizedFee

bigint

Fee normalized for decimal differences.

contractAddress

string

Bridge contract address on source chain.

bridgedToken

OmniAddress | undefined

Token address on destination chain if different.

TokenDecimals

Token decimal information from the bridge contract.

interface TokenDecimals {
  decimals: number
  origin_decimals: number
}

decimals

number

Decimals on the foreign chain.

origin_decimals

number

Decimals on NEAR.

UTXO

Unspent Transaction Output for Bitcoin/Zcash operations.

interface UTXO {
  txid: string
  vout: number
  balance: bigint | number | string
  tx_bytes?: Uint8Array | number[] | undefined
  path?: string | undefined
}

txid

string

Transaction ID.

vout

number

Output index in the transaction.

balance

bigint | number | string

Balance in satoshis/zatoshis.

tx_bytes

Uint8Array | number[] | undefined

Raw transaction bytes for signing.

path

string | undefined

HD derivation path for hardware wallets.

UtxoChain

UTXO chain subset type.

type UtxoChain = ChainKind.Btc | ChainKind.Zcash

EvmUnsignedTransaction

Unsigned transaction for EVM chains. Compatible with both viem and ethers v6.

interface EvmUnsignedTransaction {
  to: `0x${string}`
  data: `0x${string}`
  value: bigint
  chainId: number
}

`0x${string}`

Target contract address.

data

`0x${string}`

Encoded call data.

value

bigint

Native token value to send.

chainId

number

EVM chain ID.

NearUnsignedTransaction

Unsigned transaction for NEAR.

interface NearUnsignedTransaction {
  type: "near"
  signerId: string
  receiverId: string
  actions: NearAction[]
}

type

"near"

Transaction type identifier.

signerId

string

NEAR account ID of the signer.

receiverId

string

NEAR account ID of the receiver.

actions

NearAction[]

Array of actions to execute.

NearAction

A single action in a NEAR transaction.

interface NearAction {
  type: "FunctionCall"
  methodName: string
  args: Uint8Array
  gas: bigint
  deposit: bigint
}

type

"FunctionCall"

Action type.

methodName

string

Contract method to call.

args

Uint8Array

Encoded method arguments.

gas

bigint

Gas to attach.

deposit

bigint

NEAR tokens to deposit.

SolanaUnsignedTransaction

Unsigned transaction for Solana.

interface SolanaUnsignedTransaction {
  type: "solana"
  feePayer: string
  instructions: SolanaInstruction[]
}

type

"solana"

Transaction type identifier.

feePayer

string

Public key of the fee payer.

instructions

SolanaInstruction[]

Array of instructions to execute.

SolanaInstruction

A single instruction in a Solana transaction.

interface SolanaInstruction {
  programId: string
  keys: Array<{ pubkey: string; isSigner: boolean; isWritable: boolean }>
  data: Uint8Array
}

programId

string

Program ID to invoke.

keys

Array

Account keys with signer and writable flags.

data

Uint8Array

Instruction data.

BtcUnsignedTransaction

Unsigned transaction for Bitcoin/Zcash.

interface BtcUnsignedTransaction {
  type: "btc"
  inputs: Array<{ txid: string; vout: number; value: bigint }>
  outputs: Array<{ address: string; value: bigint }>
}

type

"btc"

Transaction type identifier.

inputs

Array

UTXO inputs to spend.

outputs

Array

Outputs to create.

Common Type Aliases

type U128 = bigint
type Nonce = bigint
type AccountId = string
type Fee = bigint

ChainAddresses

Contract addresses for all chains.

interface ChainAddresses {
  eth: EvmAddresses
  arb: EvmAddresses
  base: EvmAddresses
  bnb: EvmAddresses
  pol: EvmAddresses
  near: NearAddresses
  sol: SolanaAddresses
  btc: BtcAddresses
  zcash: ZcashAddresses
}

EvmAddresses

EVM chain contract addresses.

interface EvmAddresses {
  bridge: string
}

NearAddresses

NEAR chain configuration.

interface NearAddresses {
  contract: string
  rpcUrls: string[]
}

SolanaAddresses

Solana chain configuration.

interface SolanaAddresses {
  locker: string
  wormhole: string
  shimProgram: string
  eventAuthority: string
}

BtcAddresses

Bitcoin chain configuration.

interface BtcAddresses {
  network: Network
  apiUrl: string
  mempoolUrl: string
  rpcUrl: string
  btcConnector: string
  btcToken: string
  bitcoinRelayer: string
}

ZcashAddresses

Zcash chain configuration.

interface ZcashAddresses {
  network: Network
  apiUrl: string
  rpcUrl: string
  zcashConnector: string
  zcashToken: string
}

WormholeNetwork

Wormhole network type.

type WormholeNetwork = "Mainnet" | "Testnet" | "Devnet"

EvmChainKind

Type representing EVM-compatible chains.

type EvmChainKind =
  | ChainKind.Eth
  | ChainKind.Base
  | ChainKind.Arb
  | ChainKind.Bnb
  | ChainKind.Pol

Utility Functions

getChain

Extracts the chain from an OmniAddress.

function getChain(address: OmniAddress): ChainKind

Parameters:

address - An OmniAddress string

Returns: The ChainKind enum value Throws: ValidationError with code INVALID_ADDRESS or INVALID_CHAIN

import { getChain, ChainKind } from "@omni-bridge/core"

const chain = getChain("eth:0x...")
console.log(chain === ChainKind.Eth) // true

getAddress

Extracts the raw address (without chain prefix) from an OmniAddress.

function getAddress(address: OmniAddress): string

Parameters:

address - An OmniAddress string

Returns: The raw address without the chain prefix Throws: ValidationError with code INVALID_ADDRESS

import { getAddress } from "@omni-bridge/core"

const raw = getAddress("eth:0x1234...")
console.log(raw) // "0x1234..."

omniAddress

Constructs an OmniAddress from chain kind and raw address.

function omniAddress(chain: ChainKind, address: string): OmniAddress

Parameters:

chain - The ChainKind enum value
address - The raw address string

Returns: A properly formatted OmniAddress

import { omniAddress, ChainKind } from "@omni-bridge/core"

const addr = omniAddress(ChainKind.Eth, "0x1234...")
console.log(addr) // "eth:0x1234..."

getChainPrefix

Returns the chain prefix for a given chain kind.

function getChainPrefix(chain: ChainKind): ChainPrefix

Parameters:

chain - The ChainKind enum value

Returns: The chain prefix string

import { getChainPrefix, ChainKind } from "@omni-bridge/core"

const prefix = getChainPrefix(ChainKind.Zcash)
console.log(prefix) // "zec"

isEvmChain

Checks if a chain is an EVM-compatible chain.

function isEvmChain(chain: ChainKind): chain is EvmChainKind

Parameters:

chain - The ChainKind enum value

Returns: true if the chain is EVM-compatible (Eth, Base, Arb, Bnb, Pol)

import { isEvmChain, ChainKind } from "@omni-bridge/core"

console.log(isEvmChain(ChainKind.Eth))  // true
console.log(isEvmChain(ChainKind.Near)) // false
console.log(isEvmChain(ChainKind.Sol))  // false

normalizeAmount

Normalizes an amount from one decimal precision to another.

function normalizeAmount(
  amount: bigint,
  fromDecimals: number,
  toDecimals: number
): bigint

Parameters:

amount - The amount to normalize as a bigint
fromDecimals - The source decimal precision
toDecimals - The target decimal precision

Returns: The normalized amount as a bigint

import { normalizeAmount } from "@omni-bridge/core"

// Scale down from 18 decimals to 6 decimals
const scaled = normalizeAmount(1000000000000000000n, 18, 6)
console.log(scaled) // 1000000n

// Scale up from 6 decimals to 18 decimals
const scaledUp = normalizeAmount(1000000n, 6, 18)
console.log(scaledUp) // 1000000000000000000n

validateTransferAmount

Validates that a transfer amount will survive decimal normalization. Throws if invalid.

function validateTransferAmount(
  amount: bigint,
  fee: bigint,
  originDecimals: number,
  destinationDecimals: number
): void

Parameters:

amount - The amount to transfer
fee - The fee to be deducted
originDecimals - Decimals on the source chain
destinationDecimals - Decimals on the destination chain

Throws:

ValidationError with code INVALID_AMOUNT if amount is less than or equal to fee
ValidationError with code AMOUNT_TOO_SMALL if normalized amount would be zero

import { validateTransferAmount, ValidationError } from "@omni-bridge/core"

try {
  validateTransferAmount(1000000n, 100n, 6, 18)
  console.log("Amount is valid")
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Invalid: ${error.code}`)
  }
}

verifyTransferAmount

Checks if a transfer amount will be valid after normalization. Returns boolean instead of throwing.

function verifyTransferAmount(
  amount: bigint,
  fee: bigint,
  originDecimals: number,
  destinationDecimals: number
): boolean

Parameters:

amount - The amount to transfer
fee - The fee to be deducted
originDecimals - Decimals on the source chain
destinationDecimals - Decimals on the destination chain

Returns: true if the normalized amount (minus fee) will be greater than 0

import { verifyTransferAmount } from "@omni-bridge/core"

const isValid = verifyTransferAmount(1000000n, 100n, 6, 18)
console.log(isValid) // true

getMinimumTransferableAmount

Gets the minimum transferable amount for a token pair accounting for decimal normalization.

function getMinimumTransferableAmount(
  originDecimals: number,
  destinationDecimals: number
): bigint

Parameters:

originDecimals - Decimals on the source chain
destinationDecimals - Decimals on the destination chain

Returns: The minimum transferable amount as a bigint

import { getMinimumTransferableAmount } from "@omni-bridge/core"

// 18 decimals -> 6 decimals: need at least 1e12 to have 1 unit after scaling
const min = getMinimumTransferableAmount(18, 6)
console.log(min) // 1000000000000n

getAddresses

Gets contract addresses for a network.

function getAddresses(network: Network): ChainAddresses

Parameters:

network - The network ("mainnet" or "testnet")

Returns: ChainAddresses object with all chain configurations

import { getAddresses } from "@omni-bridge/core"

const addresses = getAddresses("mainnet")
console.log(addresses.eth.bridge)     // "0xe00c629afaccb0510995a2b95560e446a24c85b9"
console.log(addresses.near.contract)  // "omni.bridge.near"

getWormholeVaa

Fetches a Wormhole VAA for a Solana transaction. Waits up to 2 minutes for guardians to sign.

async function getWormholeVaa(
  txSignature: string,
  network: WormholeNetwork
): Promise<string>

Parameters:

txSignature - Solana transaction signature
network - Wormhole network ("Mainnet", "Testnet", or "Devnet")

Returns: Hex-encoded VAA string Throws: Error if no VAA is found within the timeout

import { getWormholeVaa } from "@omni-bridge/core"

const vaa = await getWormholeVaa(
  "5KtPn1...", // Solana transaction signature
  "Mainnet"
)
console.log(vaa) // Hex-encoded VAA

Configuration Constants

EVM_CHAIN_IDS

EVM chain IDs per network.

const EVM_CHAIN_IDS: Record<Network, Record<string, number>> = {
  mainnet: {
    eth: 1,
    arb: 42161,
    base: 8453,
    bnb: 56,
    pol: 137,
  },
  testnet: {
    eth: 11155111,  // Sepolia
    arb: 421614,    // Arbitrum Sepolia
    base: 84532,    // Base Sepolia
    bnb: 97,        // BSC Testnet
    pol: 80002,     // Polygon Amoy
  },
}

API_BASE_URLS

API base URLs per network.

const API_BASE_URLS: Record<Network, string> = {
  mainnet: "https://mainnet.api.bridge.nearone.org",
  testnet: "https://testnet.api.bridge.nearone.org",
}

Error Types

OmniBridgeError

Base error class for all SDK errors.

class OmniBridgeError extends Error {
  code: string
  details?: Record<string, unknown>

  constructor(
    message: string,
    code: string,
    details?: Record<string, unknown>
  )
}

code

string

Error code identifying the type of error.

details

Record<string, unknown>

Optional additional details about the error.

ValidationError

Thrown when transfer validation fails.

class ValidationError extends OmniBridgeError {
  constructor(
    message: string,
    code: ValidationErrorCode,
    details?: Record<string, unknown>
  )
}

Error Codes (ValidationErrorCode):

Code	Description
`INVALID_AMOUNT`	Amount is invalid (zero, negative, or less than fee)
`INVALID_ADDRESS`	Address format is invalid
`INVALID_CHAIN`	Chain is not supported
`TOKEN_NOT_REGISTERED`	Token is not registered on the bridge
`DECIMAL_OVERFLOW`	Amount exceeds precision limits
`AMOUNT_TOO_SMALL`	Amount too small after decimal normalization
`INVALID_CHECKSUM`	Address checksum is invalid

RpcError

Thrown when RPC calls fail.

class RpcError extends OmniBridgeError {
  retryCount: number

  constructor(
    message: string,
    retryCount: number,
    details?: Record<string, unknown>
  )
}

retryCount

number

Number of retries attempted before failing.

ProofError

Thrown when proof generation or verification fails.

class ProofError extends OmniBridgeError {
  constructor(
    message: string,
    code: "PROOF_NOT_READY" | "PROOF_FETCH_FAILED",
    details?: Record<string, unknown>
  )
}

Error Codes:

Code	Description
`PROOF_NOT_READY`	Proof is not yet available
`PROOF_FETCH_FAILED`	Failed to fetch proof from RPC

Error Handling

Basic error handling

import {
  createBridge,
  ValidationError,
  OmniBridgeError
} from "@omni-bridge/core"

const bridge = createBridge({ network: "mainnet" })

try {
  const validated = await bridge.validateTransfer(params)
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Validation failed: ${error.code}`)
    console.error(`Details:`, error.details)
  } else if (error instanceof OmniBridgeError) {
    console.error(`Bridge error: ${error.message}`)
  } else {
    throw error
  }
}

Handling specific validation codes

import { ValidationError, getMinimumTransferableAmount } from "@omni-bridge/core"

try {
  const validated = await bridge.validateTransfer(params)
} catch (error) {
  if (error instanceof ValidationError) {
    switch (error.code) {
      case "INVALID_ADDRESS":
        showError("Please enter a valid address")
        break
      case "AMOUNT_TOO_SMALL":
        const min = getMinimumTransferableAmount(srcDecimals, dstDecimals)
        showError(`Minimum amount is ${formatAmount(min)}`)
        break
      case "TOKEN_NOT_REGISTERED":
        showError("This token is not supported")
        break
      default:
        showError(error.message)
    }
  }
}

RPC error retry pattern

import { RpcError } from "@omni-bridge/core"

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  try {
    return await fn()
  } catch (error) {
    if (error instanceof RpcError && error.retryCount < maxRetries) {
      await new Promise(r => setTimeout(r, 1000 * error.retryCount))
      return withRetry(fn, maxRetries)
    }
    throw error
  }
}

Proof error handling

import { ProofError } from "@omni-bridge/core"

try {
  const proof = await getEvmProof(txHash, topic, chain)
} catch (error) {
  if (error instanceof ProofError) {
    if (error.code === "PROOF_NOT_READY") {
      console.log("Proof not ready yet, retrying...")
      await new Promise(r => setTimeout(r, 5000))
      // Retry
    } else if (error.code === "PROOF_FETCH_FAILED") {
      console.error("Could not fetch proof from RPC")
    }
  }
}

​Import

​createBridge

​Signature

​Parameters

​Returns

​Example

​Bridge.validateTransfer

​Signature

​Parameters

​Returns

​Validation Checks

​Errors

​Example

​Bridge.getTokenDecimals

​Signature

​Parameters

​Returns

​Example

​Bridge.getBridgedToken

​Signature

​Parameters

​Returns

​Example

​Bridge.getUtxoDepositAddress

​Signature

​Parameters

​Returns

​Example

​BridgeAPI

​Constructor

​Example

​BridgeAPI.getTransferStatus

​Signature

​Parameters

​Returns

​Example

​BridgeAPI.getFee

​Signature

​Parameters

​Returns

​Example

​BridgeAPI.getTransfer

​Signature

​Parameters

​Returns

​Example

​BridgeAPI.findTransfers

​Signature

​Parameters

​Returns

​Example

​BridgeAPI.getAllowlistedTokens

​Signature

​Returns

​Example

​BridgeAPI.getUtxoDepositAddress

​Signature

​Parameters

​Returns

​Example

​Types

​OmniAddress

​ChainKind

​ChainPrefix

​Network

​Chain

​TransferParams

​ValidatedTransfer

​TokenDecimals

​UTXO

​UtxoChain

​EvmUnsignedTransaction

​NearUnsignedTransaction

​NearAction

​SolanaUnsignedTransaction

​SolanaInstruction

​BtcUnsignedTransaction

​Common Type Aliases

​ChainAddresses

​EvmAddresses

Import

createBridge

Signature

Parameters

Returns

Example

Bridge.validateTransfer

Signature

Parameters

Returns

Validation Checks

Errors

Example

Bridge.getTokenDecimals

Signature

Parameters

Returns

Example

Bridge.getBridgedToken

Signature

Parameters

Returns

Example

Bridge.getUtxoDepositAddress

Signature

Parameters

Returns

Example

BridgeAPI

Constructor

Example

BridgeAPI.getTransferStatus

Signature

Parameters

Returns

Example

BridgeAPI.getFee

Signature

Parameters

Returns

Example

BridgeAPI.getTransfer

Signature

Parameters

Returns

Example

BridgeAPI.findTransfers

Signature

Parameters

Returns

Example

BridgeAPI.getAllowlistedTokens

Signature

Returns

Example

BridgeAPI.getUtxoDepositAddress

Signature

Parameters

Returns

Example

Types

OmniAddress

ChainKind

ChainPrefix

Network

Chain

TransferParams

ValidatedTransfer

TokenDecimals

UTXO

UtxoChain

EvmUnsignedTransaction

NearUnsignedTransaction

NearAction

SolanaUnsignedTransaction

SolanaInstruction

BtcUnsignedTransaction

Common Type Aliases

ChainAddresses

EvmAddresses