@avail-project/nexus-core

无头 TypeScript SDK 用于跨链互换,同资产桥接,钱包余额和EVM 合同执行。 带回您的钱包连接和用户界面 .

安装和连接

npm install @avail-project/nexus-core

import { createNexusClient, type EthereumProvider } from '@avail-project/nexus-core';
import { formatUnits, parseUnits } from '@avail-project/nexus-core/utils';

const client = createNexusClient({ clientId: 'your-app-name', network: 'mainnet' });
await client.initialize();

// Use the EIP-1193 provider supplied by your wallet connector.
declare const provider: EthereumProvider;
await client.setEVMProvider(provider);

clientId 是需要的、非空的、稳定的应用标识符。 目录查询和准确输入 引用预览需要初始化,但没有钱包。 执行和钱包余额需要连接 供养. 在账户/提供者更改和调用后重建客户端 client.destroy() 关于清理.

mainnet 财务报告和审定财务报表 canary 使用主网链. testnet 仅支持独立执行; 意图 操作和同步意图目录帮助器拒绝 ENVIRONMENT_NOT_SUPPORTED。 。 。 .

选择操作

数额为未加工 bigint 数值。 通过链式ID和合同地址解析令牌,然后使用自己的 小数 parseUnits 编号 : formatUnits。原生地址来自目录元数据. 路线、提供者和收费由引文决定.

发现资产和余额

const chains = client.getSupportedChains();
const swapChains = chains.filter((chain) => chain.capabilities.intent);
const executeChains = chains.filter((chain) => chain.capabilities.execute);

const page = await client.getTokensByChain(8453, { symbol: 'USDC', limit: 25 });
const baseUsdc = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
const destination = { chainId: 8453, tokenAddress: baseUsdc } as const;
const token = await client.getToken(destination);
const amountRaw = parseUnits('10', token.decimals);

const balances = await client.getBalances();
for (const balance of balances) {
  console.log(balance.symbol, formatUnits(balance.usableBalanceRaw, balance.decimals), balance.usable);
}

余额曝光 actualBalanceRaw (完整的钱包余额)和 usableBalanceRaw (备有 天然气储备后的路由)作为 bigint。 。 。 . balanceRaw 是一个已贬值的别名,其名称是: usableBalanceRaw。 。 。 . valueUsd 值为可用余额,且为 null 当没有价格时.

接受按键查询 chainId, (中文(简体) ), providers, (中文(简体) ), name, (中文(简体) ), symbol, (中文(简体) ), contract, (中文(简体) ), includeUnverified, (中文(简体) ), offset,以及 limit与AND结合的过滤器。 默认抵消0并限制50页;上限 限制为1000。 调试页面默认已验证资产; 选择使用 includeUnverified: true。 。 。 . 精确的搜索可以解决未验证的符. 平衡包括两者;尊重 verified 财务报告和审定财务报表 usable。 。 。 .

提前标注 page.offset + page.limit ,而这个小于 page.total兼容性 页面在过滤前计算候选人,所以空页并不意味着没有后期匹配. 当过滤器或选择器改变时重置偏移 。 保留显示页面以外的选择; 返回的符号使用 address选择 tokenAddress. 复制供应商集团 通过链式ID加地址.

对于精确输入的采取者,将现有来源传递至 getAvailableSourceTokens 所以所有选择 共享一个提供者。 确切产出来源是替代品:用途 getAvailableSourceTokens(destination, [], query)。 。 。 . confirmRouteExists 需要共享提供者 并且不能保证引言 查找失败与空页分开拒绝 .

路由限制接受 sources, (中文(简体) ), destinations, (中文(简体) ), providers,以及 valueUsd。腿部接受 chainId?, (中文(简体) ), tokenAddress?,以及 amountRaw?;金额需要两个身份字段。 用同样的 字段,最多一个缩放模式:源数、目的地数、, 或美元价值。 数量必须是非负数。 Token 查询不会继承路由限制 .

交换

精确输出指定要接收什么 。 奥米 sources (或通过) []自动钱包资金; 明确来源限制了符合资格的链条和标志. toNativeAmountRaw 可选请求 目的地是天然气的本土资金.

const result = await client.swapWithExactOut({
  toChainId: destination.chainId,
  toTokenAddress: destination.tokenAddress,
  toAmountRaw: amountRaw,
  sources: [{ chainId: 1, tokenAddress: '0xA0b86991c6218b36c1d19d4a2e9eb0cE3606eB48' }],
});
console.log(result.intentId, result.intentExplorerUrl);

