nexus-elements-fast-bridge（Nexus 元素快速桥）

Nexus Elements - Fast Bridge

Install

• Install widget:

- npx shadcn@latest add @nexus-elements/fast-bridge

• Ensure NexusProvider is installed and initialized on wallet connect before rendering FastBridge.

Required setup before rendering

• Ensure useNexus().nexusSDK is non-null.
• Ensure bridgableBalance has loaded.
• Pass connected wallet address as connectedAddress.

Initialize SDK (required once per app)

• On wallet connect, resolve an EIP-1193 provider and call useNexus().handleInit(provider).
• Wait for useNexus().nexusSDK before allowing bridge actions.
• Re-run init after reconnect if wallet session resets.

Render widget

"use client";

import FastBridge from "@/components/fast-bridge/fast-bridge";
import { SUPPORTED_CHAINS } from "@avail-project/nexus-core";

export function BridgePanel({ address }: { address: `0x${string}` }) {
  return (
    <FastBridge
      connectedAddress={address}
      prefill={{
        token: "USDC",
        chainId: SUPPORTED_CHAINS.BASE,
      }}
      onStart={() => {
        // track pending state
      }}
      onComplete={() => {
        // show success state
      }}
      onError={(message) => {
        console.error(message);
      }}
    />
  );
}

Live prop contract

• connectedAddress (required): connected wallet address.
• prefill?:

- token, chainId, optional amount, optional recipient.

• maxAmount?: cap bridgeable amount.
• onStart?, onComplete?, onError?(message) callbacks.

SDK flow details (under the hood)

• Primary execute call:

- sdk.bridge({token, amount, toChainId, recipient, sourceChains}, {onEvent})

• Pre-execution validation and limits:

- input validation (token/chain/recipient/amount) - sdk.calculateMaxForBridge(...) for selected sources - source coverage checks before allow/execute

• Hook usage:

- intent.current stores OnIntentHookData - allowance.current stores OnAllowanceHookData - flow calls intent.refresh(selectedSources) before accept

• Event mapping:

- NEXUS_EVENTS.STEPS_LIST seeds progress steps - NEXUS_EVENTS.STEP_COMPLETE updates step completion and timer start

Understand source selection behavior

• Widget computes available sources from token breakdown excluding destination chain.
• Widget tracks selected source chains and coverage against required amount.
• Widget blocks accept/execute when source coverage is insufficient.

E2E verification

• Enter valid amount/recipient and confirm preview appears (intent hook received).
• Toggle sources and confirm max amount and coverage update.
• Accept flow and confirm allowance modal appears only when needed.
• Confirm transaction progresses through steps and returns explorer URL.
• Confirm balances refresh after success.

Common failure cases

• Nexus SDK not initialized:

- confirm handleInit(provider) ran.

• Source coverage errors:

- increase amount coverage or add more source chains.

• Stuck preview:

- ensure allow() or deny() is called from hook-driven UI.