CLMM

powfi.clmm // ClmmModule

CLMM pools are Uniswap V3-style: liquidity providers choose a price range (tickLower–tickUpper) and earn fees only while the price is inside it. Each pool is identified by a token pair plus a fee tier (configIndex). Prices are stored as sqrtPriceX96 = sqrt(token1/token0) × 2^96.

Guide: swap on CLMM

Guide: open & manage a position

Fee tiers (pool configs)

A fee tier is a PoolConfig contract registered in the factory, indexed from 0n. Every pool references exactly one.

interface ClmmPoolConfig {
  configIndex: bigint
  tickSpacing: bigint  // positions' ticks must be multiples of this
  tradingFee: bigint   // pips (MAX_PIPS = 1_000_000n): 3000n = 0.3%
  protocolFee: bigint  // protocol share of trading fees
}

Method	Returns
`getAllPoolConfigs()`	`Promise<ClmmPoolConfig[]>`: every tier (cached per index)
`getPoolConfig(configIndex)`	`Promise<ClmmPoolConfig \| undefined>`: `undefined` if the index doesn’t exist
`getPoolConfigId(configIndex)`	Contract ID of the tier’s `PoolConfig`

Pool lookups

Method	Returns
`getPoolId(tokenA, tokenB, configIndex)`	Pool contract ID (tokens sorted internally)
`getPoolAddress(tokenA, tokenB, configIndex)`	Pool address
`getPool(tokenA, tokenB, configIndex)`	Typed `PoolInstance` for direct contract calls
`poolExists(tokenA, tokenB, configIndex)`	`Promise<boolean>`
`findBestRoute(tokenA, tokenB)`	`Promise<bigint>`: the `configIndex` whose pool has the most active liquidity. Throws `PoolNotFoundError` if none exist.

`getPoolState(poolId)`

getPoolState(poolId: string): Promise<ClmmPoolContractState>

object

Hide fields

string

TokenInfo

Sorted pair metadata (both must be in the token list).

bigint

Current price. Convert with TickUtils.sqrtPriceX96ToPrice.

bigint

Current tick.

bigint

Active in-range liquidity.

bigint

Fee-tier fields.

Throws PoolNotFoundError if the pool doesn’t exist.

Method	Returns
`getPoolTokenBalances(poolId)`	`{ token0Balance, token1Balance }`: actual token balances held by the pool contract
`getPoolProtocolFees(poolId)`	`{ token0, token1 }`: uncollected protocol fees
`getPoolRewardState(poolId)`	`{ token2Info?, rewardInfos: { amount, openTime, endTime }[] }`: farming reward programs. `token2` is the pool’s extra reward token. `token2Info` is `undefined` for pools without one.

Swaps

`simulateSwap(params)`

simulateSwap(p: ClmmSimulateSwapParams): Promise<ClmmSimulateSwapQuote>

Runs the pool’s simulateSwap view method on the node (no transaction) and returns the liquidity curve the swap walks through. Feed the result to PoolUtils.offlineSwap to compute the output amount locally.

bigint

required

string

required

The pool’s tokens (any order, used to locate the pool).

boolean

required

true sells sorted token0 for token1 (price goes down).

bigint

required

Positive = exact-in, negative = exact-out.

string

Multi-hop path from buildSwapPath (optional).

string[]

Addresses of extra pools touched by a multi-hop path.

object

Hide fields

bigint

Reference sqrt price at a tick boundary found opposite the swap direction, used to anchor the offline liquidity curve.

bigint

Pool sqrt price at the start of the simulated swap.

bigint

Active in-range liquidity at the start of the simulated swap.

bigint

Trading fee in pips.

{ sqrtPriceX96, liquidity }[]

Price and liquidity recorded at LP range boundaries, tick-search group edges, and the final point reached by the simulation.

`swap(params)`

swap(p: ClmmSwapRequest): Promise<SignExecuteScriptTxResult>

Executes a single-pool swap through the SwapWithoutAccount script (or SwapWithoutAccountWithFee when an integrator fee is set). The signer is both payer and recipient.

string

required

The input token (not necessarily the pool’s sorted token0).

string

required

The output token.

bigint

required

Amount specified: positive = exact-in, negative = exact-out (the negated desired output).

bigint