精确输入指定了每个源的正生量. 所有来源和目的地必须 共享一个提供者.

const source = {
  chainId: 1,
  tokenAddress: '0xA0b86991c6218b36c1d19d4a2e9eb0cE3606eB48',
} as const;
const sourceToken = await client.getToken(source);
await client.swapWithExactIn({
  sources: [{ ...source, amountRaw: parseUnits('5', sourceToken.decimals) }],
  toChainId: destination.chainId,
  toTokenAddress: destination.tokenAddress,
});

引用和预览率

过 options.hooks.onIntent 以显示确认 UI 。 行动等待 allow() 或者说 deny();单从回调返回不接受. 没有钩子,引文被接受 自动。 ERC-20批准使用最低要求的金额;钱包也可能提示 批准签名和源交易.

import type { IntentHookData, SwapOperationOptions } from '@avail-project/nexus-core';

declare function showReview(hook: IntentHookData): void;
const options: SwapOperationOptions = {
  hooks: { onIntent: showReview },
  slippageBps: 50,
  fillTimeoutMinutes: 2,
  pollingIntervalMs: 2000,
};

过 options 作为交换方法的第二个参数。 这些是默认的选项值 . 剪贴页接受从 0 到 10 000 的整数或 'auto'。UI使用的审查 hook.quote, (中文(简体) ), hook.execution, (中文(简体) ), hook.allow(), (中文(简体) ), hook.deny(),以及 await hook.refresh(sources?)。 。 。 . 刷新返回完整替换引号; 使返回值读取 hook.execution 再来一次 在允许前等待更新。 精确输入的替换源仍必须携带符号 地址和原始金额。 引文在验收后被固定.

引文曝光 input, (中文(简体) ), output, (中文(简体) ), output.minAmountRaw, (中文(简体) ), fees, (中文(简体) ), allowances, (中文(简体) ), plan, (中文(简体) ), sourceVerdicts,以及 expiresAt (Unix秒). 期末金额 Raw 为: bigint· ; 美元引号数额是小数字符串. quote.isExecutable (一) 来源平衡检查; quote.executionWarnings 说明任何不足.

swapWithExactIn 可以在钱包连接前预览费率。 它的钩子暴露:

type QuoteExecution =
  | { possible: true }
  | { possible: false; cause: 'not-connected' | 'insufficient-balance' };

在整个操作中,预览仍然不连续。 连接后, 启动新的互换呼叫 并审查它的新引文. allow() 以断开的预览拒绝 WALLET_NOT_CONNECTED· ; deny() 拒绝作为用户拒绝。 没有成功的预览结果 。 没有钩子,引文 事件被释放,呼叫被拒绝。 如果缺少源批准气体,预览报价也可能失败. 余额不足的已连接引文无法执行; 为钱包提供资金并刷新 . 精确输出和复合操作需要钱包.

进展和成果

options.onEvent 接收 IntentEvent数字 :

• quote:当前引文和计划.
• step数字 : step, (中文(简体) ), state (单位:千美元)started, (中文(简体) ), completed,或 failed, (中文(简体) ), committed选择 errorDetails。 。 。 .
• status数字 : intentId, (中文(简体) ), status (单位:千美元)created, (中文(简体) ), deposited, (中文(简体) ), fulfilled,或 expired, (中文(简体) ), substatus源代码 legs 有交易链接和错误.

import type { IntentEvent } from '@avail-project/nexus-core';

const onEvent = (event: IntentEvent): void => {
  switch (event.type) {
    case 'quote':
      console.log('Quote updated', event.quote.output, event.quote.fees, event.quote.plan.steps);
      break;
    case 'step':
      console.log('Step progress', event.step.type, event.state);
      if (event.state === 'failed') {
        console.error(event.errorDetails?.message, event.errorDetails?.code);
        // A committed attempt may still settle; check its status before retrying.
        console.log('Intent committed', event.committed);
      }
      break;
    case 'status':
      console.log('Intent status', event.intentId, event.status, event.substatus);
      for (const leg of event.legs) {
        console.log('Source progress', leg.sourceIndex, leg.status, leg.txExplorerUrl, leg.error);
      }
      break;
  }
};

const swapOptions: SwapOperationOptions = { ...options, onEvent };

过 swapOptions 作为交换方法的第二个参数。 将日志替换为您的 应用程序进度 UI;下面的错误示例使用这些相同的选项.

