Execute Operations

Execute smart contracts with automatic bridging and funding

execute

Standalone function to execute a smart contract call on a destination chain. Use this when you already have sufficient funds on the target chain.

await sdk.execute(
  params: ExecuteParams,
  options?: OnEventParam
): Promise<ExecuteResult>

Parameters

params · ExecuteParams · required

Execute operation parameters

Show properties

toChainId · number · required

Target chain ID

to · Hex · required

Contract address to execute

data · Hex

Encoded function call data

value · bigint

Native token value to send (in wei)

gas · bigint

Gas limit for the transaction

gasPrice · 'low' | 'medium' | 'high'

Gas price strategy

tokenApproval · object

Token approval before execution

Show properties

token · string · required

Token symbol to approve

amount · bigint · required

Amount to approve

spender · Hex · required

Spender address (usually the contract)

waitForReceipt · boolean

Wait for transaction receipt before returning

receiptTimeout · number

Receipt wait timeout in milliseconds

requiredConfirmations · number

Required block confirmations

options · OnEventParam

Event callbacks

Returns

ExecuteResult · object

Show properties

transactionHash · string

Transaction hash

explorerUrl · string

Block explorer URL

chainId · number

Chain ID where execution occurred

receipt · TransactionReceipt

Transaction receipt (if waitForReceipt was true)

confirmations · number

Number of confirmations

gasUsed · string

Gas used by the transaction

effectiveGasPrice · string

Effective gas price

approvalTransactionHash · string

Token approval transaction hash (if approval was needed)

Example

Basic Contract Call

import { encodeFunctionData } from 'viem';

// Encode function call
const data = encodeFunctionData({
  abi: contractABI,
  functionName: 'deposit',
  args: [amount],
});

const result = await sdk.execute({
  toChainId: 1, // Ethereum
  to: '0xContractAddress',
  data,
});

console.log('Transaction:', result.transactionHash);
console.log('Explorer:', result.explorerUrl);

---

simulateExecute

Simulate contract execution to estimate gas costs and validate parameters before executing.

await sdk.simulateExecute(
  params: ExecuteParams
): Promise<ExecuteSimulation>

Parameters

params · ExecuteParams · required

Same parameters as execute() method

Returns

ExecuteSimulation · object

Show properties

gasUsed · bigint

Estimated gas units required

gasPrice · bigint

Current gas price (in wei)

gasFee · bigint

Total estimated gas fee (gasUsed * gasPrice)

Example

import { encodeFunctionData, formatEther } from 'viem';

const data = encodeFunctionData({
  abi: contractABI,
  functionName: 'deposit',
  args: [amount],
});

const simulation = await sdk.simulateExecute({
  toChainId: 1,
  to: '0xContract',
  data,
});

console.log('Gas estimate:', simulation.gasUsed);
console.log('Gas price:', formatEther(simulation.gasPrice));
console.log('Total fee:', formatEther(simulation.gasFee), 'ETH');

// Show confirmation to user
const confirmed = confirm(
  `Estimated fee: ${formatEther(simulation.gasFee)} ETH. Continue?`
);

if (confirmed) {
  await sdk.execute({
    toChainId: 1,
    to: '0xContract',
    data,
    gas: simulation.gasUsed, // Use simulated gas
  });
}

---

bridgeAndExecute

Bridge tokens to a destination chain and execute a contract call. The SDK automatically checks if bridging is needed based on available balance.

await sdk.bridgeAndExecute(
  params: BridgeAndExecuteParams,
  options?: OnEventParam & BeforeExecuteHook
): Promise<BridgeAndExecuteResult>

Parameters

params · BridgeAndExecuteParams · required

Bridge and execute parameters

Show properties

token · string · required

Token to bridge

amount · bigint · required

Amount to bridge (in smallest unit)

toChainId · number · required

Destination chain ID

sourceChains · number[]

Specific source chains to use (auto-selected if omitted)

execute · Omit<ExecuteParams, 'toChainId'> · required

Contract execution parameters (all ExecuteParams except toChainId)

options · OnEventParam & BeforeExecuteHook

Event callbacks and pre-execution hook

Show properties

onEvent · function

Event callback for progress tracking

beforeExecute · () => Promise<{ value?, data?, gas? }>

Hook called before contract execution. Use to update execution parameters dynamically based on bridged amount.

Returns

BridgeAndExecuteResult · object

Show properties

executeTransactionHash · string

Execute transaction hash

executeExplorerUrl · string

Execute transaction explorer URL

toChainId · number

Destination chain ID

bridgeSkipped · boolean

Indicates if bridge was skipped due to sufficient balance

approvalTransactionHash · string

