从 v3 迁移到 v4

概览

LI.FI SDK v4 引入了基于客户端的架构，提供了更好的类型安全性、改进的模块化和更清晰的关注点分离。SDK 现在使用客户端实例模式而不是全局配置，使得管理多个 SDK 实例更容易，并提高了可测试性。要开始使用，请安装最新版本的 LI.FI SDK。

yarn add @lifi/sdk

pnpm add @lifi/sdk

bun add @lifi/sdk

npm install @lifi/sdk

配置

v4 中最重大的变更是从全局配置模式转向基于客户端的架构。您现在无需调用 createConfig() 和使用全局函数，而是创建一个客户端实例并将其传递给所有 SDK 函数。

之前（v3）

// SDK v3
import { createConfig, getQuote, ChainId } from '@lifi/sdk';

createConfig({
  integrator: 'Your dApp/company name',
});

const quote = await getQuote({
  fromAddress: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  fromChain: ChainId.ARB,
  toChain: ChainId.OPT,
  fromToken: '0x0000000000000000000000000000000000000000',
  toToken: '0x0000000000000000000000000000000000000000',
  fromAmount: '1000000000000000000',
});

之后（v4）

// SDK v4
import { createClient, getQuote, ChainId } from '@lifi/sdk';

const client = createClient({
  integrator: 'Your dApp/company name',
});

const quote = await getQuote(client, {
  fromAddress: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  fromChain: ChainId.ARB,
  toChain: ChainId.OPT,
  fromToken: '0x0000000000000000000000000000000000000000',
  toToken: '0x0000000000000000000000000000000000000000',
  fromAmount: '1000000000000000000',
});

函数签名

所有 SDK 操作函数现在都需要将客户端作为第一个参数。这包括：

getRoutes(client, {...})
getQuote(client, {...})
getContractCallsQuote(client, {...})
getChains(client, {...})
getTools(client, {...})
getConnections(client, {...})
getTokens(client, {...})
getToken(client, chain, token)
getTokenBalance(client, walletAddress, token)
getTokenBalances(client, walletAddress, tokens)
getTokenBalancesByChain(client, walletAddress, tokensByChain)
getWalletBalances(client, walletAddress)
getStatus(client, {...})
getStepTransaction(client, step)
executeRoute(client, route, options)
resumeRoute(client, route, options)
getGasRecommendation(client, {...})
getTransactionHistory(client, {...})
getNameServiceAddress(client, name, chainType?)
getRelayerQuote(client, {...})
relayTransaction(client, {...})
getRelayedTransactionStatus(client, {...})
patchContractCalls(client, {...})

迁移示例

之前（v3）

// SDK v3
import { getRoutes, executeRoute } from '@lifi/sdk';

const result = await getRoutes({
  fromChainId: 42161,
  toChainId: 10,
  fromTokenAddress: '0x...',
  toTokenAddress: '0x...',
  fromAmount: '10000000',
});

const executedRoute = await executeRoute(result.routes[0], {
  updateRouteHook(route) {
    console.log(route);
  },
});

之后（v4）

// SDK v4
import { createClient, getRoutes, executeRoute } from '@lifi/sdk';

const client = createClient({
  integrator: 'Your dApp/company name',
});

const result = await getRoutes(client, {
  fromChainId: 42161,
  toChainId: 10,
  fromTokenAddress: '0x...',
  toTokenAddress: '0x...',
  fromAmount: '10000000',
});

const executedRoute = await executeRoute(client, result.routes[0], {
  updateRouteHook(route) {
    console.log(route);
  },
});

提供者包

在 v4 中，生态系统提供者已被移至单独的包中，以获得更好的模块化和 tree-shaking。您需要单独安装提供者包，并从各自的包中导入提供者。

安装提供者包

yarn add @lifi/sdk-provider-ethereum @lifi/sdk-provider-solana @lifi/sdk-provider-bitcoin @lifi/sdk-provider-sui @lifi/sdk-provider-tron

