nexus-sdk-bridge-flows

name	nexus-sdk-bridge-flows
description	Implement bridge, bridgeAndTransfer, bridgeAndExecute, and execute flows with Nexus SDK. Use when wiring cross-chain bridge and execution operations, simulations, or max-amount checks.

Bridge and Execute Flows

Call bridge(params, options?)

• Use to move tokens cross-chain (intent-based bridge).
• Signature:
  • sdk.bridge(params, { onEvent? })
• Params (BridgeParams):
  • token: string — token symbol (e.g., "ETH", "USDC")
  • amount: bigint — smallest units
  • toChainId: number — destination chain id
  • recipient?: Hex — defaults to connected user address
  • gas?: bigint — optional native gas to deliver on destination
  • sourceChains?: number[] — restrict source chains
• Result (BridgeResult):
  • explorerUrl: string
  • sourceTxs: { chain, hash, explorerUrl }[]
  • intent: ReadableIntent

Call bridgeAndTransfer(params, options?)

• Use to bridge and transfer to a recipient address.
• Signature:
  • sdk.bridgeAndTransfer(params, { onEvent? })
• Params (TransferParams):
  • token: string
  • amount: bigint
  • toChainId: number
  • recipient: Hex
  • sourceChains?: number[]
• Result (TransferResult):
  • transactionHash: string
  • explorerUrl: string

Call bridgeAndExecute(params, options?)

• Use to bridge (if needed) and then execute a contract call.
• Signature:
  • sdk.bridgeAndExecute(params, { onEvent?, beforeExecute? })
• Params (BridgeAndExecuteParams):
  • token: string, amount: bigint, toChainId: number
  • execute: Omit<ExecuteParams, "toChainId">
  • Optional: waitForReceipt, requiredConfirmations, timeouts
• beforeExecute hook (optional):
  • beforeExecute?: () => Promise<{ value?: bigint; data?: Hex; gas?: bigint }>
  • Use to dynamically override execute payload before sending.
• Result (BridgeAndExecuteResult):
  • executeTransactionHash: string
  • executeExplorerUrl: string
  • bridgeExplorerUrl?: string (undefined if bridge skipped)
  • bridgeSkipped: boolean
  • intent?: ReadableIntent

Call execute(params, options?)

• Use for a standalone contract call on a chain.
• Signature:
  • sdk.execute(params, { onEvent? })
• Params (ExecuteParams):
  • toChainId: number
  • to: Hex (contract address)
  • data?: Hex
  • value?: bigint
  • gas?: bigint (optional but recommended for deterministic behavior)
  • gasPrice?: 'low' | 'medium' | 'high'
  • Optional receipt config: waitForReceipt, receiptTimeout, requiredConfirmations
  • Optional tokenApproval?: { token: string; amount: bigint; spender: Hex }
• Result (ExecuteResult):
  • transactionHash, explorerUrl, chainId
  • optional receipt fields

Use simulation helpers

• Call sdk.simulateBridge(params) → SimulationResult.
• Call sdk.simulateBridgeAndTransfer(params) → BridgeAndExecuteSimulationResult.
• Call sdk.simulateBridgeAndExecute(params) → BridgeAndExecuteSimulationResult.
• Use simulation to show fees and gas before execution.
• Expect BridgeAndExecuteSimulationResult.bridgeSimulation to be null if bridge is skipped.

Compute max bridgeable amount

• Call sdk.calculateMaxForBridge({ token, toChainId, recipient?, sourceChains? }).
• Use BridgeMaxResult to set “max” or validate input.

Convert amounts to bigint

• Use sdk.convertTokenReadableAmountToBigInt(amountString, tokenSymbol, chainId).
• Or use sdk.utils.parseUnits(value, decimals) if decimals are known.

Attach hooks and events

• Attach intent and allowance hooks before calling bridge flows.
• Use NEXUS_EVENTS.STEPS_LIST and NEXUS_EVENTS.STEP_COMPLETE for progress UI.

Handle common failures

• On throw, clear intent/allowance refs and reset UI state.
• On user cancel, call deny() on the active hook and abort.