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
Execute operation parameters
Contract address to execute
Encoded function call data
Native token value to send (in wei)
Gas limit for the transaction
gasPrice
'low' | 'medium' | 'high'
Gas price strategy
Token approval before execution
Spender address (usually the contract)
Wait for transaction receipt before returning
Receipt wait timeout in milliseconds
Required block confirmations
Returns
Chain ID where execution occurred
Transaction receipt (if waitForReceipt was true)
Gas used by the transaction
Token approval transaction hash (if approval was needed)
Example
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
Same parameters as execute() method
Returns
Estimated gas units required
Current gas price (in wei)
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
Amount to bridge (in smallest unit)
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
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
Execute transaction explorer URL
Indicates if bridge was skipped due to sufficient balance
Token approval transaction hash (if approval was needed)
Bridge explorer URL (undefined if bridge was skipped)
Intent details (undefined if bridge was skipped)
Example
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
Bridge simulation (null if bridge not needed due to sufficient balance)
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);
}
}
}
Bridge Operations
Learn about bridging
DeFi Integration
Integrate with DeFi protocols