计划步骤类型 erc20_approval, (中文(简体) ), source_approval_signature, (中文(简体) ), intent_signature, (中文(简体) ), native_transaction, (中文(简体) ), intent_submission,以及 intent_fulfillment。事件召回失败 不中断操作。 使用 errorDetails 而不是堕落的一步 error 绳子.

实现后交换承诺 IntentResult数字 : intentId, (中文(简体) ), intentExplorerUrl, (中文(简体) ), quote, (中文(简体) ), status, (中文(简体) ), approvals, (中文(简体) ), nativeTransactions选择 attemptId音轨 attemptId 并行 intentId 请求支持。 被拒绝的允诺可跟随已经提交的交易.

执行合同呼叫

import type { ExecuteParams } from '@avail-project/nexus-core';

declare const contract: ExecuteParams['to'];
declare const calldata: ExecuteParams['data'];
const executeParams: ExecuteParams = {
  toChainId: destination.chainId,
  to: contract,
  data: calldata,
  value: 0n,
  tokenApproval: {
    toTokenAddress: destination.tokenAddress,
    amount: amountRaw,
    spender: contract,
  },
};
const estimate = await client.simulateExecute(executeParams);
const executed = await client.execute(executeParams);
console.log(estimate.estimatedGasUnits, executed.execute.txExplorerUrl);

奥米 tokenApproval 当不需要时; 使用本地语汇 value. 需要模拟 钱包,并估计批准气体。 执行返回 execute选项 approval, (中文(简体) ), 财务报告和审定财务报表 chainId默认情况下,它等待收据; waitForReceipt: false 播放后返回. 收款控制为 receiptTimeout (毫秒,默认为30万)和 requiredConfirmations (默认一). 提交的交易在只播出结果后仍会失败.

供资和执行

swapAndExecute 默认为 tradeType: 'exactOutput': 指定 toAmountRaw和SDK基金 当所选余额已经覆盖执行时,目标缺口或跳过交换.

const composed = await client.swapAndExecute(
  {
    tradeType: 'exactOutput', // Optional; this is the default.
    toChainId: destination.chainId,
    toTokenAddress: destination.tokenAddress,
    toAmountRaw: amountRaw,
    execute: {
      to: contract,
      data: calldata,
      gas: 350_000n,
      tokenApproval: executeParams.tokenApproval,
    },
  },
  {
    hooks: {
      onIntent({ intent, allow }) {
        console.log(intent.executeRequirement, intent.available, intent.shortfall);
        allow(); // In an app, call after the user confirms.
      },
    },
  },
);
console.log(composed.swapSkipped, composed.executeAmountRaw);
if (composed.executionMode === 'wallet') console.log(composed.execute.txExplorerUrl);
if (!composed.swapSkipped) console.log(composed.swapResult.intentExplorerUrl);

提供正数 execute.gas 估计与你的合同电话有关 SDK账户 执行气体和价值,为目的地短缺提供资金,然后在完成后执行. 复合钩子收到 intent没有 quote;即使资金已经足够,它也能运作. intent.quote 仅在 intent.swapRequired 这是真的.

准确输入, 设置 tradeType: 'exactInput',提供正数 amountRaw 每个来源,和 删除 toAmountRaw。匹配目的链和令牌的来源留在钱包中,并且是 预留执行。 其他来源以固定金额输入互换,必须共享一个 提供方与目的地。 如果每个来源已经是目的地标志,则互换被跳过; ERC -20的处决仍需要 本地天然气资金在这个链.

declare function buildDepositData(amountRaw: bigint): NonNullable<ExecuteParams['data']>;

await client.swapAndExecute(
  {
    tradeType: 'exactInput',
    sources: [{ ...source, amountRaw: parseUnits('5', sourceToken.decimals) }],
    toChainId: destination.chainId,
    toTokenAddress: destination.tokenAddress,
    execute: {
      to: contract,
      data: calldata,
      gas: 350_000n,
      tokenApproval: {
        toTokenAddress: destination.tokenAddress,
        amount: 0n, // The SDK sets the final approval amount after funding.
        spender: contract,
      },
    },
  },
  {
    hooks: {
      onIntent({ intent, allow }) {
        console.log(intent.executeRequirement.token.amountRaw, intent.quote?.output);
        allow(); // In an app, call after the user confirms.
      },
    },
    beforeExecute: async ({ receivedAmountRaw, executeAmountRaw }) => {
      console.log('Actual swap proceeds', receivedAmountRaw);
      return { data: buildDepositData(executeAmountRaw) };
    },
  },
);

