SDK TypeScript

​

Installation

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

• Node.js 20+ ou Bun 1.0+ (déclarés dans engines).
• TypeScript 5.x. Le package fournit du CommonJS (lib/index.js), de l’ESM (lib/index.mjs) et les déclarations de types (lib/index.d.ts).
• Support natif de bigint. Tous les montants on-chain sont des bigint.

​

Initialisation

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
  }
})

1. Résout le réseau dans la liste intégrée (mainnet, testnet, devnet) et applique networkOverrides.
2. Crée un NodeProvider et un ExplorerProvider pour ce réseau.
3. Instancie chaque module et charge ses identifiants de contrats depuis les fichiers de déploiement inclus dans le package.
4. Enregistre ses providers comme providers globaux par défaut de @alephium/web3 (setCurrentProviders()), pour que les helpers de contrats générés fonctionnent immédiatement.

​

Les façades de modules

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'

​

Résultats de transaction

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

​

Pièges courants

​

Politique de versions

• Les versions stables sont publiées sur npm sous le nom @alephium/powfi-sdk avec le tag latest. Les release candidates utilisent le tag rc.
• Les bindings de contrats (clmm/, cpmm/, staking/) sont régénérés depuis le dépôt des contrats et inclus dans le package. Une mise à niveau de contrat qui change des adresses ou des ABI est publiée dans une nouvelle version du SDK.
• Figez les versions exactes et lisez les notes de version avant de mettre à jour.

​

Mise à jour

1. Lisez les notes de version sur GitHub.
2. Mettez à jour @alephium/powfi-sdk et vérifiez que votre @alephium/web3 satisfait la dépendance pair du SDK (^3.0.3 aujourd’hui) et qu’une seule copie est installée (npm ls @alephium/web3). Plusieurs copies de @alephium/web3 provoquent des bugs de instanceof et d’enregistrement des providers.
3. Lancez tsc --noEmit. La plupart des changements incompatibles apparaissent comme des erreurs de type.
4. Relancez vos tests de cotation sur le testnet avant de basculer le trafic mainnet.

​

Obtenir de l’aide

• Bugs et demandes de fonctionnalités : issues GitHub.
• Problèmes de sécurité : n’ouvrez pas d’issue publique. Contactez l’équipe Powfi en privé.

​

Liens utiles

• Référence des modules : CPMM · CLMM · Staking · Jetons
• Artefacts de contrats et déploiements
• CLI développeur
• Code source : github.com/alephium/powfi-sdk