required

How much input token to attach. Exact-in: same as amount. Exact-out: your maximum input (simulate, then add slippage).

bigint

required

Basis points, converted to a sqrtPriceLimitX96.

bigint[]

required

Fee tiers to route through. Only routePlan[0] is used today.

bigint / string

Optional integrator fee, in the input token.

swap() always sends an empty multi-hop path, so it swaps in one pool only. For multi-hop, build the path with buildSwapPath and call the SwapWithoutAccount script from ClmmScripts directly.

`swapTo(params)`

swapTo(p: ClmmSwapToRequest): Promise<SignExecuteScriptTxResult>
// { tokenIn, tokenOut, configIndex, targetSqrtPriceX96, amountInMax }

Swaps until the pool reaches targetSqrtPriceX96, spending at most amountInMax of tokenIn. Fails on-chain (error code 106, InvalidSqrtPriceLimit) if the target is on the wrong side of the current price.

`buildSwapPath(tokenId, configIndex)`

Encodes one extra hop for simulateSwap({ data }): tokenId + configIndex as 4 hex characters.

Liquidity positions

A position is identified by pool + owner + tickLower + tickUpper. The position contract ID doubles as a position token ID. The owner holds one unit of it, and it is attached when modifying the position.

`getPositionId(poolId, owner, tickLower, tickUpper)`

Derives the position ID offline. Pass owner in normalized form for groupless addresses (see Groups and addresses). PoolUtils.getPositionId(poolAddress, owner, ...) normalizes for you.

`createPool(...)`

createPool(
  configIndex: bigint,
  token0: string, token1: string,
  tick: bigint,                    // initial price as a tick
  amount0: bigint, amount1: bigint,
  tickLower: bigint, tickUpper: bigint,
  dustAmount?: bigint
): Promise<{ poolId: string; result: ExecuteScriptResult }>

Creates a pool at price tick and mints the first position in [tickLower, tickUpper]. Tokens, their amounts, and the ticks are sorted internally. Attaches 6 × MINIMAL_CONTRACT_DEPOSIT ALPH for the new contracts.

`addLiquidity(params)`

addLiquidity(p: ClmmAddLiquidityRequest): Promise<{ positionId: string; result: SignExecuteScriptTxResult }>

string

required

Pool tokens. Pass them sorted (sortTokens) and match amount0 / amount1 to that order.

bigint

required

bigint

required

Multiples of the tier’s tickSpacing. Use TickUtils.getAlignedTick.

bigint

required

Desired amounts. The contract deposits the maximal balanced amounts up to these.

bigint

required

Basis points on price. Minimum amounts are derived from the price bounds.

string

Position owner. Defaults to the signer.

boolean

Set true when adding to a position you already own (attaches the position token). The signer must hold its position NFT, which the SDK attaches automatically.

The position’s deposit (dustAmount) is read on-chain via PositionManager.getSqrtPricesX96. Two-step variant: getAddLiquidityParams(p) returns [positionId, positionManager, params] without sending, and addLiquidityFromParams(positionId, positionManager, params) executes them. Use this to show a confirmation screen with the exact minimum amounts.

`removeLiquidity(params)`

removeLiquidity(p: ClmmRemoveLiquidityRequest): Promise<{ positionId: string; result: SignExecuteScriptTxResult }>

Decreases the position’s liquidity and, in the same transaction, collects all accrued fees and rewards. Tokens go to the signer.

required

Identify the pool.

required

Identify the position.

bigint

required

Liquidity units to remove (read the position’s current liquidity, then take a fraction).

'token0' | 'token1'

required

Which side baseAmount refers to.

bigint

required

Minimum amount of the base token to receive.

bigint

required

Minimum amount of the other token to receive. Despite the name, it’s passed on-chain as a minimum.

Pass 0n for both minimums to disable the check.

`collectTokens(params)`

collectTokens(p: ClmmCollectTokensRequest): Promise<{ positionId: string; result: SignExecuteScriptTxResult }>

Collects accrued fees and rewards to recipient. It does not remove liquidity; use removeLiquidity for that.

required

Identify the position.

string

required

bigint

required

Caps on what to collect. Use U128_MAX-sized values (for example UNLIMITED_AMOUNT) to collect everything.