评论钩显示一个基于引文最小输出加上所选取的本地符号的估计. 经审查后,SDK在供资和 完成之后再次出现. beforeExecute 接收 BeforeExecuteContext数字 :

• receivedAmountRaw: 各种资金的平衡差额, 或当互换被跳过时为零.
• executeAmountRaw: 准确输入时, 实际收益加上选定的本地符号, 仅次于本地 执行储备; 确切产出,请 toAmountRaw。 。 。 .

例如,从10个目的地开始的钱包 USDT 并选择其中的5个用于执行 5个本地人 如果资金将余额提高到140美元,则钩子获得130美元的收益 135美元用于执行,使未选取的5美元未受影响.

余额差异包括供资期间不相关的转账。 缺少当地资金, 未实现余额读取、非正值互换收益或当地执行储备不足 执行。 原生产出储备执行值和气体;非原生产出请求减少气体 需要的时候。 何时 tokenApproval.toTokenAddress 匹配精确输入目的地 SDK 储存批准气体,然后重新检查备抵,建立批准 executeAmountRaw 之后 钩子回来了 开发者提供更新的调用数据;批准建造留在SDK. 当每个输入都是当地输入时,金额已经知道,所以足够的津贴可以避免预留 不需要的批准气体.

复合 refresh(sources?) 返回当前收费估计数和替换的更新意向 必要时援引资金。 它重用原有的平衡快照; 开始新的操作来重读 余额。 外出来源保留选择。 对于准确的输出, [] 清除; 准确输入 替换源必须是非空的,并包括符号地址和正原始数量. 顶级 beforeExecute 能够返回 { data?, value?, gas? } 在供资后,但取消 重新计算资金. 使用 executeAmountRaw 通过这个钩子编写对量敏感的调用数据。 忽略的召回 情况仍然得到支持. 意向性活动包括供资;综合承诺也包括随后的合同呼吁.

提供方目的地执行

设定 useProviderDestinationExecution: true 打开 swapAndExecute 要求Relay批准和 执行目的呼叫. swapWithExactIn 财务报告和审定财务报表 swapWithExactOut 仍为普通互换. 重用 execute.to, (中文(简体) ), execute.data, (中文(简体) ), execute.value,以及 execute.tokenApproval; SDK 编码 执行通知前的批准。 目的地合同必须支持代表 因为它的呼叫器是Relay的路由器.

const deposited = await client.swapAndExecute(
  {
    tradeType: 'exactInput',
    sources: [{ ...source, amountRaw: parseUnits('5', sourceToken.decimals) }],
    toChainId: destination.chainId,
    toTokenAddress: destination.tokenAddress,
    execute: {
      to: contract,
      gas: 350_000n,
      tokenApproval: { toTokenAddress: destination.tokenAddress, amount: 0n, spender: contract },
    },
  },
  {
    useProviderDestinationExecution: true,
    beforeExecute: async ({ executeAmountRaw }) => ({ data: buildDepositData(executeAmountRaw) }),
    hooks: {
      onIntent({ intent, allow }) {
        console.log(intent.executionMode, intent.executeRequirement.token.amountRaw, intent.quote);
        allow(); // In an app, call after the user confirms.
      },
    },
  },
);
if (deposited.executionMode === 'provider') {
  console.log(deposited.executeAmountRaw, deposited.swapResult.intentExplorerUrl);
  // No wallet execution transaction: deposited.execute and deposited.approval are undefined.
}

使用此选项省略或 false,上面描述的钱包流仍然是默认的。 用这个 设置为 true,一个不支持的路由在签名前拒绝,并且永远不会回到钱包执行中. 中间的软件 quote.supportsDestinationCalls 旗帜决定来自资助分支的支持 实际被选中:允许多个候选人,但只有一个链条/托起的腿可以资助路线. 被选中的多条腿,或者没有旗帜的更老的中间软件,拒绝.

提供执行人通过引文为整个电话提供资金。 现有目标钱包余额 不得在保证金中减去或默示增加。 匹配目的地的精确输入源 链/托肯输入引文作为明确的源输入。 SDK从不花额外的钱包 实现后的迹象。 只能批准输出符; 必须出现本地执行值 符合当地产出,并符合引用的执行预算。 ERC-20 输出为本地调用值 不支持提供者模式.

