> ## 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.

# 数学、数值与辅助函数

> MathUtil、NumericUtils、代币排序、地址规范化和日志。

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={[]} lang="zh" />

## MathUtil

```ts theme={null}
import { MathUtil } from '@alephium/powfi-sdk'
```

带显式取整方式的 bigint 数学，与 Alephium 的整数语义一致。

| 方法 | 说明 |
| - | - |
| `MathUtil.sqrt(x)` | 整数平方根（向下取整），牛顿法 |
| `MathUtil.alphDiv(a, b)` | 向 −∞ 取整的除法（链上对有符号值的约定） |
| `MathUtil.alphCeil(a, b)` | 远离零取整的除法 |
| `MathUtil.divFloor(a, b)` / `divCeil(a, b)` | 向下 / 向上取整除法。`b = 0` 时抛出错误。 |
| `MathUtil.mulDivFloor(a, b, d)` / `mulDivCeil(a, b, d)` | 按给定取整方式计算 `a × b / d`。`d = 0` 时抛出错误。 |
| `MathUtil.abs(x)` | bigint 的绝对值 |

<Note>
  原生 bigint 的 `/` 向零截断。对负数来说这与合约不同。复现带符号数量的链上数学时，请使用 `alphDiv`。
</Note>

## NumericUtils

```ts theme={null}
import { NumericUtils, type NumericLike } from '@alephium/powfi-sdk'
// NumericLike = Decimal | bigint | number | string | undefined | null
```

| 方法 | 示例 |
| - | - |
| `decimalFrom(value)` | `decimalFrom(10n)` → `Decimal(10)`（空值 → 0） |
| `scaleDecimal(value, decimals)` | `scaleDecimal(1500000n, 6)` → `Decimal(1.5)` |
| `scaleToString(value, decimals)` | `scaleToString(1500000n, 6)` → `"1.5"` |
| `numericToString(value)` | 普通字符串，从不使用科学计数法 |
| `decimalToString(decimal)` | 同上，输入为 `Decimal` |
| `numericToBigInt(value)` | `"42"` → `42n`。非整数或非有限值时抛出错误。 |

## 代币排序

```ts theme={null}
import { sortTokens } from '@alephium/powfi-sdk'

const [token0, token1] = sortTokens(tokenA, tokenB) // lexicographic, as the contracts derive pool IDs
```

## 地址规范化

```ts theme={null}
import { normalizeAddress } from '@alephium/powfi-sdk'

normalizeAddress('1Abc…', 0) // '1Abc…:0' for a groupless address, unchanged otherwise
```

## 集成方手续费校验

```ts theme={null}
import { validateIntegratorFee } from '@alephium/powfi-sdk'

validateIntegratorFee({ fee, feeRecipient, sender, tokenInId, amountIn }) // returns the fee (0n when unset) or throws
```

校验规则见[集成方手续费](/zh/guides/integrator-fees)。

## 日志

每个模块都通过一个具名日志器输出日志（`CpmmModule`、`ClmmModule`、`StakingModule`、`TokenModule`）。默认级别是 `Error`。

```ts theme={null}
import { setLoggerLevel, LogLevel } from '@alephium/powfi-sdk'

setLoggerLevel('ClmmModule', LogLevel.Debug) // Error | Warning | Info | Debug
```

`setLoggerLevel` 在 `Powfi.load` 之前或之后调用都有效。模块名区分大小写，名称拼错时不会有任何效果，也不会报错。

你也可以用 `createLogger(name)` 创建自己的日志器，它返回一个带有 `error`、`warning`、`info` 和 `debug` 方法的 `Logger`。


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