nexus-sdk-bridge-flows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bridge and Execute Flows

桥接与执行工作流

Call bridge(params, options?)

调用 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
```

用于跨链转移代币（基于意图的桥接）。
签名：
- ```
sdk.bridge(params, { onEvent? })
```
参数（
```
BridgeParams
```
）：
- ```
token: string
```
  — 代币符号（例如："ETH"、"USDC"）
- ```
amount: bigint
```
  — 最小单位数量
- ```
toChainId: number
```
  — 目标链ID
- ```
recipient?: Hex
```
  — 默认为当前连接的用户地址
- ```
gas?: bigint
```
  — 可选，要在目标链支付的原生 gas
- ```
sourceChains?: number[]
```
  — 限制可选的源链

返回结果（

BridgeResult

）：

```
explorerUrl: string
```

sourceTxs: { chain, hash, explorerUrl }[]

```
intent: ReadableIntent
```

Call bridgeAndTransfer(params, options?)

调用 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
```

用于桥接代币并转账到指定接收方地址。

签名：

sdk.bridgeAndTransfer(params, { onEvent? })

参数（

TransferParams

）：

```
token: string
```
```
amount: bigint
```
```
toChainId: number
```
```
recipient: Hex
```
```
sourceChains?: number[]
```

返回结果（

TransferResult

）：

```
transactionHash: string
```
```
explorerUrl: string
```

Call bridgeAndExecute(params, options?)

调用 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
```

用于（如有需要）桥接代币后执行合约调用。

签名：

sdk.bridgeAndExecute(params, { onEvent?, beforeExecute? })

参数（

BridgeAndExecuteParams

）：

token: string

amount: bigint

toChainId: number

execute: Omit<ExecuteParams, "toChainId">

可选参数：
```
waitForReceipt
```
、
```
requiredConfirmations
```
、超时配置

beforeExecute

钩子（可选）：

beforeExecute?: () => Promise<{ value?: bigint; data?: Hex; gas?: bigint }>

用于在发送请求前动态覆盖执行 payload

返回结果（

BridgeAndExecuteResult

）：

```
executeTransactionHash: string
```
```
executeExplorerUrl: string
```
```
bridgeExplorerUrl?: string
```
（跳过桥接时为 undefined）
```
bridgeSkipped: boolean
```
```
intent?: ReadableIntent
```

Call execute(params, options?)

调用 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

用于在单链上独立执行合约调用。
签名：
- ```
sdk.execute(params, { onEvent? })
```

参数（

ExecuteParams

）：

```
toChainId: number
```
```
to: Hex
```
（合约地址）
```
data?: Hex
```
```
value?: bigint
```
```
gas?: bigint
```
（可选，为保证行为确定性建议填写）
```
gasPrice?: 'low' | 'medium' | 'high'
```

可选回执配置：

waitForReceipt

、

receiptTimeout

、

requiredConfirmations

可选参数

tokenApproval?: { token: string; amount: bigint; spender: Hex }

返回结果（

ExecuteResult

）：

```
transactionHash
```
、
```
explorerUrl
```
、
```
chainId
```
可选回执字段

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.

调用

sdk.simulateBridge(params)

→ 返回

SimulationResult

。

调用

sdk.simulateBridgeAndTransfer(params)

→ 返回

BridgeAndExecuteSimulationResult

。

调用

sdk.simulateBridgeAndExecute(params)

→ 返回

BridgeAndExecuteSimulationResult

。

使用模拟功能可在执行前展示手续费与 gas 消耗。

若跳过桥接，

BridgeAndExecuteSimulationResult.bridgeSimulation

将返回

null

。

Compute max bridgeable amount

计算最大可桥接金额

Call

sdk.calculateMaxForBridge({ token, toChainId, recipient?, sourceChains? })

Use
```
BridgeMaxResult
```
to set “max” or validate input.

调用

sdk.calculateMaxForBridge({ token, toChainId, recipient?, sourceChains? })

。

可使用返回的
```
BridgeMaxResult
```
填充「最大」按钮或校验用户输入。

Convert amounts to bigint

转换金额为 bigint 格式

Use

sdk.convertTokenReadableAmountToBigInt(amountString, tokenSymbol, chainId)

Or use
```
sdk.utils.parseUnits(value, decimals)
```
if decimals are known.

使用

sdk.convertTokenReadableAmountToBigInt(amountString, tokenSymbol, chainId)

。

若已知小数位数，也可使用
```
sdk.utils.parseUnits(value, decimals)
```
。

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.

调用桥接工作流前挂载意图与授权钩子。

使用

NEXUS_EVENTS.STEPS_LIST

和

NEXUS_EVENTS.STEP_COMPLETE

实现进度 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.

抛出错误时，清空意图/授权引用并重置 UI 状态。
用户取消操作时，调用活跃钩子的
```
deny()
```
方法并中止流程。