精确输出引用请求 toAmountRaw 没有钱包执行气体。 首先精确输入 预览中继引用,然后将执行金额固定在保证最小值以下。 预备队 等于该最低值的1%(四舍五入为原始单位),按照报价的美元估价,上限为一美元 (四舍入生单位. 无价产出,或产出太小,不能表示正储备 与执行金额,拒绝。 这种储备与互换滑行是分开的.

在提供者模式下, beforeExecute 运行 审议前 准备编码的呼叫,并再次 在每一个新鲜. receivedAmountRaw 是预览的保证最小值(请求的金额) (a) 准确产出,非计量收益; executeAmountRaw 是固定的执行预算. 将后者用于对量敏感的调用数据或本地数据 value。回调只应准备 呼叫,必须安全地重复。 SDK引用这些电话 并拒绝低于 签名前已编码预算 。 更新新电话、预算和最后引文; 失败的刷新保留了先前的意图.

综合审查显示 executionMode: 'provider',固定存款,零钱包气体 ; 报价中包括供应商执行费用。 源批准和意图 签名可能需要钱包提示 。 完成提供者执行,剩余 输出到接收者。 结果暴露了 executeAmountRaw 财务报告和审定财务报表 swapResult,没有 编造 execute 或者说 approval 交易。 在钱包模式下, executeAmountRaw 实际 执行分配和现有交易结果仍然有效.

历史和错误

const history = await client.listIntents({ page: 1, status: 'fulfilled' });
console.log(history.intents, history.total);

所有 SDK 错误扩展 NexusError 并携带 category, (中文(简体) ), code, (中文(简体) ), context选择 details。 。 。 . 使用 UserActionError 拒绝和 ERROR_CODES 用于具体的追回行动. getIntentQuoteFailure(error) 提取结构化路线、数量、余额、批准气体和价格 诊断。 处理代码而不是解析信件文本 。 见 引用错误。 。 。 .

中间软件报告特定数量或目标失败, 当所有无法运行源时 说吧 这些失败 retryable: false; 在重试前更改请求。 来源判决 可包含 DESTINATION_NOT_SERVED。没有每个供应商支持的目的地仍然随行 不支持符号处理 .

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

try {
  const swap = await client.swapWithExactOut(
    {
      toChainId: destination.chainId,
      toTokenAddress: destination.tokenAddress,
      toAmountRaw: amountRaw,
    },
    swapOptions,
  );
  console.log('Fulfilled', swap.intentExplorerUrl);
} catch (error) {
  if (error instanceof UserActionError) {
    console.info('Action declined', error.code);
  } else if (error instanceof NexusError) {
    switch (error.code) {
      case ERROR_CODES.WALLET_NOT_CONNECTED:
        console.info('Connect a wallet, then request a fresh quote.');
        break;
      case ERROR_CODES.BACKEND_INSUFFICIENT_BALANCE:
        console.info('Fund the wallet or choose different source assets.');
        break;
      case ERROR_CODES.BACKEND_INSUFFICIENT_APPROVAL_GAS:
        console.info('Add native gas funds on the source chain or choose another source.');
        break;
      default:
        console.error(error.message, error.code, error.context);
    }

    const failure = getIntentQuoteFailure(error);
    if (failure) console.log('Quote diagnostics', failure.subcode, failure.sourceVerdicts);
    if (error.details?.approvals) console.log('Broadcast approvals', error.details.approvals);
  } else {
    throw error;
  }
}

使用信件更新您的 UI 并保留错误代码/ context 支持 。 事件处理器 显示进展; 行动的承诺 仍然必须抓住 处理最后的失败.

承诺后超时或连接失败后, 请检查历史、 探索者、 已知 重试前交易散列。 意图还可能实现。 批准失败可能暴露 error.details.approvals 与 confirmed, (中文(简体) ), reverted,或 unconfirmed 各州。 一个未经证实的 交易仍可确认;在启动另一个操作时使用新引号.

产品分析可以禁用 analytics: { enabled: false } 在客户端配置中. 诊断日志是单独配置的;参见 遥测参考。 。 。 .

移动已存在的集成

使用基于地址的互换来删除 bridge 编号 : bridgeAndTransfer 方法及方法 swapAndExecute 页:1 bridgeAndExecute。没有接收者覆盖或独立交换模拟方法; 使用引号校正 onIntent。 。 。 . getBalancesForSwap 是一个已贬值的别名,其名称是: getBalances。 。 。 .

删除本地最大/ 路由帮助器、 安全和电平键配置, onAllowance旧的 桥梁/游泳计划活动。 使用 options.hooks, (中文(简体) ), IntentQuote, (中文(简体) ), IntentEvent,以及 IntentResult。 。 。 . 可用功能来自 @avail-project/nexus-core/utils 财务报告和审定财务报表 client.utils。 。 。 .