nexus-elements-transfer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nexus Elements - Transfer

Nexus Elements - Transfer组件

Install

安装

Install widget:

npx shadcn@latest add @nexus-elements/transfer

Ensure
```
NexusProvider
```
is installed and initialized before rendering.

安装组件：

npx shadcn@latest add @nexus-elements/transfer

确保在渲染前已安装并初始化
```
NexusProvider
```
。

Required setup before rendering

渲染前的必要设置

Ensure
```
useNexus().nexusSDK
```
is initialized.
Ensure
```
bridgableBalance
```
has loaded.
Ensure recipient is valid EVM address (prefill or user input).

确保
```
useNexus().nexusSDK
```
已初始化。
确保
```
bridgableBalance
```
已加载完成。
确保接收方地址为有效的EVM地址（可预填或由用户输入）。

Initialize SDK (required once per app)

初始化SDK（每个应用只需执行一次）

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

连接钱包时，解析EIP-1193 provider并调用
```
useNexus().handleInit(provider)
```
。
在允许执行转账操作前，需等待
```
useNexus().nexusSDK
```
初始化完成。
若钱包会话重置，重新连接后需重新执行初始化操作。

Render widget

渲染组件

tsx

"use client";

import FastTransfer from "@/components/transfer/transfer";
import { SUPPORTED_CHAINS } from "@avail-project/nexus-core";

export function TransferPanel() {
  return (
    <FastTransfer
      prefill={{
        token: "USDC",
        chainId: SUPPORTED_CHAINS.BASE,
        recipient: "0x000000000000000000000000000000000000dead",
      }}
      onStart={() => {
        // pending
      }}
      onComplete={() => {
        // success
      }}
      onError={(message) => {
        console.error(message);
      }}
    />
  );
}

tsx

"use client";

import FastTransfer from "@/components/transfer/transfer";
import { SUPPORTED_CHAINS } from "@avail-project/nexus-core";

export function TransferPanel() {
  return (
    <FastTransfer
      prefill={{
        token: "USDC",
        chainId: SUPPORTED_CHAINS.BASE,
        recipient: "0x000000000000000000000000000000000000dead",
      }}
      onStart={() => {
        // pending
      }}
      onComplete={() => {
        // success
      }}
      onError={(message) => {
        console.error(message);
      }}
    />
  );
}

Live prop contract

实时属性约定

```
prefill?
```
:
- ```
token
```
  ,
```
chainId
```
  , optional
```
amount
```
  , optional
```
recipient
```
  .
```
maxAmount?
```
: cap transferable amount.
```
onStart?
```
,
```
onComplete?
```
,
```
onError?(message)
```
callbacks.

```
prefill?
```
:
- 包含
```
token
```
  、
```
chainId
```
  ，可选
```
amount
```
  、可选
```
recipient
```
  。
```
maxAmount?
```
: 限制可转账的最大金额。
```
onStart?
```
,
```
onComplete?
```
,
```
onError?(message)
```
回调函数。

SDK flow details (under the hood)

SDK流程细节（底层实现）

Primary execute call:

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

Pre-execution checks:
- validate recipient + amount
- compute max available via
```
sdk.calculateMaxForBridge(...)
```
- enforce selected-source sufficiency
Hook usage:
- ```
intent.current
```
  for transfer intent preview/refresh/allow
- ```
allowance.current
```
  for source-specific allowance decisions
Event mapping:
- ```
NEXUS_EVENTS.STEPS_LIST
```
  -> initialize step tracker
- ```
NEXUS_EVENTS.STEP_COMPLETE
```
  -> progress update and elapsed timer

核心执行调用：

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

执行前检查：
- 验证接收方地址和金额
- 通过
```
sdk.calculateMaxForBridge(...)
```
  计算最大可用金额
- 确保所选源链的余额充足
Hook使用：
- ```
intent.current
```
  用于转账意向预览/刷新/授权
- ```
allowance.current
```
  用于源链特定的授权决策
事件映射：
- ```
NEXUS_EVENTS.STEPS_LIST
```
  -> 初始化步骤追踪器
- ```
NEXUS_EVENTS.STEP_COMPLETE
```
  -> 更新进度和耗时计时器

Understand recipient behavior

了解接收方相关行为

Transfer flow requires recipient address.
Prefill recipient locks input.
Without prefill, UI validates recipient and blocks invalid addresses.

转账流程需要接收方地址。
预填接收方地址后，输入框将被锁定。
若未预填，UI会验证接收方地址，阻止无效地址的输入。

E2E verification

端到端验证

Fill token/chain/amount/recipient and confirm intent preview appears.
Adjust source chains and confirm coverage indicators update.
Accept and verify allowance step when required.
Confirm success updates explorer URL and refreshes balances.
Confirm history refresh event appears in
```
ViewHistory
```
(when present).

填写代币/链/金额/接收方地址，确认意向预览界面显示。
调整源链设置，确认覆盖指示器更新。
当需要授权步骤时，完成授权并验证。
确认成功后，更新浏览器URL并刷新余额。
确认历史记录刷新事件出现在
```
ViewHistory
```
中（若该组件存在）。

Common failure cases

常见失败场景

Invalid recipient:
- pass a checksummed or valid hex address.
Exceeds selected source max:
- reduce amount or enable more source chains.
Flow canceled:
- expect
```
onError
```
  with user-cancel message and reset state.

无效接收方地址：
- 需传入校验通过的有效十六进制地址。
超过所选源链的最大金额限制：
- 减少转账金额或启用更多源链。
流程被取消：
- 触发
```
onError
```
  回调，返回用户取消的提示信息并重置状态。