pnpm add @lifi/sdk-provider-ethereum @lifi/sdk-provider-solana @lifi/sdk-provider-bitcoin @lifi/sdk-provider-sui @lifi/sdk-provider-tron

npm install @lifi/sdk-provider-ethereum @lifi/sdk-provider-solana @lifi/sdk-provider-bitcoin @lifi/sdk-provider-sui @lifi/sdk-provider-tron

bun add @lifi/sdk-provider-ethereum @lifi/sdk-provider-solana @lifi/sdk-provider-bitcoin @lifi/sdk-provider-sui @lifi/sdk-provider-tron

仅安装您所需生态系统的提供者包。例如，如果您只支持 EVM 链，则只需要 @lifi/sdk-provider-ethereum。

提供者配置

之前（v3）

// SDK v3
import { createConfig, EVM, Solana } from '@lifi/sdk';

createConfig({
  integrator: 'Your dApp/company name',
  providers: [
    EVM({
      getWalletClient: () => Promise.resolve(walletClient),
    }),
    Solana({
      getWalletAdapter: () => Promise.resolve(walletAdapter),
    }),
  ],
});

之后（v4）

// SDK v4
import { createClient } from '@lifi/sdk';
import { EthereumProvider } from '@lifi/sdk-provider-ethereum';
import { SolanaProvider } from '@lifi/sdk-provider-solana';

const client = createClient({
  integrator: 'Your dApp/company name',
});

client.setProviders([
  EthereumProvider({
    getWalletClient: () => Promise.resolve(walletClient),
  }),
  SolanaProvider({
    getWallet: () => Promise.resolve(wallet), // wallet-standard Wallet
  }),
]);

提供者名称

提供者工厂名称已更新，使其更具描述性：

EVM → EthereumProvider（来自 @lifi/sdk-provider-ethereum）
Solana → SolanaProvider（来自 @lifi/sdk-provider-solana）
UTXO → BitcoinProvider（来自 @lifi/sdk-provider-bitcoin）
Sui → SuiProvider（来自 @lifi/sdk-provider-sui）
新增: TronProvider（来自 @lifi/sdk-provider-tron）—— 添加了 Tron 生态系统支持

Solana 提供者：`getWalletAdapter` → `getWallet`

Solana 提供者现在使用 @solana/kit 和 Wallet Standard，而不是 @solana/web3.js 和旧版钱包适配器。

之前（v3）

// SDK v3
import { Solana } from '@lifi/sdk';

Solana({
  getWalletAdapter: () => Promise.resolve(walletAdapter),
});

之后（v4）

// SDK v4
import { SolanaProvider } from '@lifi/sdk-provider-solana';

SolanaProvider({
  getWallet: () => Promise.resolve(wallet), // wallet-standard Wallet
});

Sui 提供者：`getWallet` → `getClient` + `getSigner`

Sui 提供者现在使用 @mysten/sui v2，并需要 ClientWithCoreApi 和 Signer 而不是钱包对象。

之前（v3）

// SDK v3
import { Sui } from '@lifi/sdk';

Sui({
  getWallet: () => Promise.resolve(wallet),
});

之后（v4）

// SDK v4
import { SuiProvider } from '@lifi/sdk-provider-sui';

SuiProvider({
  getClient: () => Promise.resolve(suiClient),
  getSigner: () => Promise.resolve(signer),
});

配置管理

之前（v3）

// SDK v3
import { config } from '@lifi/sdk';

// Update configuration
config.set({
  integrator: 'Updated name',
});

// Set providers
config.setProviders([...]);

// Get chains
const chains = await config.getChains();

之后（v4）

// SDK v4
import { createClient } from '@lifi/sdk';

const client = createClient({
  integrator: 'Your dApp/company name',
});

// Access configuration (read-only)
console.log(client.config.integrator);

// Set providers
client.setProviders([...]);

