Import import { // Factory createNearBuilder , type NearBuilder , type NearBuilderConfig , // Shims toNearKitTransaction , toNearApiJsActions , sendWithNearApiJs , // Storage utilities calculateStorageAccountId , type TransferMessageForStorage , // MPC Signature MPCSignature , type MPCSignatureRaw , // Proof serialization schemas EvmVerifyProofArgsSchema , WormholeVerifyProofArgsSchema , EvmProofSchema , FinTransferArgsSchema , DeployTokenArgsSchema , BindTokenArgsSchema , StorageDepositActionSchema , ChainKindSchema , ProofKindSchema , // Enums and constants ProofKind , GAS , DEPOSIT , // Types type EvmVerifyProofArgs , type WormholeVerifyProofArgs , type NearEvmProof , type FinalizationParams , type FastFinTransferParams , type TransferId , type TransferFee , type StorageDepositAction , type InitTransferEvent , type SignTransferEvent , type LogMetadataEvent , // UTXO types type UTXO , type UtxoBridgeFee , type UtxoConnectorConfig , type UtxoDepositFinalizationParams , type UtxoDepositMsg , type UtxoPostAction , type UtxoWithdrawalInitParams , type UtxoWithdrawalOutput , type UtxoWithdrawalVerifyParams , } from "@omni-bridge/near"
createNearBuilder Factory function to create a NEAR transaction builder.
Signature function createNearBuilder ( config : NearBuilderConfig ) : NearBuilder
Parameters config
NearBuilderConfig
required
network
'mainnet' | 'testnet'
required
The network to connect to.
Returns A builder instance with methods for building NEAR transactions.
Example import { createNearBuilder } from "@omni-bridge/near" const nearBuilder = createNearBuilder ({ network: "mainnet" })
NearBuilder Methods buildTransfer Build an unsigned transfer transaction to bridge tokens from NEAR.
Signature buildTransfer ( validated : ValidatedTransfer , signerId : string ): NearUnsignedTransaction
Parameters validated
ValidatedTransfer
required
The validated transfer from bridge.validateTransfer().
The NEAR account ID that will sign the transaction.
Returns An unsigned transaction ready to be signed and sent.
Example import { createBridge } from "@omni-bridge/core" import { createNearBuilder , toNearKitTransaction } from "@omni-bridge/near" import { Near } from "near-kit" const bridge = createBridge ({ network: "mainnet" }) const nearBuilder = createNearBuilder ({ network: "mainnet" }) const near = new Near ({ network: "mainnet" , privateKey: "ed25519:..." }) const validated = await bridge . validateTransfer ({ token: "near:wrap.near" , amount: 1000000000000000000000000 n , fee: 0 n , nativeFee: 0 n , sender: "near:alice.near" , recipient: "eth:0x1234567890123456789012345678901234567890" , }) const unsigned = nearBuilder . buildTransfer ( validated , "alice.near" ) const result = await toNearKitTransaction ( near , unsigned ). send ()
buildStorageDeposit Build a transaction to deposit storage on the bridge contract.
Signature buildStorageDeposit ( signerId : string , amount : bigint ): NearUnsignedTransaction
Parameters The NEAR account ID that will sign and pay for storage.
The amount of NEAR (in yoctoNEAR) to deposit for storage.
Returns An unsigned storage deposit transaction.
Example const deposit = await nearBuilder . getRequiredStorageDeposit ( "alice.near" ) if ( deposit > 0 n ) { const tx = nearBuilder . buildStorageDeposit ( "alice.near" , deposit ) await toNearKitTransaction ( near , tx ). send () }
getRequiredStorageDeposit Get the required storage deposit for an account on the bridge contract. Makes view calls to check current balance vs required amounts.
Signature getRequiredStorageDeposit ( accountId : string ): Promise < bigint >
Parameters The NEAR account ID to check storage for.
Returns Amount of additional storage deposit needed in yoctoNEAR. Returns 0n if sufficient storage exists.
Example const deposit = await nearBuilder . getRequiredStorageDeposit ( "alice.near" ) console . log ( `Need to deposit ${ deposit } yoctoNEAR` )
isTokenStorageRegistered Check if a token has storage registered for the bridge contract. If not, the bridge needs storage_deposit on the token before receiving transfers.
Signature isTokenStorageRegistered ( tokenId : string ): Promise < boolean >
Parameters The token contract ID to check.
Returns true if bridge has storage, false if storage_deposit is needed.
Example const isRegistered = await nearBuilder . isTokenStorageRegistered ( "wrap.near" ) if ( ! isRegistered ) { const tx = await nearBuilder . buildTokenStorageDeposit ( "wrap.near" , "alice.near" ) await toNearKitTransaction ( near , tx ). send () }
buildTokenStorageDeposit Build a storage deposit transaction on a token contract for the bridge. This is needed before the bridge can receive tokens.
Signature buildTokenStorageDeposit ( tokenId : string , signerId : string ): Promise < NearUnsignedTransaction >
Parameters The token contract ID to register storage on.
The NEAR account ID paying for storage.
Returns Promise<NearUnsignedTransaction>
An unsigned transaction for storage_deposit on the token contract.
Example const tx = await nearBuilder . buildTokenStorageDeposit ( "wrap.near" , "alice.near" ) await toNearKitTransaction ( near , tx ). send ()
buildFinalization Build a transaction to finalize an incoming transfer to NEAR.
Signature buildFinalization ( params : FinalizationParams ): NearUnsignedTransaction
Parameters params
FinalizationParams
required
The source chain of the transfer (e.g., ChainKind.Eth).
storageDepositActions
StorageDepositAction[]
required
Array of storage deposit actions for recipient accounts.
Wormhole VAA proof (provide either vaa or evmProof).
EVM proof data (provide either vaa or evmProof).
The NEAR account ID that will sign the transaction.
Returns An unsigned finalization transaction.
Example import { ChainKind } from "@omni-bridge/core" const tx = nearBuilder . buildFinalization ({ sourceChain: ChainKind . Eth , storageDepositActions: [], vaa: "AQAAAAMNALfP..." , // Wormhole VAA signerId: "relayer.near" , })
Build a transaction to log token metadata on the bridge. This is the first step in registering a new token.
Signature buildLogMetadata ( token : string , signerId : string ): NearUnsignedTransaction
Parameters The NEAR token contract ID (e.g., "wrap.near").
The NEAR account ID that will sign the transaction.
Returns An unsigned log metadata transaction.
Example const tx = nearBuilder . buildLogMetadata ( "wrap.near" , "alice.near" ) await toNearKitTransaction ( near , tx ). send ()
buildDeployToken Build a transaction to deploy a token on a destination chain. Used for registering NEAR tokens on other chains.
Signature buildDeployToken ( destinationChain : ChainKind , proverArgs : Uint8Array , signerId : string , deposit : bigint ): NearUnsignedTransaction
Parameters The destination chain to deploy the token on.
Serialized prover arguments (use serializeEvmProofArgs or serializeWormholeProofArgs).
The NEAR account ID that will sign the transaction.
The NEAR deposit required for deployment.
Returns An unsigned deploy token transaction.
Example import { ChainKind } from "@omni-bridge/core" const proverArgs = nearBuilder . serializeWormholeProofArgs ({ proof_kind: ProofKind . LogMetadata , vaa: vaaString , }) const tx = nearBuilder . buildDeployToken ( ChainKind . Eth , proverArgs , "alice.near" , 1000000000000000000000000 n // 1 NEAR )
buildBindToken Build a transaction to bind a token from a source chain. Used for registering foreign tokens on NEAR.
Signature buildBindToken ( sourceChain : ChainKind , proverArgs : Uint8Array , signerId : string , deposit : bigint ): NearUnsignedTransaction
Parameters The source chain where the token originates.
Serialized prover arguments.
The NEAR account ID that will sign the transaction.
The NEAR deposit required for binding.
Returns An unsigned bind token transaction.
Example import { ChainKind } from "@omni-bridge/core" const tx = nearBuilder . buildBindToken ( ChainKind . Eth , proverArgs , "alice.near" , 1000000000000000000000000 n )
buildSignTransfer Build a transaction to request MPC signature for a transfer. Used by relayers.
Signature buildSignTransfer ( transferId : TransferId , feeRecipient : string , fee : { fee: string ; native_fee : string }, signerId : string ): NearUnsignedTransaction
Parameters origin_chain
ChainKind | number | string
required
The chain where the transfer originated.
The nonce of the transfer on the origin chain.
The NEAR account to receive the relayer fee.
The token fee amount as a string.
The native token fee amount as a string.
The NEAR account ID that will sign the transaction.
Returns An unsigned sign transfer transaction.
Example import { ChainKind } from "@omni-bridge/core" const tx = nearBuilder . buildSignTransfer ( { origin_chain: ChainKind . Eth , origin_nonce: 123 n }, "relayer.near" , { fee: "1000000" , native_fee: "0" }, "relayer.near" )
buildFastFinTransfer Build a transaction for fast finalization of a transfer. Used by relayers to provide immediate liquidity.
Signature buildFastFinTransfer ( params : FastFinTransferParams , signerId : string ): NearUnsignedTransaction
Parameters params
FastFinTransferParams
required
Show FastFinTransferParams
The NEAR token contract ID.
The original transfer amount.
The amount to send to recipient (after fees).
Optional message attached to the transfer.
Optional storage deposit amount.
The NEAR account ID that will sign the transaction.
Returns An unsigned fast finalization transaction.
Example import { ChainKind } from "@omni-bridge/core" const tx = nearBuilder . buildFastFinTransfer ({ tokenId: "wrap.near" , amount: "1000000000000000000000000" , amountToSend: "999000000000000000000000" , transferId: { origin_chain: ChainKind . Eth , origin_nonce: 123 n }, recipient: "near:bob.near" , fee: { fee: "1000000" , native_fee: "0" }, storageDepositAmount: "1250000000000000000000" , relayer: "relayer.near" , }, "relayer.near" )
serializeEvmProofArgs Serialize EVM proof arguments for the prover contract.
Signature serializeEvmProofArgs ( args : EvmVerifyProofArgs ): Uint8Array
Parameters args
EvmVerifyProofArgs
required
The type of proof (ProofKind.InitTransfer, ProofKind.FinTransfer, etc.).
Index of the log in the transaction.
Serialized log entry data.
Index of the receipt in the block.
Serialized block header data.
Array of Merkle proof nodes.
Returns Borsh-serialized proof arguments.
Example const serialized = nearBuilder . serializeEvmProofArgs ({ proof_kind: ProofKind . InitTransfer , proof: { log_index: 0 n , log_entry_data: new Uint8Array ([ ... ]), receipt_index: 0 n , receipt_data: new Uint8Array ([ ... ]), header_data: new Uint8Array ([ ... ]), proof: [ new Uint8Array ([ ... ])], }, })
serializeWormholeProofArgs Serialize Wormhole VAA proof arguments for the prover contract.
Signature serializeWormholeProofArgs ( args : WormholeVerifyProofArgs ): Uint8Array
Parameters args
WormholeVerifyProofArgs
required
Show WormholeVerifyProofArgs
The Wormhole VAA as a base64 or hex string.
Returns Borsh-serialized proof arguments.
Example const serialized = nearBuilder . serializeWormholeProofArgs ({ proof_kind: ProofKind . InitTransfer , vaa: "AQAAAAMNALfP..." , })
UTXO Methods (BTC/Zcash) Methods for interacting with the Bitcoin and Zcash UTXO connectors on NEAR.
buildUtxoDepositFinalization Build a transaction to finalize a UTXO deposit on NEAR. Calls verify_deposit on the connector contract.
Signature buildUtxoDepositFinalization ( params : UtxoDepositFinalizationParams ): NearUnsignedTransaction
Parameters params
UtxoDepositFinalizationParams
required
Show UtxoDepositFinalizationParams
The NEAR account to receive the tokens.
Optional post-deposit actions (e.g., bridge to another chain).
Output index in the transaction.
Block hash containing the transaction.
Transaction index in the block.
Merkle proof for transaction inclusion.
The NEAR account ID that will sign the transaction.
Returns An unsigned verify_deposit transaction.
buildUtxoWithdrawalInit Build a transaction to initiate a UTXO withdrawal from NEAR. Calls ft_transfer_call on the nBTC/nZEC token.
Signature buildUtxoWithdrawalInit ( params : UtxoWithdrawalInitParams ): NearUnsignedTransaction
Parameters params
UtxoWithdrawalInitParams
required
Show UtxoWithdrawalInitParams
Target BTC/Zcash address.
UTXO inputs in “txid:vout” format.
outputs
UtxoWithdrawalOutput[]
required
Show UtxoWithdrawalOutput
Output value in satoshis/zatoshis.
Output script pubkey (hex).
Total amount to transfer (including fees).
Optional maximum gas fee in satoshis/zatoshis.
The NEAR account ID that will sign the transaction.
Returns An unsigned ft_transfer_call transaction.
buildUtxoWithdrawalVerify Build a transaction to verify a UTXO withdrawal on NEAR. Calls btc_verify_withdraw on the connector.
Signature buildUtxoWithdrawalVerify ( params : UtxoWithdrawalVerifyParams ): NearUnsignedTransaction
Parameters params
UtxoWithdrawalVerifyParams
required
Show UtxoWithdrawalVerifyParams
Block height of the transaction.
Position in the merkle tree.
The NEAR account ID that will sign the transaction.
Returns An unsigned btc_verify_withdraw transaction.
getUtxoConnectorAddress Get the UTXO connector contract address for a chain.
Signature getUtxoConnectorAddress ( chain : "btc" | "zcash" ): string
Parameters Returns The connector contract address.
getUtxoTokenAddress Get the UTXO token contract address for a chain.
Signature getUtxoTokenAddress ( chain : "btc" | "zcash" ): string
Parameters Returns The token contract address (nBTC or nZEC).
getUtxoConnectorConfig Get the UTXO connector configuration from the contract.
Signature getUtxoConnectorConfig ( chain : "btc" | "zcash" ): Promise < UtxoConnectorConfig >
Parameters Returns Promise<UtxoConnectorConfig>
The change address for withdrawals.
Fee configuration for deposits.
Fee configuration for withdrawals.
Minimum withdrawal amount.
max_withdrawal_input_number
Maximum number of inputs for withdrawal.
getUtxoAvailableOutputs Get available UTXOs from the connector contract.
Signature getUtxoAvailableOutputs ( chain : "btc" | "zcash" ): Promise < UTXO [] >
Parameters Returns Array of available UTXOs for withdrawal.
getUtxoTokenBalance Get the nBTC/nZEC token balance for an account.
Signature getUtxoTokenBalance ( chain : "btc" | "zcash" , accountId : string ): Promise < bigint >
Parameters NEAR account to check balance for.
Returns Token balance in satoshis/zatoshis.
calculateUtxoWithdrawalFee Calculate the bridge fee for a UTXO withdrawal.
Signature calculateUtxoWithdrawalFee ( chain : "btc" | "zcash" , amount : bigint ): Promise < bigint >
Parameters Withdrawal amount in satoshis/zatoshis.
Returns Shim Functions Functions to convert SDK transactions to library-specific formats.
toNearKitTransaction Convert a NearUnsignedTransaction to a near-kit TransactionBuilder. near-kit handles nonce, blockHash, and signing automatically.
Signature function toNearKitTransaction ( near : Near , unsigned : NearUnsignedTransaction ) : TransactionBuilder
Parameters A configured near-kit Near instance.
unsigned
NearUnsignedTransaction
required
The unsigned transaction from the builder.
Returns A near-kit TransactionBuilder that can be sent with .send() or built with .build().
Example import { Near } from "near-kit" import { createNearBuilder , toNearKitTransaction } from "@omni-bridge/near" const near = new Near ({ network: "mainnet" , privateKey: "ed25519:..." , }) const nearBuilder = createNearBuilder ({ network: "mainnet" }) const unsigned = nearBuilder . buildTransfer ( validated , "alice.near" ) const result = await toNearKitTransaction ( near , unsigned ). send ()
toNearApiJsActions Convert NearUnsignedTransaction actions to @near-js/transactions Action array. Use this with Account.signAndSendTransaction().
Signature function toNearApiJsActions ( unsigned : NearUnsignedTransaction ) : Action []
Parameters unsigned
NearUnsignedTransaction
required
The unsigned transaction from the builder.
Returns Array of Action objects for use with @near-js/accounts.
Example import { Account } from "@near-js/accounts" import { JsonRpcProvider } from "@near-js/providers" import { InMemoryKeyStore } from "@near-js/keystores" import { KeyPair } from "@near-js/crypto" import { InMemorySigner } from "@near-js/signers" import { toNearApiJsActions } from "@omni-bridge/near" const keyStore = new InMemoryKeyStore () await keyStore . setKey ( "mainnet" , "alice.near" , KeyPair . fromString ( "ed25519:..." )) const provider = new JsonRpcProvider ({ url: "https://rpc.mainnet.near.org" }) const signer = new InMemorySigner ( keyStore ) const account = new Account ({ accountId: "alice.near" , provider , signer }) const actions = toNearApiJsActions ( unsigned ) const result = await account . signAndSendTransaction ({ receiverId: unsigned . receiverId , actions , })
sendWithNearApiJs Convenience wrapper that converts and sends a transaction using @near-js/accounts.
Signature function sendWithNearApiJs ( account : Account , unsigned : NearUnsignedTransaction ) : Promise < FinalExecutionOutcome >
Parameters A @near-js/accounts Account instance with signer configured.
unsigned
NearUnsignedTransaction
required
The unsigned transaction from the builder.
Returns Promise<FinalExecutionOutcome>
The transaction execution outcome.
Example import { Account } from "@near-js/accounts" import { sendWithNearApiJs } from "@omni-bridge/near" // ... setup account as shown above const unsigned = nearBuilder . buildTransfer ( validated , "alice.near" ) const result = await sendWithNearApiJs ( account , unsigned ) console . log ( "Transaction hash:" , result . transaction . hash )
MPCSignature Class Class representing an MPC signature from the NEAR bridge contract.
Constructor constructor ( big_r : AffinePoint , s : Scalar , recovery_id : number )
Properties The R component of the signature as an affine point. Hex-encoded affine point.
The S component of the signature. Hex-encoded scalar value.
The recovery ID (0 or 1).
Methods toBytes Convert the signature to bytes for use on Solana or EVM.
toBytes ( forEvm : boolean = false ): Uint8Array
If true, adds 27 to recovery_id for EVM compatibility.
fromRaw (static) Create an MPCSignature from raw contract log data.
static fromRaw ( raw : MPCSignatureRaw ): MPCSignature
Example import { MPCSignature } from "@omni-bridge/near" // From contract logs const raw = { big_r: { affine_point: "02abc..." }, s: { scalar: "def..." }, recovery_id: 0 , } const signature = MPCSignature . fromRaw ( raw ) // For Solana const solanaBytes = signature . toBytes ( false ) // For EVM (adds 27 to recovery_id) const evmBytes = signature . toBytes ( true )
calculateStorageAccountId Calculate the storage account ID for a transfer message. This replicates the on-chain calculation.
Signature function calculateStorageAccountId ( transferMessage : TransferMessageForStorage ) : string
Parameters transferMessage
TransferMessageForStorage
required
Show TransferMessageForStorage
Token as OmniAddress string (e.g., "near:wrap.near").
Recipient as OmniAddress string.
Sender as OmniAddress string.
Message attached to transfer.
Returns The storage account ID as a hex string.
Example import { calculateStorageAccountId } from "@omni-bridge/near" const storageAccountId = calculateStorageAccountId ({ token: "near:wrap.near" , amount: 1000000000000000000000000 n , recipient: "eth:0x1234567890123456789012345678901234567890" , fee: { fee: 0 n , native_fee: 0 n }, sender: "near:alice.near" , msg: "" , })
Types NearUnsignedTransaction The unsigned transaction format returned by the builder.
interface NearUnsignedTransaction { type : "near" signerId : string receiverId : string actions : NearAction [] }
NearAction An action within a NEAR transaction.
interface NearAction { type : "FunctionCall" methodName : string args : Uint8Array gas : bigint deposit : bigint }
TransferId Identifier for a cross-chain transfer.
interface TransferId { origin_chain : ChainKind | number | string origin_nonce : bigint | string }
TransferFee Fee structure for transfers.
interface TransferFee { fee : string native_fee : string }
StorageDepositAction Action for depositing storage during finalization.
interface StorageDepositAction { token_id : string account_id : string storage_deposit_amount ?: bigint }
UtxoPostAction Post-action to execute after UTXO deposit is finalized.
interface UtxoPostAction { receiver_id : string amount : bigint memo ?: string msg : string gas ?: bigint }
UtxoBridgeFee Bridge fee configuration.
interface UtxoBridgeFee { fee_min : string fee_rate : number protocol_fee_rate : number }
UTXO UTXO structure for Bitcoin/Zcash operations.
interface UTXO { txid : string vout : number balance : bigint path ?: string tx_bytes ?: number [] }
Enums ProofKind Types of proofs for finalization and token operations.
enum ProofKind { InitTransfer = 0 , FinTransfer = 1 , DeployToken = 2 , LogMetadata = 3 , }
Constants GAS Pre-defined gas amounts for NEAR transactions.
const GAS = { LOG_METADATA: 300_000_000_000_000 n , // 300 Tgas DEPLOY_TOKEN: 120_000_000_000_000 n , // 120 Tgas BIND_TOKEN: 300_000_000_000_000 n , // 300 Tgas INIT_TRANSFER: 300_000_000_000_000 n , // 300 Tgas FIN_TRANSFER: 300_000_000_000_000 n , // 300 Tgas SIGN_TRANSFER: 300_000_000_000_000 n , // 300 Tgas STORAGE_DEPOSIT: 10_000_000_000_000 n , // 10 Tgas FAST_FIN_TRANSFER: 300_000_000_000_000 n , // 300 Tgas UTXO_VERIFY_DEPOSIT: 300_000_000_000_000 n , // 300 Tgas UTXO_INIT_WITHDRAWAL: 100_000_000_000_000 n , // 100 Tgas UTXO_VERIFY_WITHDRAWAL: 5_000_000_000_000 n , // 5 Tgas }
DEPOSIT Pre-defined deposit amounts.
const DEPOSIT = { ONE_YOCTO: 1 n , }
Borsh Schemas The package exports Borsh serialization schemas for advanced use cases.
// Proof schemas EvmVerifyProofArgsSchema // EVM proof arguments WormholeVerifyProofArgsSchema // Wormhole VAA proof arguments EvmProofSchema // EVM proof structure // Transaction argument schemas FinTransferArgsSchema // Finalization arguments DeployTokenArgsSchema // Deploy token arguments BindTokenArgsSchema // Bind token arguments StorageDepositActionSchema // Storage deposit action // Enum schemas ChainKindSchema // ChainKind enum ProofKindSchema // ProofKind enum
These schemas use the @zorsh/zorsh library and can be used for custom serialization:
import { FinTransferArgsSchema , ChainKind , ProofKind } from "@omni-bridge/near" const serialized = FinTransferArgsSchema . serialize ({ chain_kind: ChainKind . Eth , storage_deposit_actions: [], prover_args: new Uint8Array ([ ... ]), })