TypeScript SDK

本页基于 @alephium/powfi-sdk@1.0.2。生产环境请锁定精确版本，并在升级前阅读发布说明。

安装

npm install @alephium/powfi-sdk @alephium/web3

工具链要求：

Node.js 20+ 或 Bun 1.0+（在 engines 中声明）。
TypeScript 5.x。包内提供 CommonJS（lib/index.js）、ESM（lib/index.mjs）和类型声明（lib/index.d.ts）。
原生 bigint 支持。所有链上数量都是 bigint。

@alephium/web3 是对等依赖（^3.0.3）：请像上面的命令那样自行安装，让 SDK 和你的应用共用同一份。会自动安装的依赖：@alephium/token-list、bignumber.js、decimal.js。

初始化

import { Powfi } from '@alephium/powfi-sdk'

const powfi = Powfi.load({
  networkId: 'mainnet', // 'mainnet' | 'testnet' | 'devnet'
  signer, // optional: any @alephium/web3 SignerProvider
  networkOverrides: {
    // optional: override any field of the built-in network config
    nodeUrl: 'https://my-node.example.com',
    nodeApiKey: process.env.NODE_API_KEY
  }
})

Powfi.load 是同步的。它会：

从内置列表（mainnet、testnet、devnet）中找到网络配置，并应用 networkOverrides。
为该网络创建 NodeProvider 和 ExplorerProvider。
实例化每个模块，并从包内打包的部署文件中加载合约 ID。
把它的 provider 注册为全局 @alephium/web3 默认值（setCurrentProviders()），生成的合约辅助方法可直接使用。

它不会发起任何网络请求。代币列表在首次使用时才获取，并缓存一天。

@alephium/web3 生成的许多合约辅助方法使用全局 node provider。Powfi.load 会自动设置它，以最后一次 load 为准。如果同时运行多个 SDK 实例，请调用 powfi.setCurrentProviders()，把指定实例的 provider 重新设为全局默认值。

默认端点以及如何指向自己的节点，见网络与配置。

模块门面

powfi.cpmm    // CpmmModule: constant-product pools. Pool state, quotes, swap, add/remove liquidity, create pool
powfi.clmm    // ClmmModule: concentrated liquidity. Fee tiers, pool state, simulateSwap, swap, positions, rewards
powfi.staking // StakingModule: xALPH liquid staking. Stake, unstake, claim, fee-collector vaults
powfi.token   // TokenModule: token metadata from the Alephium token list (cached)

无状态的辅助工具与模块一起导出：

import {
  CpmmModule,          // static quote helpers: computeSwapAmount, computeLiquidityAmounts, ...
  TickUtils,           // tick <-> sqrtPriceX96 <-> price
  ClmmLiquidityUtils,  // liquidity <-> token amounts
  PoolUtils,           // position IDs, offline swap simulation
  MathUtil,            // bigint math (sqrt, mulDiv with rounding)
  NumericUtils,        // bigint/Decimal/string conversion and decimal scaling
  sortTokens,          // canonical token ordering used for pool IDs
} from '@alephium/powfi-sdk'

每个模块都继承自 ModuleBase，可以访问父级 Powfi 实例（scope：provider、签名器、网络）和一个具名日志器。开启调试输出见日志。

交易结果

写入类方法会通过 powfi.signer 签署并提交交易，返回底层调用对应的 @alephium/web3 结果类型：

方法类型	返回类型	主要字段
脚本执行（CPMM 兑换/流动性、CLMM `createPool`、质押费用操作）	`ExecuteScriptResult`	`txId`、`unsignedTx`、`signature`、`gasAmount`、`gasPrice`
合约方法调用（CLMM 兑换/头寸、质押）	`SignExecuteScriptTxResult`	同上
会创建新对象的方法	`{ poolId, result }` 或 `{ positionId, result }`	推导出的 ID 加交易结果

const { positionId, result } = await powfi.clmm.addLiquidity({ /* ... */ })
console.log(positionId, result.txId)

