@omni-bridge/core

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"

function createBridge(config: BridgeConfig): Bridge

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(params: TransferParams): Promise<ValidatedTransfer>

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(token: OmniAddress): Promise<TokenDecimals | null>

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

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

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

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(
  chain: UtxoChain,
  recipient: string,
  options?: UtxoDepositOptions
): Promise<UtxoDepositResult>

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..." }),
    }]
  }
)

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

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"
})

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

// 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]}`)

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

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}`)

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

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}`)
}

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

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

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

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

const tokens = await api.getAllowlistedTokens()

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

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

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

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

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

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

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

type Network = "mainnet" | "testnet"

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

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

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

interface TokenDecimals {
  decimals: number
  origin_decimals: number
}

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

type UtxoChain = ChainKind.Btc | ChainKind.Zcash

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

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

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

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

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

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

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

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

interface EvmAddresses {
  bridge: string
}

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

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

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

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

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

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

function getChain(address: OmniAddress): ChainKind

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

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

function getAddress(address: OmniAddress): string

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

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

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

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

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

function getChainPrefix(chain: ChainKind): ChainPrefix

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

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

function isEvmChain(chain: ChainKind): chain is EvmChainKind

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

function normalizeAmount(
  amount: bigint,
  fromDecimals: number,
  toDecimals: number
): 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

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

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}`)
  }
}

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

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

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

function getMinimumTransferableAmount(
  originDecimals: number,
  destinationDecimals: number
): 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

function getAddresses(network: Network): ChainAddresses

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

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

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

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

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

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
  },
}

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

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

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

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

class RpcError extends OmniBridgeError {
  retryCount: number

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

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

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
  }
}

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)
    }
  }
}

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
  }
}

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")
    }
  }
}