Hooks and Events

Set up hooks once after SDK init

• •Call sdk.setOnIntentHook(callback).
• •Call sdk.setOnAllowanceHook(callback).
• •Call sdk.setOnSwapIntentHook(callback).
• •If a hook is not set, the SDK auto-approves and continues.
• •If a hook is set, always call allow(...) or deny() or the flow will stall.
• •Optionally auto-deny after a timeout to avoid hanging UX.

Handle intent hook (bridge / bridgeAndTransfer / bridgeAndExecute)

Signature

sdk.setOnIntentHook((data) => {
  // data: OnIntentHookData
});

OnIntentHookData

• •allow(): void — continue the flow
• •deny(): void — reject the flow
• •intent: ReadableIntent — readable intent info for UI
• •refresh(selectedSources?: number[]): Promise<ReadableIntent> — refresh the intent

How to use

• •Store data in a ref so UI can call allow()/deny() later.
• •Call refresh() on an interval (e.g., every 15s) if you show intent details.
• •If the user closes the modal or cancels, call deny() and clear the ref.

Handle allowance hook (approval control)

Signature

sdk.setOnAllowanceHook((data) => {
  // data: OnAllowanceHookData
});

OnAllowanceHookData

• •allow(decisions): void
  • •decisions must match the number of sources
  • •each entry can be 'min', 'max', bigint, or numeric string
• •deny(): void
• •sources: AllowanceHookSources
  • •includes chain/token info and current vs required allowance

How to use

• •Present each source to the user (chain + token + required allowance).
• •Build the decisions array in the same order as sources.
• •Call allow(decisions) to continue, or deny() to cancel.
• •Ensure decisions.length === sources.length or the SDK will reject with INVALID_VALUES_ALLOWANCE_HOOK.

Handle swap intent hook (swap flows)

Signature

sdk.setOnSwapIntentHook((data) => {
  // data: OnSwapIntentHookData
});

OnSwapIntentHookData

• •allow(): void
• •deny(): void
• •intent: SwapIntent
• •refresh(): Promise<SwapIntent>

How to use

• •Store data and show a UI summary.
• •Call allow() to proceed or deny() to cancel.

Stream events for progress UI

Attach listeners

• •All main operations accept { onEvent } in options.

Event names and payloads

• •NEXUS_EVENTS.STEPS_LIST → BridgeStepType[]
• •NEXUS_EVENTS.STEP_COMPLETE → BridgeStepType
• •NEXUS_EVENTS.SWAP_STEP_COMPLETE → SwapStepType

Typical usage

• •Use STEPS_LIST to seed step trackers.
• •Use STEP_COMPLETE and SWAP_STEP_COMPLETE to update progress and explorer links.

Handle errors and cancellation

• •If an operation throws, clear intent/allowance refs to avoid stale state.
• •On user cancel, call deny() for the active hook and reset UI state.
• •If a hook is set but no allow()/deny() is called, the intent remains pending.

Expand error-handling patterns

Normalize errors

• •The SDK throws NexusError for known failures.
• •Import from SDK:
  • •import { NexusError, ERROR_CODES } from '@avail-project/nexus-core'

Map common error codes to UX responses

• •USER_DENIED_INTENT / USER_DENIED_ALLOWANCE / USER_DENIED_INTENT_SIGNATURE:
  • •Treat as user cancel; show a neutral message and reset UI.
• •INVALID_VALUES_ALLOWANCE_HOOK:
  • •Fix decisions length/type and resubmit.
• •SDK_NOT_INITIALIZED / WALLET_NOT_CONNECTED / CONNECT_ACCOUNT_FAILED:
  • •Prompt user to reconnect; re-run sdk.initialize(...).
• •INVALID_INPUT / INVALID_ADDRESS_LENGTH:
  • •Validate inputs; block submission until fixed.
• •INSUFFICIENT_BALANCE / NO_BALANCE_FOR_ADDRESS:
  • •Prompt user to reduce amount or fund source chain.
• •TOKEN_NOT_SUPPORTED / CHAIN_NOT_FOUND:
  • •Block submission and update selectors.
• •QUOTE_FAILED / SWAP_FAILED / RATES_CHANGED_BEYOND_TOLERANCE / SLIPPAGE_EXCEEDED_ALLOWANCE:
  • •Re-run quote or suggest a smaller amount.
• •RFF_FEE_EXPIRED:
  • •Re-simulate and re-submit the transaction.
• •TRANSACTION_TIMEOUT / LIQUIDITY_TIMEOUT:
  • •Show “pending” state and allow retry or check intent history.
• •TRANSACTION_REVERTED:
  • •Display failure with explorer link if available.
• •COSMOS_ERROR / INTERNAL_ERROR:
  • •Show a generic error and log err.data?.details for support.

Use a helper pattern

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

export function getReadableNexusError(err: unknown): string {
  if (err instanceof NexusError) {
    switch (err.code) {
      case ERROR_CODES.USER_DENIED_INTENT:
      case ERROR_CODES.USER_DENIED_ALLOWANCE:
      case ERROR_CODES.USER_DENIED_INTENT_SIGNATURE:
        return 'Transaction cancelled by user';
      case ERROR_CODES.INSUFFICIENT_BALANCE:
        return 'Insufficient balance';
      case ERROR_CODES.SLIPPAGE_EXCEEDED_ALLOWANCE:
      case ERROR_CODES.RATES_CHANGED_BEYOND_TOLERANCE:
        return 'Price changed too much. Please try again.';
      case ERROR_CODES.TRANSACTION_TIMEOUT:
        return 'Transaction timed out. Please retry.';
      default:
        return err.message;
    }
  }
  if (err instanceof Error) return err.message;
  return 'Unknown error';
}

Clean up on error

• •Clear intent/allowance refs and reset progress state:
  • •intentRef.current = null; allowanceRef.current = null; swapIntentRef.current = null;
  • •reset step UI and pending flags