// Get chains
const chains = await client.getChains();

// Get specific chain
const chain = await client.getChainById(1);

// Get RPC URLs
const rpcUrls = await client.getRpcUrls();

执行模型：Process → Action

执行跟踪模型已重命名以求清晰。之前称为 “process” 的现在称为 “action”。

类型和字段重命名

Execution.process → Execution.actions
Process → ExecutionAction
ProcessType → ExecutionActionType
getProcessMessage() → getActionMessage() + getSubstatusMessage()

新的 action 类型

TOKEN_ALLOWANCE process 类型已被拆分为更细粒度的 action 类型：

CHECK_ALLOWANCE - 检查代币授权额度
RESET_ALLOWANCE - 重置代币授权额度
SET_ALLOWANCE - 设置代币授权额度

此外，还添加了 NATIVE_PERMIT action 类型。

之前（v3）

// SDK v3
step.execution?.process.forEach((process) => {
  if (process.txHash) {
    console.log(process.type, process.txHash);
  }
});

之后（v4）

// SDK v4
import { getActionMessage } from '@lifi/sdk';

step.execution?.actions.forEach((action) => {
  if (action.txHash) {
    console.log(action.type, action.txHash);
  }
  const message = getActionMessage(action.type, action.status);
  console.log(message);
});

ExecutionOptions 变更

switchChainHook 和 disableMessageSigning 选项已从 ExecutionOptions 中移除，并移至 EthereumProviderOptions，该选项在设置 EVM 提供者时配置。请注意，switchChainHook 在提供者上已重命名为 switchChain（如下例所示）。

之前（v3）

// SDK v3
executeRoute(route, {
  switchChainHook: async (chainId) => { ... },
  disableMessageSigning: true,
});

之后（v4）

// SDK v4
import { EthereumProvider } from '@lifi/sdk-provider-ethereum';

client.setProviders([
  EthereumProvider({
    getWalletClient: () => Promise.resolve(walletClient),
    switchChain: async (chainId) => { ... },
    disableMessageSigning: true,
  }),
]);

executeRoute(client, route, {
  // switchChainHook and disableMessageSigning are no longer here
});

代币授权额度函数

代币授权额度函数现在从 Ethereum 提供者包导出，而不是主 SDK 包。

之前（v3）

// SDK v3
import { getTokenAllowance, setTokenAllowance } from '@lifi/sdk';

const allowance = await getTokenAllowance(token, ownerAddress, spenderAddress);
const txHash = await setTokenAllowance(approvalRequest);

之后（v4）

// SDK v4
import { createClient } from '@lifi/sdk';
import { getTokenAllowance, setTokenAllowance } from '@lifi/sdk-provider-ethereum';

const client = createClient({
  integrator: 'Your dApp/company name',
});

const allowance = await getTokenAllowance(client, token, ownerAddress, spenderAddress);
const txHash = await setTokenAllowance(client, approvalRequest);

`actions()` 辅助函数

如果您希望在每次调用 SDK 函数时无需将客户端作为第一个参数传递，可以使用 actions() 辅助函数。它返回一个对象，其中包含所有预绑定到客户端的 SDK 操作函数。

// SDK v4
import { createClient, actions } from '@lifi/sdk';

const client = createClient({
  integrator: 'Your dApp/company name',
});

const api = actions(client);

// No need to pass client as the first parameter
const quote = await api.getQuote({
  fromChain: 42161,
  toChain: 10,
  fromToken: '0x...',
  toToken: '0x...',
  fromAmount: '10000000',
  fromAddress: '0x...',
});

新的实用工具

v4 从 @lifi/sdk 导出常用实用工具，因此您不再需要 viem 或其他库进行基本格式化：

import { formatUnits, parseUnits } from '@lifi/sdk';

// Format token amount for display
const formatted = formatUnits(1000000n, 6); // "1"

// Parse user input to token amount
const amount = parseUnits("1", 6); // 1000000n

移除的参数

