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

# SDK TypeScript

> @alephium/powfi-sdk : installation, initialisation, façades de modules, résultats de transaction et pièges courants.

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="fr" />

<Info>
  Cette page cible `@alephium/powfi-sdk@1.0.2`. Figez les versions exactes en production et lisez les notes de version avant de mettre à jour.
</Info>

## Installation

```bash theme={null}
npm install @alephium/powfi-sdk @alephium/web3
```

Prérequis :

* **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`.

`@alephium/web3` est une **dépendance pair** (`^3.0.3`) : installez-la vous-même, comme dans la commande ci-dessus, pour que le SDK et votre application partagent une seule copie. Installées automatiquement : `@alephium/token-list`, `bignumber.js`, `decimal.js`.

## Initialisation

```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` est **synchrone**. Il :

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.

Il n'effectue **aucun** appel réseau. La liste de jetons est récupérée au premier usage et mise en cache pendant un jour.

<Tip>
  De nombreux helpers de contrats générés par `@alephium/web3` utilisent le node provider *global*. `Powfi.load` le définit pour vous, et le dernier `load` l'emporte. Si vous utilisez plusieurs instances du SDK, appelez `powfi.setCurrentProviders()` pour rendre à nouveau globaux les providers d'une instance donnée.
</Tip>

Voir [Réseaux et configuration](/fr/concepts/networks) pour les endpoints par défaut et l'utilisation de votre propre nœud.

## Les façades de modules

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

Des helpers sans état sont exportés à côté des modules :

```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'
```

Chaque module hérite de `ModuleBase`, qui lui donne accès à l'instance `Powfi` parente (`scope` : providers, signataire, réseau) et à un logger nommé. Voir [Journalisation](/fr/utilities/math) pour activer la sortie de débogage.

## Résultats de transaction

Les méthodes d'écriture signent **et soumettent** la transaction via `powfi.signer`. Elles renvoient le type de résultat `@alephium/web3` de l'appel sous-jacent :

| Type de méthode | Type de retour | Champs principaux |
| - | - | - |
| Exécution de script (swap/liquidité CPMM, `createPool` CLMM, opérations de frais du staking) | `ExecuteScriptResult` | `txId`, `unsignedTx`, `signature`, `gasAmount`, `gasPrice` |
| Appel de méthode de contrat (swap/positions CLMM, staking) | `SignExecuteScriptTxResult` | mêmes champs |
| Méthodes qui créent quelque chose | `{ poolId, result }` ou `{ positionId, result }` | l'identifiant dérivé plus le résultat de la transaction |

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

Le SDK n'attend **pas** la confirmation. Interrogez `powfi.nodeProvider.transactions.getTransactionsStatus({ txId })` jusqu'à obtenir `type === 'Confirmed'` (voir l'étape 5 du [Démarrage rapide](/fr/quickstart)).

<Note>
  La plupart des méthodes n'ont pas de mode « construire sans envoyer ». L'exception est l'ajout de liquidité CLMM : `getAddLiquidityParams` renvoie les paramètres d'appel préparés, et `addLiquidityFromParams` les exécute. Pour le reste, si vous avez besoin d'une transaction non signée, appelez directement `.execute` / `.transact` du script ou du contrat sous-jacent avec un `SignerProvider` personnalisé qui capture la requête au lieu de la soumettre.
</Note>

## Pièges courants

<AccordionGroup>
  <Accordion title="1. Réseau incohérent">
    Les identifiants de contrats proviennent du fichier de déploiement de `networkId`. Un signataire mainnet avec `networkId: 'testnet'` (ou l'inverse) construit des transactions vers des contrats qui n'existent pas sur le réseau du signataire. Dérivez toujours `networkId` de la même source que le réseau du wallet.
  </Accordion>

  <Accordion title="2. Ordre des jetons">
    Les pools sont indexés par la paire **triée lexicographiquement** (`token0 < token1`). Les fonctions comme `getPoolId(tokenA, tokenB)` trient pour vous. Les réserves, les prix et `sqrtPriceX96` sont toujours exprimés dans l'ordre trié (prix = token1 par token0). Utilisez `sortTokens(a, b)` chaque fois que vous associez la paire « base/cotation » de l'interface aux champs du pool.
  </Accordion>

  <Accordion title="3. Le swap CLMM utilise token0/token1 pour la direction, pas l'ordre du pool">
    Dans `ClmmSwapRequest`, `token0` est le jeton **d'entrée** et `token1` le jeton **de sortie**. Dans `ClmmSimulateSwapParams`, la direction est donnée par `zeroForOne`. Voir [Swapper sur CLMM](/fr/guides/clmm-swap).
  </Accordion>

  <Accordion title="4. État périmé">
    Une cotation calculée à partir d'un `CpmmPoolContractState` ou d'un `ClmmSimulateSwapQuote` devient obsolète dès qu'un autre trade est exécuté. `cpmm.swap` recharge l'état avant l'envoi. Pour le CLMM, relancez `simulateSwap` juste avant de soumettre et fixez toujours un slippage non nul.
  </Accordion>

  <Accordion title="5. Le slippage est en points de base et s'applique différemment selon le type de pool">
    `slippageBps: 50n` signifie 0,5 %. Le CPMM l'applique aux **montants** (`minimalAmount` / `maximalAmount`). Le CLMM l'applique au **prix** (une borne `sqrtPriceLimitX96`). Voir [Montants et slippage](/fr/concepts/amounts-and-slippage).
  </Accordion>

  <Accordion title="6. Adresses sans groupe">
    Les adresses Alephium sans groupe (sans suffixe `:group`) sont normalisées en interne vers le groupe du protocole pour les arguments owner/recipient. Si vous dérivez vous-même des identifiants (par exemple `clmm.getPositionId`), passez la forme normalisée : `normalizeAddress(address, powfi.clmm.getClmmConfig().groupIndex)`.
  </Accordion>

  <Accordion title="7. Plafond d'impact de prix CPMM">
    `cpmm.swap` lève `PriceImpactTooHighError` lorsque l'impact de prix de la cotation est **≥ 5 %** (`MAX_PRICE_IMPACT`). Découpez le trade, ou utilisez `swapTo` (qui ignore ce contrôle) si c'est vraiment voulu.
  </Accordion>
</AccordionGroup>

## 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](https://github.com/alephium/powfi-sdk/issues).
* **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](/fr/modules/cpmm) · [CLMM](/fr/modules/clmm) · [Staking](/fr/modules/staking) · [Jetons](/fr/modules/token)
* [Artefacts de contrats et déploiements](/fr/reference/contracts)
* [CLI développeur](/fr/reference/cli)
* Code source : [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.