Token approval transaction hash (if approval was needed)

bridgeExplorerUrl · string

Bridge explorer URL (undefined if bridge was skipped)

intent · ReadableIntent

Intent details (undefined if bridge was skipped)

Example

Basic Bridge + Execute

import { encodeFunctionData } from 'viem';

const amount = 100_000_000n; // 100 USDC

const data = encodeFunctionData({
  abi: contractABI,
  functionName: 'deposit',
  args: [amount],
});

const result = await sdk.bridgeAndExecute({
  token: 'USDC',
  amount: amount,
  toChainId: 1,
  execute: {
    to: '0xDeFiProtocol',
    data,
    tokenApproval: {
      token: 'USDC',
      amount: amount,
      spender: '0xDeFiProtocol',
    },
  },
});

if (result.bridgeSkipped) {
  console.log('Used existing balance - no bridge needed');
} else {
  console.log('Bridge TX:', result.bridgeExplorerUrl);
}
console.log('Execute TX:', result.executeExplorerUrl);

---

simulateBridgeAndExecute

Simulate bridge-and-execute operation to estimate costs before execution.

await sdk.simulateBridgeAndExecute(
  params: BridgeAndExecuteParams
): Promise<BridgeAndExecuteSimulationResult>

Parameters

params · BridgeAndExecuteParams · required

Same parameters as bridgeAndExecute() method

Returns

BridgeAndExecuteSimulationResult · object

Show properties

bridgeSimulation · SimulationResult | null

Bridge simulation (null if bridge not needed due to sufficient balance)

executeSimulation · ExecuteSimulation

Execute simulation with gas estimates

Example

import { encodeFunctionData, formatEther } from 'viem';

const amount = 100_000_000n;

const data = encodeFunctionData({
  abi: contractABI,
  functionName: 'deposit',
  args: [amount],
});

const simulation = await sdk.simulateBridgeAndExecute({
  token: 'USDC',
  amount: amount,
  toChainId: 1,
  execute: {
    to: '0xContract',
    data,
    tokenApproval: {
      token: 'USDC',
      amount: amount,
      spender: '0xContract',
    },
  },
});

// Display cost breakdown
if (simulation.bridgeSimulation) {
  console.log('Bridge fees:', simulation.bridgeSimulation.intent.fees.total);
  console.log('Bridge from:', simulation.bridgeSimulation.intent.sources);
}

console.log('Execute gas:', simulation.executeSimulation.gasUsed);
console.log('Execute fee:', formatEther(simulation.executeSimulation.gasFee));

// Calculate total cost
const bridgeFee = simulation.bridgeSimulation 
  ? parseFloat(simulation.bridgeSimulation.intent.fees.total)
  : 0;
const executeFee = formatEther(simulation.executeSimulation.gasFee);

console.log(`Total estimated cost: $${bridgeFee.toFixed(2)} + ${executeFee} ETH`);

---

Bridge Skip Optimization

The SDK automatically detects if you have sufficient balance on the destination chain:

const result = await sdk.bridgeAndExecute({
  token: 'USDC',
  amount: 100_000_000n,
  toChainId: 1,
  execute: { /* ... */ },
});

if (result.bridgeSkipped) {
  // Bridge was not needed - used existing balance
  console.log('✓ Executed using local balance');
  console.log('✓ Saved bridge fees and time!');
  console.log('Execute TX:', result.executeTransactionHash);
} else {
  // Bridge occurred first
  console.log('Bridge TX:', result.bridgeExplorerUrl);
  console.log('Execute TX:', result.executeTransactionHash);
}

---

Error Handling

import { NexusError, ERROR_CODES } from '@avail-project/nexus-core';

try {
  const result = await sdk.bridgeAndExecute({
    token: 'USDC',
    amount: 100_000_000n,
    toChainId: 1,
    execute: { to: '0x...', data: '0x...' },
  });
} catch (error) {
  if (error instanceof NexusError) {
    switch (error.code) {
      case ERROR_CODES.INSUFFICIENT_BALANCE:
        console.error('Not enough tokens for bridge + execute');
        break;
        
      case ERROR_CODES.TRANSACTION_REVERTED:
        console.error('Contract execution reverted');
        // Check contract requirements
        break;
        
      case ERROR_CODES.SIMULATION_FAILED:
        console.error('Simulation failed - check parameters');
        break;
        
      case ERROR_CODES.USER_DENIED_ALLOWANCE:
        console.log('User denied token approval');
        break;
        
      default:
        console.error('Operation failed:', error.message);
    }
  }
}

Related

Bridge Operations

Learn about bridging

DeFi Integration

Integrate with DeFi protocols