> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powfi.alephium.org/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> @alephium/powfi-sdk：安装、初始化、模块门面、交易结果和常见陷阱。

export const VersionBanner = ({network = 'mainnet', products = [], lang = 'en'}) => {
  const SDK_VERSION = '1.0.2';
  const ADDRESSES = {
    mainnet: {
      cpmm: {
        Router: 'ze15rnAwTyVCPnDhN7J8An3SvNeWBsZHAVMeBx1ehXeP',
        TokenPairFactory: '24CXRLvj1QiDH6riwr1EPERG7BcduHKZtktygbq97MfYb'
      },
      clmm: {
        PoolFactory: '24gqd4DMQXVzjm5QDAGxUtYupx3WM2PSu3vZUseuBCV9h',
        PositionManager: 'vFyKSqnJHS9MicrojBcLgztyRFqhS4hB349Ci3LJCELw'
      },
      staking: {
        XAlphToken: '225WevmFp5ZgzPsyVJTvyp2v2uyKrvp329HfrVmzffnWj',
        RewardFeeCollector: '22CE7vG6u64zjjsLZLxeJqQuPDydjPvbP9iG1d861j2G7'
      }
    },
    testnet: {
      cpmm: {
        Router: 'xaueT8kPMvpnaFJEfHv6CJLgqsSPpoNmHjF1QgTxoF9R',
        TokenPairFactory: '29hdd9b9Gp7oXuamwHKfUqBaRXP487HoeTcutS3RhZJEj'
      },
      clmm: {
        PoolFactory: 'z2QFT7qBQrfm8UwAYG3VHWoHs7B56ZDFNdSCcDu5j53m',
        PositionManager: '21p6egW8d6FEyVVuH17WqvHCARsCsD61GcBmeCr75XdGT'
      },
      staking: {
        XAlphToken: '23psDicimC5VdpM56wrgqgCzQzcyXWGCkQGSYWbtZAPRq',
        RewardFeeCollector: '29qQ1LPJ5uqawRviXLVDMeo19JUygRrNNTQy5RUBh817D'
      }
    }
  };
  const EXPLORERS = {
    mainnet: 'https://explorer.alephium.org/addresses/',
    testnet: 'https://testnet.alephium.org/addresses/'
  };
  const LABELS = {
    en: {
      sdk: 'SDK',
      network: 'Network',
      contracts: 'Contracts',
      all: 'All addresses',
      allNetworks: 'mainnet · testnet · devnet',
      devnet: 'Local deployment (addresses vary per devnet)'
    },
    zh: {
      sdk: 'SDK 版本',
      network: '网络',
      contracts: '合约',
      all: '全部地址',
      allNetworks: 'mainnet · testnet · devnet',
      devnet: '本地部署（每个 devnet 的地址不同）'
    },
    fr: {
      sdk: 'SDK',
      network: 'Réseau',
      contracts: 'Contrats',
      all: 'Toutes les adresses',
      allNetworks: 'mainnet · testnet · devnet',
      devnet: 'Déploiement local (adresses propres à chaque devnet)'
    }
  };
  const t = LABELS[lang] ?? LABELS.en;
  const contractsPage = lang === 'en' ? '/reference/contracts' : `/${lang}/reference/contracts`;
  const short = a => `${a.slice(0, 6)}…${a.slice(-4)}`;
  const entries = [];
  const addrs = ADDRESSES[network];
  if (addrs) {
    for (const p of products) {
      for (const [name, address] of Object.entries(addrs[p] ?? ({}))) entries.push({
        name,
        address
      });
    }
  }
  let contractsCell;
  if (network === 'devnet' && products.length > 0) {
    contractsCell = <span>{t.devnet}</span>;
  } else if (entries.length > 0) {
    contractsCell = entries.map(({name, address}, i) => <span key={name}>
        {i > 0 && <span className="mx-1 opacity-50">·</span>}
        {name}{' '}
        <a href={EXPLORERS[network] + address} target="_blank" rel="noreferrer" title={address}>
          <code>{short(address)}</code>
        </a>
      </span>);
  }
  const row = (label, value) => <div className="flex flex-wrap gap-x-2">
      <span className="font-semibold min-w-[5.5rem]">{label}</span>
      <span className="flex-1 min-w-0 break-words">{value}</span>
    </div>;
  return <div className="not-prose mb-6 rounded-xl border border-zinc-950/10 dark:border-white/10 bg-zinc-50 dark:bg-white/5 px-4 py-3 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
      {row(t.sdk, <code>@alephium/powfi-sdk@{SDK_VERSION}</code>)}
      {row(t.network, network === 'all' ? t.allNetworks : network)}
      {contractsCell && row(t.contracts, <span>
            {contractsCell}
            <span className="mx-1 opacity-50">·</span>
            <a href={contractsPage}>{t.all} →</a>
          </span>)}
    </div>;
};

<VersionBanner network="mainnet" products={['cpmm', 'clmm', 'staking']} lang="zh" />

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

## 安装

```bash theme={null}
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`。

## 初始化

```ts theme={null}
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` 是**同步**的。它会：

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

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

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

默认端点以及如何指向自己的节点，见[网络与配置](/zh/concepts/networks)。

## 模块门面

```ts theme={null}
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)
```

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

```ts theme={null}
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、签名器、网络）和一个具名日志器。开启调试输出见[日志](/zh/utilities/math)。

## 交易结果

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

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

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

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

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

## 常见陷阱

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

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

  <Accordion title="3. CLMM 兑换用 token0/token1 表示方向，而不是池顺序">
    在 `ClmmSwapRequest` 中，`token0` 是**输入**代币，`token1` 是**输出**代币。而在 `ClmmSimulateSwapParams` 中，方向由 `zeroForOne` 决定。见[在 CLMM 上兑换](/zh/guides/clmm-swap)。
  </Accordion>

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

  <Accordion title="5. 滑点以基点为单位，且两种池的应用方式不同">
    `slippageBps: 50n` 表示 0.5%。CPMM 把滑点应用在**数量**上（`minimalAmount` / `maximalAmount`），CLMM 把滑点应用在**价格**上（`sqrtPriceLimitX96` 边界）。见[数量与滑点](/zh/concepts/amounts-and-slippage)。
  </Accordion>

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

  <Accordion title="7. CPMM 价格影响上限">
    当报价的价格影响 **≥ 5%**（`MAX_PRICE_IMPACT`）时，`cpmm.swap` 会抛出 `PriceImpactTooHighError`。如果确有需要，请拆分交易，或使用跳过此检查的 `swapTo`。
  </Accordion>
</AccordionGroup>

## 版本策略

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

## 升级

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

## 获取帮助

* **Bug 和功能请求：** [GitHub issues](https://github.com/alephium/powfi-sdk/issues)。
* **安全问题：** 请勿公开提 issue，请私下联系 Powfi 团队。

## 相关链接

* 模块参考：[CPMM](/zh/modules/cpmm) · [CLMM](/zh/modules/clmm) · [质押](/zh/modules/staking) · [代币](/zh/modules/token)
* [合约产物与部署](/zh/reference/contracts)
* [开发者 CLI](/zh/reference/cli)
* 源码：[github.com/alephium/powfi-sdk](https://github.com/alephium/powfi-sdk)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.