一些配置参数已被移除或更改：

chains - 不再传递给 createClient。链将自动从 API 获取。

客户端实例模式

客户端实例模式允许您：

创建多个客户端，使用不同的配置
更好的可测试性 - 更容易 mock 和测试
类型安全 - 更好的 TypeScript 支持
显式依赖 - 明确函数依赖于什么

示例：多个客户端

// SDK v4 - Multiple clients
import { createClient } from '@lifi/sdk';

const mainnetClient = createClient({
  integrator: 'MyApp',
  apiUrl: 'https://li.quest/v1',
});

const testnetClient = createClient({
  integrator: 'MyApp',
  apiUrl: 'https://staging.li.quest/v1',
});

// Use different clients for different environments
const mainnetRoutes = await getRoutes(mainnetClient, {...});
const testnetRoutes = await getRoutes(testnetClient, {...});

迁移清单

更新包安装以包含提供者包
将 createConfig() 替换为 createClient() 并存储客户端实例
更新所有函数调用以将 client 作为第一个参数包含（或使用 actions() 辅助函数）
更新提供者导入以使用单独的提供者包
更新提供者工厂名称（EVM → EthereumProvider 等）
对于 Solana：将 getWalletAdapter 替换为 getWallet（返回 wallet-standard Wallet）
对于 Sui：将 getWallet 替换为 getClient + getSigner
将 switchChainHook（重命名为 switchChain）和 disableMessageSigning 从 ExecutionOptions 移至 EthereumProviderOptions
更新执行监控代码：execution.process → execution.actions
将 getProcessMessage() 替换为 getActionMessage() 和 getSubstatusMessage()
将代币授权额度函数导入更新为 @lifi/sdk-provider-ethereum
更新代币授权额度函数调用以包含 client 参数
将 config.set() 和 config.getChains() 替换为客户端方法
移除对全局 config 对象的任何引用
如果需要，将 viem 的 formatUnits/parseUnits 替换为 @lifi/sdk 导出

示例

请查看我们在 SDK 仓库中的完整示例，如果您遇到任何问题，请随时提交 issue。

更新日志

有关所有更改的详细视图，请参阅 CHANGELOG。

​概览

​配置

​之前（v3）

​之后（v4）

​函数签名

​迁移示例

​之前（v3）

​之后（v4）

​提供者包

​安装提供者包

​提供者配置

​之前（v3）

​之后（v4）

​提供者名称

​Solana 提供者：getWalletAdapter → getWallet

​之前（v3）

​之后（v4）

​Sui 提供者：getWallet → getClient + getSigner

​之前（v3）

​之后（v4）

​配置管理

​之前（v3）

​之后（v4）

​执行模型：Process → Action

​类型和字段重命名

​新的 action 类型

​之前（v3）

​之后（v4）

​ExecutionOptions 变更

​之前（v3）

​之后（v4）

​代币授权额度函数

​之前（v3）

​之后（v4）

​actions() 辅助函数

​新的实用工具

​移除的参数

​客户端实例模式

​示例：多个客户端

​迁移清单

​示例

​更新日志

概览

配置

之前（v3）

之后（v4）

函数签名

迁移示例

之前（v3）

之后（v4）

提供者包

安装提供者包

提供者配置

之前（v3）

之后（v4）

提供者名称

Solana 提供者：`getWalletAdapter` → `getWallet`

之前（v3）

之后（v4）

Sui 提供者：`getWallet` → `getClient` + `getSigner`

之前（v3）

之后（v4）

配置管理

之前（v3）

之后（v4）

执行模型：Process → Action

类型和字段重命名

新的 action 类型

之前（v3）

之后（v4）

ExecutionOptions 变更

之前（v3）

之后（v4）

代币授权额度函数

之前（v3）

之后（v4）

`actions()` 辅助函数

新的实用工具

移除的参数

客户端实例模式

示例：多个客户端

迁移清单

示例

更新日志