Ferra's DLMM liquidity distribution example
| What's DLMM | Learn about DLMM liquidity, an innovative and advantageous model on the Sui network | /files/DFDAGtBCgAtl3IsCx4Oi | /pages/PxGSrkbi2I69IWIH4Tv9 | |
| Pool Comparison | Compare the three types of Ferra liquidity pools and learn how to use each one effectively. | /files/0CsOmTPg5VUP1Ihcsmt9 | /pages/6cxKqyxLBR1G6uH3RGog | |
| Integration Guide | Step-by-step guide to integrating with Ferra liquidity pools using either the TypeScript SDK or the smart contract interface. | /files/Rxhkl7W5NgenJsQlKCGr | /pages/rkIzbUESE8pAlcKcYJqH |
Ferra's DLMM liquidity distribution example
Curve Liquidity Distribution for SUI/USDC
Bid-Ask Liquidity Distribution for SUI/USDC
Spot Liquidity Distribution for SUI/USDC
AMM and CLMM liquidity distribution comparison
| Component | Description |
| Ticks | Discrete price points dividing the price range. Each tick represents a specific price, with tick spacing determining granularity (e.g., 0.01% price steps). |
| Liquidity Positions | LPs create positions by specifying a lower and upper tick. Liquidity is active only within this range, earning fees when trades occur inside it. Each position is an on‑chain NFT storing range, liquidity, and fees. |
| Fee Tiers | Pools offer different fee levels (e.g., 0.01%, 0.05%, 0.3%), allowing LPs to choose based on expected trading volume and risk. |
Tick-based in Ferra's CLMM liquidity model
| Component | Description |
|---|---|
| Swap Fee | Percentage charged on every trade (e.g., 0.05 %, 0.30 %, 1 %). |
| Fee Tier | Each pool has a fixed swap‑fee tier chosen at deployment. Multiple pools with different tiers can coexist for the same token pair. |
| Protocol Fee | A configurable share of the swap fee routed to the Ferra treasury. The remainder goes to LPs. It is set to 20% by default |
| Range Strategy | Typical Width | When to Use | Pros | Const | Upkeep |
|---|---|---|---|---|---|
| Narrow | ±0.5 – 2 % around spot | High‑volume, low‑volatility pairs; active LPs | Highest fee APR per dollar | Falls out‑of‑range quickly; needs frequent re‑centering | High |
| Medium | ±5 – 10 % | Range‑bound blue chips | Balanced uptime vs. efficiency | Lower APR than narrow; some upkeep | Medium |
| Wide | ±20 – 50 % | Long‑term passive LPs; volatile tokens | Stays active longer; low maintenance | Capital spread thin → lower fee capture | Low |
| Ladder | Stacked narrow + medium + wide | Diversify IL risk and fee capture | Blends benefits of multiple widths | Higher gas costs; more complex | Medium, High |
Linear decay function over the time (t)
Exponential decay function over the time (t)
• Minimal slippage
• Precise pricing
• Better for limit orders
|• Liquidity spread thin
• More bins needed
• Higher gas on rebalancing
| | **Large** (100+ bps) |• Concentrated liquidity
• Fewer bins to manage
• Lower rebalancing costs
|• Higher slippage
• Larger price jumps
• Less precise entries
| #### Quick Reference ```typescript // Recommended bin steps by pair type const binStepGuide = { stablecoin: 1, // USDC/USDT correlated: 5, // haSUI/SUI bluechip: 20, // SUI/USDC volatile: 100, // MEME/USDC exotic: 200 // New launches }; ``` #### Practical Example For SUI/USDC with 20 bps bin step: * Bin 8388608: $3.00 * Bin 8388609: $3.01 (0.3% higher) * Bin 8388610: $3.02 (0.6% higher) This provides good balance between capital efficiency and price precision. # Price Helpers ## Price Helpers Utility functions for price conversions between human-readable formats and protocol values. Essential helpers for working with DLMM's bin-based pricing system. ### Core Price Functions ```typescript // Convert bin ID to price function getPriceFromBinId(binId: number, binStep: number): number { const base = 1 + binStep / 10000; const exponent = binId - 8388608; return Math.pow(base, exponent); } // Convert price to bin ID function getBinIdFromPrice(price: number, binStep: number): number { const base = 1 + binStep / 10000; const binId = Math.log(price) / Math.log(base) + 8388608; return Math.round(binId); } // Get price with high precision function getPriceFromBinIdPrecise(binId: number, binStep: number): string { const base = 1 + binStep / 10000; const exponent = binId - 8388608; const price = Math.pow(base, exponent); return price.toPrecision(18); } ``` ### Price Formatting ```typescript // Format price for display function formatPrice(price: number, decimals: number = 4): string { if (price > 10000) { return price.toLocaleString('en-US', { maximumFractionDigits: 0 }); } else if (price > 1) { return price.toFixed(decimals); } else { return price.toPrecision(decimals); } } // Smart format based on value function autoFormatPrice(price: number): string { if (price >= 1000) return formatPrice(price, 0); if (price >= 1) return formatPrice(price, 2); if (price >= 0.01) return formatPrice(price, 4); return price.toPrecision(4); } ``` ### Price Range Calculations ```typescript // Get price range from bin range function getPriceRange( centerBinId: number, binRadius: number, binStep: number ): { min: number, max: number, spread: number } { const minPrice = getPriceFromBinId(centerBinId - binRadius, binStep); const maxPrice = getPriceFromBinId(centerBinId + binRadius, binStep); return { min: minPrice, max: maxPrice, spread: ((maxPrice - minPrice) / minPrice) * 100 }; } // Calculate bins needed for price range function getBinsForPriceRange( currentPrice: number, minPrice: number, maxPrice: number, binStep: number ): { lower: number, upper: number, total: number } { const currentBin = getBinIdFromPrice(currentPrice, binStep); const minBin = getBinIdFromPrice(minPrice, binStep); const maxBin = getBinIdFromPrice(maxPrice, binStep); return { lower: currentBin - minBin, upper: maxBin - currentBin, total: maxBin - minBin + 1 }; } ``` ### Price Conversions ```typescript // Convert between token ratios function calculateTokenRatio( amountX: bigint, amountY: bigint, decimalsX: number, decimalsY: number ): number { const x = Number(amountX) / (10 ** decimalsX); const y = Number(amountY) / (10 ** decimalsY); return y / x; // Price of X in terms of Y } // Normalize price for different decimals function normalizePrice( price: number, decimalsX: number, decimalsY: number ): number { const decimalDiff = decimalsY - decimalsX; return price * Math.pow(10, decimalDiff); } ``` ### Bin Navigation ```typescript // Get next/previous bin prices function getAdjacentPrices( binId: number, binStep: number, count: number = 5 ): { below: number[], current: number, above: number[] } { const below = []; const above = []; for (let i = 1; i <= count; i++) { below.push(getPriceFromBinId(binId - i, binStep)); above.push(getPriceFromBinId(binId + i, binStep)); } return { below: below.reverse(), current: getPriceFromBinId(binId, binStep), above }; } // Find nearest bin to target price function getNearestBin( targetPrice: number, binStep: number ): { binId: number, actualPrice: number, difference: number } { const binId = getBinIdFromPrice(targetPrice, binStep); const actualPrice = getPriceFromBinId(binId, binStep); return { binId, actualPrice, difference: Math.abs(targetPrice - actualPrice) }; } ``` ### Price Validation ```typescript // DLMM constants const PRICE_BOUNDS = { MIN_BIN_ID: 0, MAX_BIN_ID: 16777215, // 2^24 - 1 REFERENCE_BIN_ID: 8388608 // Price = 1.0 }; // Validate price is within DLMM bounds function isValidPrice(price: number, binStep: number): boolean { try { const binId = getBinIdFromPrice(price, binStep); return binId >= PRICE_BOUNDS.MIN_BIN_ID && binId <= PRICE_BOUNDS.MAX_BIN_ID; } catch { return false; } } // Get max/min prices for bin step function getPriceBounds(binStep: number): { min: number, max: number } { return { min: getPriceFromBinId(PRICE_BOUNDS.MIN_BIN_ID, binStep), max: getPriceFromBinId(PRICE_BOUNDS.MAX_BIN_ID, binStep) }; } ``` ### Utility Functions ```typescript // Quick helpers const priceHelpers = { // Get current price from pair getCurrentPrice: (pair: LBPair) => getPriceFromBinId(pair.parameters.active_id, Number(pair.binStep)), // Calculate price impact getPriceImpact: (startBin: number, endBin: number, binStep: number) => { const startPrice = getPriceFromBinId(startBin, binStep); const endPrice = getPriceFromBinId(endBin, binStep); return ((endPrice - startPrice) / startPrice) * 100; }, // Format pair price for display formatPairPrice: (pair: LBPair, decimals?: number) => { const price = getPriceFromBinId(pair.parameters.active_id, Number(pair.binStep)); return autoFormatPrice(price); } }; ``` # Best Practices Performance optimization tips for efficient DLMM interactions. Minimize gas usage, batch operations effectively, and implement robust patterns for production applications. ### Gas Optimization #### Batch Operations ```typescript // ❌ Bad: Multiple transactions await sdk.Pair.removeLiquidity(pair, { positionId, binIds: [1] }); await sdk.Pair.removeLiquidity(pair, { positionId, binIds: [2] }); await sdk.Pair.removeLiquidity(pair, { positionId, binIds: [3] }); // ✅ Good: Single transaction await sdk.Pair.removeLiquidity(pair, { positionId, binIds: [1, 2, 3] }); ``` #### Minimize Bin Count ```typescript // Gas scales with number of bins const gasEfficient = { // ❌ Excessive: 100 bins wide: Array.from({length: 101}, (_, i) => i - 50), // ✅ Efficient: Focused liquidity focused: Array.from({length: 21}, (_, i) => i - 10) }; // Consider gas cost vs capital efficiency function optimizeBinCount(expectedVolatility: number): number { if (expectedVolatility < 0.01) return 10; // Stable if (expectedVolatility < 0.05) return 20; // Normal return 30; // Volatile } ``` ### Efficient Data Fetching #### Cache Pair Data ```typescript class PairCache { private cache = new Map| Tick Spacing | Fee |
|---|---|
| 2 | 0.01% |
| 10 | 0.05% |
| 20 | 0.1% |
| 60 | 0.5% |
| 200 | 1% |
| 220 | 5% |
import { clmmMainnet, initFerraSDK } from '@ferra-labs/clmm'
// Initialize SDK
const sdk = initFerraSDK({
...clmmMainnet,
network: 'beta',
fullNodeUrl: 'https://...',
wallet: '0x...'
})
const tx = sdk.Position.openPositionTransactionPayload({
pool_id: '0x...',
coinTypeA: '0x2::sui::SUI',
coinTypeB: '0x...::usdc::USDC',
tick_lower: -1000,
tick_upper: 1000
})
// Execute
const result = await sdk.fullClient.signAndExecuteTransaction({
transaction: tx,
signer: keypair
})
const position = await sdk.Position.getPositionById(positionId)
const pool = await sdk.Pool.getPool(position.pool)
const amountA = 100000000
const amountB = 2000000000
const percent = 0.2
const { tokenMaxA, tokenMaxB, liquidity } = await estimateRemovePosition(poolOnchain, position, amountA, amountB);
const rewards = await ferraSDK.Rewarder.fetchPositionRewarders(
poolOnchain,
position.pos_object_id
);
const rewardCoinTypes = rewards
.filter((item) => Number(item.amount_owed) > 0)
.map((item) => item.coin_address);
const closeLiquidityPayloadParams: ClosePositionParams = {
coinTypeA: poolOnchain.coinTypeA,
coinTypeB: poolOnchain.coinTypeB,
pool_id: poolOnchain.poolAddress,
min_amount_a: tokenMaxA.toString(),
min_amount_b: tokenMaxB.toString(),
collect_fee: true,
rewarder_coin_types: rewardCoinTypes,
pos_id: position.pos_object_id,
};
const tx = await sdk.Position.closePositionTransactionPayload(closeLiquidityPayloadParams);
const result = await sdk.fullClient.signAndExecuteTransaction({
transaction: tx,
signer: keypair
})