`bridgeAndExecute()`

SET UP THE SDK BEFORE YOU START:

You can find the SDK setup instructions in the Quickstart page.
We also created a tutorial to make it easier to understand how devs need to initialize the Nexus SDK in their project.

Use the bridgeAndExecute() function to bridge a token and execute a contract function on the recipient chain in a single flow. Use the simulateBridgeAndExecute() function to simulate bridgeAndExecute() before sending an actual transaction.

Note: Check out the API reference for a full list of supported tokens and chains.

Method signature

Typescript


async bridgeAndExecute(
  params: BridgeAndExecuteParams,
  options?: OnEventParam,
): Promise<BridgeAndExecuteResult>
 
 
async simulateBridgeAndExecute(
  params: BridgeAndExecuteParams,
): Promise<BridgeAndExecuteSimulationResult>

Parameters

Typescript


export interface BridgeAndExecuteParams {
  toChainId: number;
  token: string;
  amount: bigint;
  sourceChains?: number[];
  execute: Omit<ExecuteParams, 'toChainId'>;
  enableTransactionPolling?: boolean;
  transactionTimeout?: number;
  waitForReceipt?: boolean;
  receiptTimeout?: number;
  requiredConfirmations?: number;
  recentApprovalTxHash?: string;
}
 
export interface ExecuteParams {
  toChainId: number;
  to: Hex;
  value?: bigint;
  data?: Hex;
  gas?: bigint;
  gasPrice?: bigint;
  enableTransactionPolling?: boolean;
  transactionTimeout?: number;
  // Transaction receipt confirmation options
  waitForReceipt?: boolean;
  receiptTimeout?: number;
  requiredConfirmations?: number;
  tokenApproval?: {
    token: string;
    amount: bigint;
    spender: Hex;
  };
}

BridgeAndExecuteParams: Parameters for using the bridgeAndExecute() function.
- toChainId (number, required): The chain ID of the destination chain.
- token (string, required): The token to be bridged in this flow.
- amount (bigint, required): The amount of tokens to be used in this flow.
- sourceChains (number[], optional): The chain IDs of the source chains to be used for the bridge. Useful if you want to maintain your holdings on some chains.
- execute (Omit<ExecuteParams>, ‘toChainId’>, required): Contract call on the destination chain
- enableTransactionPolling (boolean, optional): Whether to enable transaction polling. Defaults to false.
- transactionTimeout (number, optional)
- waitForReceipt (boolean, optional)
- receiptTimeout (number, optional)
- requiredConfirmations (number, optional)
- recentApprovalTxHash (string, optional)
options: OnEventParam (optional): Optional callback function to listen to the events emitted by the transfer operation.
- onEvent: SDK emits these events as the transaction progresses. This is helpful to add when trying to display transaction progress to the user. With this you receive:
  - STEPS_LIST: An ordered array of BridgeStepType objects. This array contains the steps that will be executed to fulfill the intent.
  - STEP_COMPLETE: A single BridgeStepType that is emitted for each completed step of the intent’s fulfillment.

You can check out the type definitions for each step type in the Bridge Events page.

Example

Typescript


import { BridgeAndExecuteParams, BridgeAndExecuteResult, NEXUS_EVENTS } from '@avail-project/nexus-core';
 
// Direct contract execution
const result = await sdk.execute({
  toChainId: 1,
  to: '0xc3d688B66703497DAA19211EEdff47f25384cdc3',
  data: '0x...',
  tokenApproval: { token: 'USDC', amount: 1000000n },
});
 
// Bridge and execute
const bridgeAndExecuteResult = await sdk.bridgeAndExecute(
  {
    token: 'USDC',
    amount: 100_000_000n, // 100 USDC (6 decimals)
    toChainId: 1,
    sourceChains: [8453],
    execute: {
      to: '0x...',
      data: '0x...',
      tokenApproval: { token: 'USDC', amount: 100_000_000n }, // 100 USDC (6 decimals)
    },
  },
  {
    onEvent: (event) => {
      if (event.name === NEXUS_EVENTS.STEPS_LIST) console.log('Bridge+Execute steps:', event.args);
      if (event.name === NEXUS_EVENTS.STEP_COMPLETE) console.log('Step completed:', event.args);
    },
  },
);
 
console.log('Bridge and execute result:', bridgeAndExecuteResult);
 
 
const bridgeAndExecuteSimulation = await sdk.simulateBridgeAndExecute({
  token: 'USDC',
  amount: 100_000_000n, // 100 USDC (6 decimals)
  toChainId: 1,
  sourceChains: [8453],
  execute: {
    to: '0x...',
    data: '0x...',
    // tokenApproval optional for simulation
  },
});
 
console.log('Bridge and execute simulation:', bridgeAndExecuteSimulation);

Return Value

The return value is a BridgeAndExecuteResult object.

Typescript


export type BridgeAndExecuteResult = {
  executeTransactionHash: string;
  executeExplorerUrl: string;
  approvalTransactionHash?: string;
  bridgeExplorerUrl?: string; // undefined when bridge is skipped
  toChainId: number;
  bridgeSkipped: boolean; // indicates if bridge was skipped due to sufficient funds
};
 
export type BridgeAndExecuteSimulationResult = {
  bridgeSimulation: SimulationResult | null; // null if bridging is skipped
  executeSimulation: {
    gasUsed: bigint;
    gasPrice: bigint;
    gasFee: bigint; // gasUsed * gasPrice
  };
};