SDK 不会等待交易确认。请轮询 powfi.nodeProvider.transactions.getTransactionsStatus({ txId })，直到 type === 'Confirmed'（见快速开始第 5 步）。

大多数方法没有”只构建不发送”的模式。例外是 CLMM 添加流动性：getAddLiquidityParams 返回准备好的调用参数，addLiquidityFromParams 再执行它们。对于其他方法，如果需要未签名交易，请直接调用底层脚本或合约的 .execute / .transact，并传入一个自定义 SignerProvider，由它截获请求而不是提交。

常见陷阱

1. 网络不匹配

合约 ID 来自 networkId 对应的部署文件。用主网签名器配合 networkId: 'testnet'（或反过来），会针对签名器所在网络上不存在的合约构建交易。请始终让 networkId 与钱包的网络来自同一个来源。

2. 代币排序

池以按字典序排序的代币对（token0 < token1）作为键。getPoolId(tokenA, tokenB) 之类的方法会自动排序。储备量、价格和 sqrtPriceX96 始终按排序后的顺序表示（价格 = 每个 token0 值多少 token1）。把界面上的”基础/报价”代币映射到池字段时，请使用 sortTokens(a, b)。

3. CLMM 兑换用 token0/token1 表示方向，而不是池顺序

在 ClmmSwapRequest 中，token0 是输入代币，token1 是输出代币。而在 ClmmSimulateSwapParams 中，方向由 zeroForOne 决定。见在 CLMM 上兑换。

4. 状态过期

基于 CpmmPoolContractState 或 ClmmSimulateSwapQuote 计算的报价，只要有另一笔交易上链就会过期。cpmm.swap 会在发送前重新获取状态。对于 CLMM，请在提交前重新运行 simulateSwap，并始终设置非零滑点。

5. 滑点以基点为单位，且两种池的应用方式不同

slippageBps: 50n 表示 0.5%。CPMM 把滑点应用在数量上（minimalAmount / maximalAmount），CLMM 把滑点应用在价格上（sqrtPriceLimitX96 边界）。见数量与滑点。

6. 无分组地址

Alephium 的无分组地址（没有 :group 后缀）作为 owner/recipient 参数时，SDK 内部会将其规范化到协议所在分组。如果你自己推导 ID（例如 clmm.getPositionId），请传入规范化后的形式：normalizeAddress(address, powfi.clmm.getClmmConfig().groupIndex)。

7. CPMM 价格影响上限

当报价的价格影响 ≥ 5%（MAX_PRICE_IMPACT）时，cpmm.swap 会抛出 PriceImpactTooHighError。如果确有需要，请拆分交易，或使用跳过此检查的 swapTo。

版本策略

正式版以 @alephium/powfi-sdk 的名称发布在 npm 的 latest 标签下，候选版本使用 rc 标签。
合约绑定（clmm/、cpmm/、staking/）从合约仓库重新生成，并打包在 SDK 中。改变地址或 ABI 的合约升级会作为新的 SDK 版本发布。
请锁定精确版本，并在升级前阅读发布说明。

升级

阅读 GitHub 上的发布说明。
升级 @alephium/powfi-sdk，并确保你的 @alephium/web3 满足 SDK 的对等依赖（目前是 ^3.0.3），且只安装了一份（npm ls @alephium/web3）。存在多份 @alephium/web3 会导致 instanceof 和 provider 注册相关的问题。
运行 tsc --noEmit。大多数破坏性变更会以类型错误的形式出现。
在把主网流量切换过去之前，先在测试网上重跑你的报价测试。

获取帮助

Bug 和功能请求： GitHub issues。
安全问题： 请勿公开提 issue，请私下联系 Powfi 团队。

SDK 与 API

核心概念

模块

工具类

指南

参考

安装

初始化

模块门面

交易结果

常见陷阱

版本策略

升级

获取帮助

相关链接

​安装

​初始化

​模块门面

​交易结果

​常见陷阱

​版本策略

​升级

​获取帮助

​相关链接

安装

初始化

模块门面

交易结果

常见陷阱

版本策略

升级

获取帮助

相关链接