`positionInfo(params)`

positionInfo(p: ClmmPositionInfoRequest): Promise<ClmmPositionInfo>
// => { amount0, amount1, fees: [bigint, bigint, bigint], avgValue, avgFees, avgTime }

Calls the pool’s positionInfo view and returns its result unchanged. fees holds three entries: token0, token1, and the pool’s reward token. The SDK passes the accumulator arguments (acc, iacc0, iacc1, t0, acct0) straight to the contract. See the Pool contract source for what they mean. To read a position’s raw liquidity, fetch the position contract:

import { ClmmContracts } from '@alephium/powfi-sdk'
import { addressFromContractId } from '@alephium/web3'

const pos = await ClmmContracts.Position.at(addressFromContractId(positionId)).fetchState()
pos.fields.liquidity // bigint
pos.fields.tokensOwed // [token0, token1, reward]

Farming rewards

A pool can run up to three reward programs (MAX_REWARDS = 3), paying in token0, token1, or the pool’s extra reward token (token2). Programs are set up and funded by the Powfi team.

getPoolRewardState(poolId) returns the reward token and each program’s amount, openTime, and endTime (millisecond timestamps).
Rewards accrued by a position appear in positionInfo(...).fees: token0 rewards in fees[0], token1 rewards in fees[1], and rewards in any other token in fees[2]. They are paid out through collectTokens.

Referral (DEX) accounts

Powfi tracks referrals through per-user DexAccount contracts under a DexAccountRoot.

Method	Description
`createDexAccount(referrer)`	Creates the signer’s account with `referrer` (costs `MINIMAL_CONTRACT_DEPOSIT`).
`getDexAccountId(owner)`	Derives an owner’s account contract ID.
`getDexAccountState(owner)`	`{ address, id, state }` of the account.
`getDexAccountRoot()`	Typed `DexAccountRootInstance`.

Configuration

interface ClmmConfig {
  groupIndex: number
  factoryId: string
  positionManagerId: string
  defaultConfigIndex: bigint // 0n
  accountRoot: string
}

Read the active config with getClmmConfig() and override it with setConfig(). getConfig() re-reads the bundled deployment.

Constants

Name	Value
`MIN_TICK` / `MAX_TICK`	`-887272n` / `887272n`
`MAX_PIPS`	`1_000_000n`
`U256_MAX`	`2n ** 256n - 1n`
`UNLIMITED_AMOUNT`	`2n ** 128n - 1n`

SDK & API

Core concepts

Modules

Utilities

Guides

Reference

Guide: swap on CLMM

Guide: open & manage a position

Fee tiers (pool configs)

Pool lookups

`getPoolState(poolId)`

Other pool reads

Swaps

`simulateSwap(params)`

`swap(params)`

`swapTo(params)`

`buildSwapPath(tokenId, configIndex)`

Liquidity positions

`getPositionId(poolId, owner, tickLower, tickUpper)`

`createPool(...)`

`addLiquidity(params)`

`removeLiquidity(params)`

`collectTokens(params)`

`positionInfo(params)`

Farming rewards

Referral (DEX) accounts

Configuration

Constants

Guide: swap on CLMM

Guide: open & manage a position

​Fee tiers (pool configs)

​Pool lookups

​getPoolState(poolId)

​Other pool reads

​Swaps

​simulateSwap(params)

​swap(params)

​swapTo(params)

​buildSwapPath(tokenId, configIndex)

​Liquidity positions

​getPositionId(poolId, owner, tickLower, tickUpper)

​createPool(...)

​addLiquidity(params)

​removeLiquidity(params)

​collectTokens(params)

​positionInfo(params)

​Farming rewards

​Referral (DEX) accounts

​Configuration

​Constants

Fee tiers (pool configs)

Pool lookups

`getPoolState(poolId)`

Other pool reads

Swaps

`simulateSwap(params)`

`swap(params)`

`swapTo(params)`

`buildSwapPath(tokenId, configIndex)`

Liquidity positions

`getPositionId(poolId, owner, tickLower, tickUpper)`

`createPool(...)`

`addLiquidity(params)`

`removeLiquidity(params)`

`collectTokens(params)`

`positionInfo(params)`

Farming rewards

Referral (DEX) accounts

Configuration

Constants