@flashnet/sdk 0.4.3 → 0.5.0

package/dist/esm/src/client/FlashnetClient.js

@@ -1,12 +1,12 @@
+import sha256 from 'fast-sha256';
 import { ApiClient } from '../api/client.js';
 import { TypedAmmApi } from '../api/typed-endpoints.js';
 import { getClientEnvironmentName, resolveClientNetworkConfig, getClientNetworkConfig, BTC_ASSET_PUBKEY } from '../config/index.js';
 import { getSparkNetworkFromLegacy, getClientEnvironmentFromLegacy, Network } from '../types/index.js';
 import { generateNonce, compareDecimalStrings } from '../utils/index.js';
 import { AuthManager } from '../utils/auth.js';
-import sha256 from 'fast-sha256';
 import { getHexFromUint8Array } from '../utils/hex.js';
-import { generateConstantProductPoolInitializationIntentMessage, generatePoolInitializationIntentMessage, generatePoolConfirmInitialDepositIntentMessage, generatePoolSwapIntentMessage, generateRouteSwapIntentMessage, generateAddLiquidityIntentMessage, generateRemoveLiquidityIntentMessage, generateRegisterHostIntentMessage, generateWithdrawHostFeesIntentMessage, generateWithdrawIntegratorFeesIntentMessage, generateCreateEscrowIntentMessage, generateFundEscrowIntentMessage, generateClaimEscrowIntentMessage, generateClawbackIntentMessage } from '../utils/intents.js';
+import { generateConstantProductPoolInitializationIntentMessage, generatePoolInitializationIntentMessage, generatePoolConfirmInitialDepositIntentMessage, generatePoolSwapIntentMessage, generateRouteSwapIntentMessage, generateAddLiquidityIntentMessage, generateRemoveLiquidityIntentMessage, generateRegisterHostIntentMessage, generateWithdrawHostFeesIntentMessage, generateWithdrawIntegratorFeesIntentMessage, generateCreateEscrowIntentMessage, generateFundEscrowIntentMessage, generateClaimEscrowIntentMessage, generateClawbackIntentMessage, generateCreateConcentratedPoolIntentMessage, generateDecreaseLiquidityIntentMessage, generateCollectFeesIntentMessage, generateWithdrawBalanceIntentMessage, generateIncreaseLiquidityIntentMessage, generateRebalancePositionIntentMessage } from '../utils/intents.js';
 import { getSparkNetworkFromAddress, encodeSparkAddressNew } from '../utils/spark-address.js';
 import { encodeSparkHumanReadableTokenIdentifier, decodeSparkHumanReadableTokenIdentifier } from '../utils/tokenAddress.js';
 import { FlashnetError } from '../types/errors.js';
@@ -214,8 +214,7 @@ class FlashnetClient {
     }
     /**
      * Convert a token identifier into the raw hex string form expected by the Flashnet backend.
-     * If the identifier is the BTC constant or already a hex string, it is returned unchanged.
-     * If it is in Bech32m human-readable form, it is decoded to hex.
+     * Handles BTC constant, hex strings, and Bech32m human-readable format.
      */
     toHexTokenIdentifier(tokenIdentifier) {
         if (tokenIdentifier === BTC_ASSET_PUBKEY) {
@@ -300,7 +299,7 @@ class FlashnetClient {
             }
         }
     }
-    // ===== Pool Operations =====
+    // Pool Operations
     /**
      * List pools with optional filters
      */
@@ -563,7 +562,7 @@ class FlashnetClient {
         };
         return this.typedApi.confirmInitialDeposit(request);
     }
-    // ===== Swap Operations =====
+    // Swap Operations
     /**
      * Simulate a swap without executing it
      */
@@ -812,7 +811,7 @@ class FlashnetClient {
             return response;
         }, [initialTransferId], firstPoolId);
     }
-    // ===== Liquidity Operations =====
+    // Liquidity Operations
     /**
      * Simulate adding liquidity
      */
@@ -963,7 +962,7 @@ class FlashnetClient {
         }
         return response;
     }
-    // ===== Host Operations =====
+    // Host Operations
     /**
      * Register as a host
      */
@@ -1109,7 +1108,7 @@ class FlashnetClient {
         await this.ensureInitialized();
         return this.typedApi.getIntegratorFees();
     }
-    // ===== Escrow Operations =====
+    // Escrow Operations
     /**
      * Creates a new escrow contract.
      * This is the first step in a two-step process: create, then fund.
@@ -1248,7 +1247,7 @@ class FlashnetClient {
         await this.ensureInitialized();
         return this.typedApi.getEscrow(escrowId);
     }
-    // ===== Swap History =====
+    // Swap History
     /**
      * Get swaps for a specific pool
      */
@@ -1271,7 +1270,7 @@ class FlashnetClient {
         const user = userPublicKey || this.publicKey;
         return this.typedApi.getUserSwaps(user, query);
     }
-    // ===== Clawback =====
+    // Clawback
     /**
      * Request clawback of a stuck inbound transfer to an LP wallet
      */
@@ -1456,7 +1455,7 @@ class FlashnetClient {
             throw flashnetError;
         }
     }
-    // ===== Clawback Monitor =====
+    // Clawback Monitor
     /**
      * Start a background job that periodically polls for clawbackable transfers
      * and automatically claws them back.
@@ -1590,7 +1589,7 @@ class FlashnetClient {
             },
         };
     }
-    // ===== Token Address Operations =====
+    // Token Address Operations
     /**
      * Encode a token identifier into a human-readable token address using the client's Spark network
      * @param tokenIdentifier - Token identifier as hex string or Uint8Array
@@ -1625,8 +1624,8 @@ class FlashnetClient {
     decodeLegacyTokenAddress(address) {
         return decodeSparkHumanReadableTokenIdentifier(address, this.sparkNetwork);
     }
-    // ===== Status =====
-    // ===== Config Inspection =====
+    // Status
+    // Config Inspection
     /**
      * Get raw feature status list (cached briefly)
      */
@@ -1687,7 +1686,7 @@ class FlashnetClient {
         await this.ensureInitialized();
         return this.typedApi.ping();
     }
-    // ===== Helper Methods =====
+    // Helper Methods
     /**
      * Performs asset transfer using generalized asset address for both BTC and tokens.
      */
@@ -1787,7 +1786,7 @@ class FlashnetClient {
             throw new Error(errorMessage);
         }
     }
-    // ===== Lightning Payment with Token =====
+    // Lightning Payment with Token
     /**
      * Get a quote for paying a Lightning invoice with a token.
      * This calculates the optimal pool and token amount needed.
@@ -1803,7 +1802,18 @@ class FlashnetClient {
         // Decode the invoice to get the amount
         const invoiceAmountSats = await this.decodeInvoiceAmount(invoice);
         if (!invoiceAmountSats || invoiceAmountSats <= 0) {
-            throw new Error("Unable to decode invoice amount. Zero-amount invoices are not supported for token payments.");
+            throw new FlashnetError("Unable to decode invoice amount. Zero-amount invoices are not supported for token payments.", {
+                response: {
+                    errorCode: "FSAG-1002",
+                    errorCategory: "Validation",
+                    message: "Unable to decode invoice amount. Zero-amount invoices are not supported for token payments.",
+                    requestId: "",
+                    timestamp: new Date().toISOString(),
+                    service: "sdk",
+                    severity: "Error",
+                    remediation: "Provide a valid BOLT11 invoice with a non-zero amount.",
+                },
+            });
         }
         // Get Lightning fee estimate
         const lightningFeeEstimate = await this.getLightningFeeEstimate(invoice);
@@ -1822,9 +1832,19 @@ class FlashnetClient {
         // Check BTC minimum (output from swap)
         const btcMinAmount = minAmounts.get(BTC_ASSET_PUBKEY.toLowerCase());
         if (btcMinAmount && totalBtcNeeded < btcMinAmount) {
-            throw new Error(`Invoice amount too small. Flashnet minimum BTC output is ${btcMinAmount} sats, ` +
-                `but invoice + lightning fee totals only ${totalBtcNeeded} sats. ` +
-                `Please use an invoice of at least ${btcMinAmount} sats.`);
+            const msg = `Invoice amount too small. Minimum BTC output is ${btcMinAmount} sats, but invoice + lightning fee totals only ${totalBtcNeeded} sats.`;
+            throw new FlashnetError(msg, {
+                response: {
+                    errorCode: "FSAG-1003",
+                    errorCategory: "Validation",
+                    message: msg,
+                    requestId: "",
+                    timestamp: new Date().toISOString(),
+                    service: "sdk",
+                    severity: "Error",
+                    remediation: `Use an invoice of at least ${btcMinAmount} sats.`,
+                },
+            });
         }
         // Find the best pool to swap token -> BTC
         const poolQuote = await this.findBestPoolForTokenToBtc(tokenAddress, totalBtcNeeded.toString(), options?.integratorFeeRateBps);
@@ -1833,9 +1853,19 @@ class FlashnetClient {
         const tokenMinAmount = minAmounts.get(tokenHex);
         if (tokenMinAmount &&
             BigInt(poolQuote.tokenAmountRequired) < tokenMinAmount) {
-            throw new Error(`Token amount too small. Flashnet minimum input is ${tokenMinAmount} units, ` +
-                `but calculated amount is only ${poolQuote.tokenAmountRequired} units. ` +
-                `Please use a larger invoice amount.`);
+            const msg = `Token amount too small. Minimum input is ${tokenMinAmount} units, but calculated amount is only ${poolQuote.tokenAmountRequired} units.`;
+            throw new FlashnetError(msg, {
+                response: {
+                    errorCode: "FSAG-1003",
+                    errorCategory: "Validation",
+                    message: msg,
+                    requestId: "",
+                    timestamp: new Date().toISOString(),
+                    service: "sdk",
+                    severity: "Error",
+                    remediation: "Use a larger invoice amount.",
+                },
+            });
         }
         // Calculate the BTC variable fee adjustment (how much extra we're requesting)
         const btcVariableFeeAdjustment = Number(totalBtcNeeded - baseBtcNeeded);
@@ -2069,6 +2099,8 @@ class FlashnetClient {
         const tokenHex = this.toHexTokenIdentifier(tokenAddress);
         const btcHex = BTC_ASSET_PUBKEY;
         // Find all pools that have this token paired with BTC
+        // Note: The API may return the same pool for both filter combinations,
+        // so we need to deduplicate and determine tokenIsAssetA from actual pool data
         const poolsWithTokenAsA = await this.listPools({
             assetAAddress: tokenHex,
             assetBAddress: btcHex,
@@ -2077,17 +2109,57 @@ class FlashnetClient {
             assetAAddress: btcHex,
             assetBAddress: tokenHex,
         });
-        const allPools = [
-            ...poolsWithTokenAsA.pools.map((p) => ({ ...p, tokenIsAssetA: true })),
-            ...poolsWithTokenAsB.pools.map((p) => ({ ...p, tokenIsAssetA: false })),
-        ];
+        // Deduplicate pools by poolId and determine tokenIsAssetA from actual pool addresses
+        const poolMap = new Map();
+        for (const p of [...poolsWithTokenAsA.pools, ...poolsWithTokenAsB.pools]) {
+            if (!poolMap.has(p.lpPublicKey)) {
+                // Determine tokenIsAssetA from actual pool asset addresses, not from which query returned it
+                const tokenIsAssetA = p.assetAAddress?.toLowerCase() === tokenHex.toLowerCase();
+                poolMap.set(p.lpPublicKey, { pool: p, tokenIsAssetA });
+            }
+        }
+        const allPools = Array.from(poolMap.values()).map(({ pool, tokenIsAssetA }) => ({
+            ...pool,
+            tokenIsAssetA,
+        }));
         if (allPools.length === 0) {
-            throw new Error(`No liquidity pool found for token ${tokenAddress} paired with BTC`);
+            throw new FlashnetError(`No liquidity pool found for token ${tokenAddress} paired with BTC`, {
+                response: {
+                    errorCode: "FSAG-4001",
+                    errorCategory: "Business",
+                    message: `No liquidity pool found for token ${tokenAddress} paired with BTC`,
+                    requestId: "",
+                    timestamp: new Date().toISOString(),
+                    service: "sdk",
+                    severity: "Error",
+                },
+            });
+        }
+        // Pre-check: Get minimum amounts to provide clear error if invoice is too small
+        const minAmounts = await this.getMinAmountsMap();
+        const btcMinAmount = minAmounts.get(BTC_ASSET_PUBKEY.toLowerCase());
+        // Check if the BTC amount needed is below the minimum
+        if (btcMinAmount && BigInt(btcAmountNeeded) < btcMinAmount) {
+            const msg = `Invoice amount too small. Minimum ${btcMinAmount} sats required, but invoice only requires ${btcAmountNeeded} sats.`;
+            throw new FlashnetError(msg, {
+                response: {
+                    errorCode: "FSAG-1003",
+                    errorCategory: "Validation",
+                    message: msg,
+                    requestId: "",
+                    timestamp: new Date().toISOString(),
+                    service: "sdk",
+                    severity: "Error",
+                    remediation: `Use an invoice with at least ${btcMinAmount} sats.`,
+                },
+            });
         }
         // Find the best pool (lowest token cost for the required BTC)
         let bestPool = null;
         let bestTokenAmount = BigInt(Number.MAX_SAFE_INTEGER);
         let bestSimulation = null;
+        // Track errors for each pool to provide better diagnostics
+        const poolErrors = [];
         for (const pool of allPools) {
             try {
                 // Get pool details for reserves
@@ -2121,12 +2193,53 @@ class FlashnetClient {
                             warningMessage: simulation.warningMessage,
                         };
                     }
+                    else {
+                        // Simulation output was insufficient
+                        const btcReserve = pool.tokenIsAssetA
+                            ? poolDetails.assetBReserve
+                            : poolDetails.assetAReserve;
+                        poolErrors.push({
+                            poolId: pool.lpPublicKey,
+                            error: `Simulation output (${simulation.amountOut} sats) < required (${btcAmountNeeded} sats)`,
+                            btcReserve,
+                        });
+                    }
                 }
             }
-            catch { }
+            catch (e) {
+                // Capture pool errors for diagnostics
+                const errorMessage = e instanceof Error ? e.message : String(e);
+                poolErrors.push({
+                    poolId: pool.lpPublicKey,
+                    error: errorMessage,
+                });
+            }
         }
         if (!bestPool || !bestSimulation) {
-            throw new Error(`No pool has sufficient liquidity for ${btcAmountNeeded} sats`);
+            let errorMessage = `No pool has sufficient liquidity for ${btcAmountNeeded} sats`;
+            if (poolErrors.length > 0) {
+                const details = poolErrors
+                    .map((pe) => {
+                    const reserveInfo = pe.btcReserve
+                        ? ` (BTC reserve: ${pe.btcReserve})`
+                        : "";
+                    return `  - Pool ${pe.poolId.slice(0, 12)}...${reserveInfo}: ${pe.error}`;
+                })
+                    .join("\n");
+                errorMessage += `\n\nPool evaluation details:\n${details}`;
+            }
+            throw new FlashnetError(errorMessage, {
+                response: {
+                    errorCode: "FSAG-4201",
+                    errorCategory: "Business",
+                    message: errorMessage,
+                    requestId: "",
+                    timestamp: new Date().toISOString(),
+                    service: "sdk",
+                    severity: "Error",
+                    remediation: "Try a smaller amount or wait for more liquidity.",
+                },
+            });
         }
         const poolDetails = await this.getPool(bestPool.lpPublicKey);
         return {
@@ -2375,7 +2488,7 @@ class FlashnetClient {
     async cleanup() {
         await this._wallet.cleanupConnections();
     }
-    // ===== Config and Policy Enforcement Helpers =====
+    // Config and Policy Enforcement Helpers
     async ensureAmmOperationAllowed(requiredFeature) {
         await this.ensurePingOk();
         const featureMap = await this.getFeatureStatusMap();
@@ -2555,6 +2668,470 @@ ${relaxed.toString()} (50% relaxed), provided minAmountOut ${minAmountOut.toStri
             throw new Error(`Asset B is not allowed for pool creation: ${assetBHex}`);
         }
     }
+    // V3 Concentrated Liquidity Operations
+    /**
+     * Create a V3 concentrated liquidity pool
+     *
+     * Concentrated liquidity pools allow LPs to provide liquidity within specific
+     * price ranges (tick ranges) for higher capital efficiency.
+     *
+     * @param params Pool creation parameters
+     * @param params.assetAAddress - Address of asset A (base asset)
+     * @param params.assetBAddress - Address of asset B (quote asset)
+     * @param params.tickSpacing - Tick spacing (common values: 10, 60, 200)
+     * @param params.initialPrice - Initial price of asset A in terms of asset B
+     * @param params.lpFeeRateBps - LP fee rate in basis points
+     * @param params.hostFeeRateBps - Host fee rate in basis points
+     * @param params.hostNamespace - Optional host namespace
+     * @param params.poolOwnerPublicKey - Optional pool owner (defaults to wallet pubkey)
+     */
+    async createConcentratedPool(params) {
+        await this.ensureInitialized();
+        await this.ensureAmmOperationAllowed("allow_pool_creation");
+        await this.assertAllowedAssetBForPoolCreation(this.toHexTokenIdentifier(params.assetBAddress));
+        const poolOwnerPublicKey = params.poolOwnerPublicKey ?? this.publicKey;
+        // Generate intent
+        const nonce = generateNonce();
+        const intentMessage = generateCreateConcentratedPoolIntentMessage({
+            poolOwnerPublicKey,
+            assetAAddress: this.toHexTokenIdentifier(params.assetAAddress),
+            assetBAddress: this.toHexTokenIdentifier(params.assetBAddress),
+            tickSpacing: params.tickSpacing,
+            initialPrice: params.initialPrice,
+            lpFeeRateBps: params.lpFeeRateBps.toString(),
+            hostFeeRateBps: params.hostFeeRateBps.toString(),
+            nonce,
+        });
+        // Sign intent
+        const messageHash = sha256(intentMessage);
+        const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+        const request = {
+            poolOwnerPublicKey,
+            assetAAddress: this.toHexTokenIdentifier(params.assetAAddress),
+            assetBAddress: this.toHexTokenIdentifier(params.assetBAddress),
+            tickSpacing: params.tickSpacing,
+            initialPrice: params.initialPrice,
+            lpFeeRateBps: params.lpFeeRateBps.toString(),
+            hostFeeRateBps: params.hostFeeRateBps.toString(),
+            hostNamespace: params.hostNamespace,
+            nonce,
+            signature: getHexFromUint8Array(signature),
+        };
+        return this.typedApi.createConcentratedPool(request);
+    }
+    /**
+     * Add liquidity to a V3 concentrated position
+     *
+     * Increases liquidity within a specific tick range. If the position doesn't exist,
+     * a new position is created.
+     *
+     * @param params Position parameters
+     * @param params.poolId - Pool ID (LP identity public key)
+     * @param params.tickLower - Lower tick of the position
+     * @param params.tickUpper - Upper tick of the position
+     * @param params.amountADesired - Desired amount of asset A to add
+     * @param params.amountBDesired - Desired amount of asset B to add
+     * @param params.amountAMin - Minimum amount of asset A (slippage protection)
+     * @param params.amountBMin - Minimum amount of asset B (slippage protection)
+     * @param params.useFreeBalanceA - If true, use free balance from pool for asset A instead of Spark transfer
+     * @param params.useFreeBalanceB - If true, use free balance from pool for asset B instead of Spark transfer
+     * @param params.retainExcessInBalance - If true, retain any excess amounts in pool free balance instead of refunding via Spark
+     */
+    async increaseLiquidity(params) {
+        await this.ensureInitialized();
+        await this.ensureAmmOperationAllowed("allow_add_liquidity");
+        // Get pool details to know asset addresses
+        const pool = await this.getPool(params.poolId);
+        // Transfer assets to pool (unless using free balance)
+        const lpSparkAddress = encodeSparkAddressNew({
+            identityPublicKey: params.poolId,
+            network: this.sparkNetwork,
+        });
+        let assetATransferId = "";
+        let assetBTransferId = "";
+        const transferIds = [];
+        // Transfer asset A if not using free balance
+        if (!params.useFreeBalanceA && BigInt(params.amountADesired) > 0n) {
+            assetATransferId = await this.transferAsset({
+                receiverSparkAddress: lpSparkAddress,
+                assetAddress: pool.assetAAddress,
+                amount: params.amountADesired,
+            }, "Insufficient balance for adding V3 liquidity (Asset A): ");
+            transferIds.push(assetATransferId);
+        }
+        // Transfer asset B if not using free balance
+        if (!params.useFreeBalanceB && BigInt(params.amountBDesired) > 0n) {
+            assetBTransferId = await this.transferAsset({
+                receiverSparkAddress: lpSparkAddress,
+                assetAddress: pool.assetBAddress,
+                amount: params.amountBDesired,
+            }, "Insufficient balance for adding V3 liquidity (Asset B): ");
+            transferIds.push(assetBTransferId);
+        }
+        const executeIncrease = async () => {
+            // Generate intent
+            const nonce = generateNonce();
+            const intentMessage = generateIncreaseLiquidityIntentMessage({
+                userPublicKey: this.publicKey,
+                lpIdentityPublicKey: params.poolId,
+                tickLower: params.tickLower,
+                tickUpper: params.tickUpper,
+                assetASparkTransferId: assetATransferId,
+                assetBSparkTransferId: assetBTransferId,
+                amountADesired: params.amountADesired,
+                amountBDesired: params.amountBDesired,
+                amountAMin: params.amountAMin,
+                amountBMin: params.amountBMin,
+                nonce,
+            });
+            // Sign intent
+            const messageHash = sha256(intentMessage);
+            const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+            const request = {
+                poolId: params.poolId,
+                tickLower: params.tickLower,
+                tickUpper: params.tickUpper,
+                assetASparkTransferId: assetATransferId,
+                assetBSparkTransferId: assetBTransferId,
+                amountADesired: params.amountADesired,
+                amountBDesired: params.amountBDesired,
+                amountAMin: params.amountAMin,
+                amountBMin: params.amountBMin,
+                useFreeBalanceA: params.useFreeBalanceA,
+                useFreeBalanceB: params.useFreeBalanceB,
+                retainExcessInBalance: params.retainExcessInBalance,
+                nonce,
+                signature: getHexFromUint8Array(signature),
+            };
+            const response = await this.typedApi.increaseLiquidity(request);
+            if (!response.accepted) {
+                const errorMessage = response.error || "Increase liquidity rejected by the AMM";
+                const hasRefund = !!(response.amountARefund || response.amountBRefund);
+                const refundInfo = hasRefund
+                    ? ` Refunds: Asset A: ${response.amountARefund || "0"}, Asset B: ${response.amountBRefund || "0"}`
+                    : "";
+                throw new FlashnetError(`${errorMessage}.${refundInfo}`, {
+                    response: {
+                        errorCode: hasRefund ? "FSAG-4203" : "UNKNOWN",
+                        errorCategory: hasRefund ? "Business" : "System",
+                        message: `${errorMessage}.${refundInfo}`,
+                        requestId: response.requestId || "",
+                        timestamp: new Date().toISOString(),
+                        service: "amm-gateway",
+                        severity: "Error",
+                    },
+                    httpStatus: 400,
+                    transferIds: hasRefund ? [] : transferIds,
+                    lpIdentityPublicKey: params.poolId,
+                });
+            }
+            return response;
+        };
+        // Execute with auto-clawback if we made transfers
+        if (transferIds.length > 0) {
+            return this.executeWithAutoClawback(executeIncrease, transferIds, params.poolId);
+        }
+        return executeIncrease();
+    }
+    /**
+     * Remove liquidity from a V3 concentrated position
+     *
+     * Decreases liquidity from a specific tick range position.
+     *
+     * @param params Position parameters
+     * @param params.poolId - Pool ID (LP identity public key)
+     * @param params.tickLower - Lower tick of the position
+     * @param params.tickUpper - Upper tick of the position
+     * @param params.liquidityToRemove - Amount of liquidity to remove (use "0" to remove all)
+     * @param params.amountAMin - Minimum amount of asset A to receive (slippage protection)
+     * @param params.amountBMin - Minimum amount of asset B to receive (slippage protection)
+     * @param params.retainInBalance - If true, retain withdrawn assets in pool free balance instead of sending via Spark
+     */
+    async decreaseLiquidity(params) {
+        await this.ensureInitialized();
+        await this.ensureAmmOperationAllowed("allow_withdraw_liquidity");
+        // Generate intent
+        const nonce = generateNonce();
+        const intentMessage = generateDecreaseLiquidityIntentMessage({
+            userPublicKey: this.publicKey,
+            lpIdentityPublicKey: params.poolId,
+            tickLower: params.tickLower,
+            tickUpper: params.tickUpper,
+            liquidityToRemove: params.liquidityToRemove,
+            amountAMin: params.amountAMin,
+            amountBMin: params.amountBMin,
+            nonce,
+        });
+        // Sign intent
+        const messageHash = sha256(intentMessage);
+        const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+        const request = {
+            poolId: params.poolId,
+            tickLower: params.tickLower,
+            tickUpper: params.tickUpper,
+            liquidityToRemove: params.liquidityToRemove,
+            amountAMin: params.amountAMin,
+            amountBMin: params.amountBMin,
+            retainInBalance: params.retainInBalance,
+            nonce,
+            signature: getHexFromUint8Array(signature),
+        };
+        const response = await this.typedApi.decreaseLiquidity(request);
+        if (!response.accepted) {
+            const errorMessage = response.error || "Decrease liquidity rejected by the AMM";
+            throw new Error(errorMessage);
+        }
+        return response;
+    }
+    /**
+     * Collect accumulated fees from a V3 position
+     *
+     * Collects fees earned from trading activity without removing liquidity.
+     *
+     * @param params Position parameters
+     * @param params.poolId - Pool ID (LP identity public key)
+     * @param params.tickLower - Lower tick of the position
+     * @param params.tickUpper - Upper tick of the position
+     * @param params.retainInBalance - If true, retain collected fees in pool free balance instead of sending via Spark
+     */
+    async collectFees(params) {
+        await this.ensureInitialized();
+        await this.ensureAmmOperationAllowed("allow_withdraw_fees");
+        // Generate intent
+        const nonce = generateNonce();
+        const intentMessage = generateCollectFeesIntentMessage({
+            userPublicKey: this.publicKey,
+            lpIdentityPublicKey: params.poolId,
+            tickLower: params.tickLower,
+            tickUpper: params.tickUpper,
+            nonce,
+        });
+        // Sign intent
+        const messageHash = sha256(intentMessage);
+        const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+        const request = {
+            poolId: params.poolId,
+            tickLower: params.tickLower,
+            tickUpper: params.tickUpper,
+            retainInBalance: params.retainInBalance,
+            nonce,
+            signature: getHexFromUint8Array(signature),
+        };
+        const response = await this.typedApi.collectFees(request);
+        if (!response.accepted) {
+            const errorMessage = response.error || "Collect fees rejected by the AMM";
+            throw new Error(errorMessage);
+        }
+        return response;
+    }
+    /**
+     * Rebalance a V3 position to a new tick range
+     *
+     * Atomically moves liquidity from an old position to a new tick range.
+     * Optionally can add additional funds during rebalancing.
+     *
+     * @param params Rebalance parameters
+     * @param params.poolId - Pool ID (LP identity public key)
+     * @param params.oldTickLower - Lower tick of the current position
+     * @param params.oldTickUpper - Upper tick of the current position
+     * @param params.newTickLower - Lower tick for the new position
+     * @param params.newTickUpper - Upper tick for the new position
+     * @param params.liquidityToMove - Amount of liquidity to move (use "0" to move all)
+     * @param params.additionalAmountA - Optional additional asset A to add
+     * @param params.additionalAmountB - Optional additional asset B to add
+     * @param params.retainInBalance - If true, retain any excess amounts in pool free balance instead of sending via Spark
+     */
+    async rebalancePosition(params) {
+        await this.ensureInitialized();
+        await this.ensureAmmOperationAllowed("allow_add_liquidity");
+        // Get pool details
+        const pool = await this.getPool(params.poolId);
+        // Transfer additional assets if provided
+        let assetATransferId;
+        let assetBTransferId;
+        const lpSparkAddress = encodeSparkAddressNew({
+            identityPublicKey: params.poolId,
+            network: this.sparkNetwork,
+        });
+        if (params.additionalAmountA && BigInt(params.additionalAmountA) > 0n) {
+            assetATransferId = await this.transferAsset({
+                receiverSparkAddress: lpSparkAddress,
+                assetAddress: pool.assetAAddress,
+                amount: params.additionalAmountA,
+            }, "Insufficient balance for rebalance (Asset A): ");
+        }
+        if (params.additionalAmountB && BigInt(params.additionalAmountB) > 0n) {
+            assetBTransferId = await this.transferAsset({
+                receiverSparkAddress: lpSparkAddress,
+                assetAddress: pool.assetBAddress,
+                amount: params.additionalAmountB,
+            }, "Insufficient balance for rebalance (Asset B): ");
+        }
+        // Collect transfer IDs for potential clawback
+        const transferIds = [];
+        if (assetATransferId) {
+            transferIds.push(assetATransferId);
+        }
+        if (assetBTransferId) {
+            transferIds.push(assetBTransferId);
+        }
+        // Execute (with auto-clawback if we have transfers)
+        const executeRebalance = async () => {
+            // Generate intent
+            const nonce = generateNonce();
+            const intentMessage = generateRebalancePositionIntentMessage({
+                userPublicKey: this.publicKey,
+                lpIdentityPublicKey: params.poolId,
+                oldTickLower: params.oldTickLower,
+                oldTickUpper: params.oldTickUpper,
+                newTickLower: params.newTickLower,
+                newTickUpper: params.newTickUpper,
+                liquidityToMove: params.liquidityToMove,
+                assetASparkTransferId: assetATransferId,
+                assetBSparkTransferId: assetBTransferId,
+                additionalAmountA: params.additionalAmountA,
+                additionalAmountB: params.additionalAmountB,
+                nonce,
+            });
+            // Sign intent
+            const messageHash = sha256(intentMessage);
+            const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+            const request = {
+                poolId: params.poolId,
+                oldTickLower: params.oldTickLower,
+                oldTickUpper: params.oldTickUpper,
+                newTickLower: params.newTickLower,
+                newTickUpper: params.newTickUpper,
+                liquidityToMove: params.liquidityToMove,
+                assetASparkTransferId: assetATransferId,
+                assetBSparkTransferId: assetBTransferId,
+                additionalAmountA: params.additionalAmountA,
+                additionalAmountB: params.additionalAmountB,
+                retainInBalance: params.retainInBalance,
+                nonce,
+                signature: getHexFromUint8Array(signature),
+            };
+            const response = await this.typedApi.rebalancePosition(request);
+            if (!response.accepted) {
+                const errorMessage = response.error || "Rebalance position rejected by the AMM";
+                throw new FlashnetError(errorMessage, {
+                    response: {
+                        errorCode: "UNKNOWN",
+                        errorCategory: "System",
+                        message: errorMessage,
+                        requestId: response.requestId || "",
+                        timestamp: new Date().toISOString(),
+                        service: "amm-gateway",
+                        severity: "Error",
+                    },
+                    httpStatus: 400,
+                    transferIds,
+                    lpIdentityPublicKey: params.poolId,
+                });
+            }
+            return response;
+        };
+        // Use auto-clawback if we made transfers
+        if (transferIds.length > 0) {
+            return this.executeWithAutoClawback(executeRebalance, transferIds, params.poolId);
+        }
+        return executeRebalance();
+    }
+    /**
+     * List V3 concentrated liquidity positions
+     *
+     * @param query Optional query parameters
+     * @param query.poolId - Filter by pool ID
+     * @param query.page - Page number (default: 1)
+     * @param query.pageSize - Page size (default: 20, max: 100)
+     */
+    async listConcentratedPositions(query) {
+        await this.ensureInitialized();
+        return this.typedApi.listConcentratedPositions(query);
+    }
+    /**
+     * Get pool liquidity distribution for visualization
+     *
+     * Returns aggregated liquidity ranges for visualizing the liquidity distribution.
+     *
+     * @param poolId - Pool ID (LP identity public key)
+     */
+    async getPoolLiquidity(poolId) {
+        await this.ensureInitialized();
+        return this.typedApi.getPoolLiquidity(poolId);
+    }
+    /**
+     * Get pool ticks for simulation
+     *
+     * Returns all initialized ticks with their liquidity deltas for swap simulation.
+     *
+     * @param poolId - Pool ID (LP identity public key)
+     */
+    async getPoolTicks(poolId) {
+        await this.ensureInitialized();
+        return this.typedApi.getPoolTicks(poolId);
+    }
+    // V3 Free Balance Methods
+    /**
+     * Get user's free balance for a specific V3 pool
+     *
+     * Returns the user's current free balance in the pool, which can be used for
+     * liquidity operations without needing to transfer from the wallet.
+     *
+     * @param poolId - Pool ID (LP identity public key)
+     */
+    async getConcentratedBalance(poolId) {
+        await this.ensureInitialized();
+        return this.typedApi.getConcentratedBalance(poolId);
+    }
+    /**
+     * Get user's free balances across all V3 pools
+     *
+     * Returns all free balances for the authenticated user across all V3 pools.
+     */
+    async getConcentratedBalances() {
+        await this.ensureInitialized();
+        return this.typedApi.getConcentratedBalances();
+    }
+    /**
+     * Withdraw free balance from a V3 pool to user's Spark wallet
+     *
+     * Withdraws accumulated free balance from a pool. Use "0" to skip an asset,
+     * or "max" to withdraw all available balance of that asset.
+     *
+     * @param params Withdrawal parameters
+     * @param params.poolId - Pool ID (LP identity public key)
+     * @param params.amountA - Amount of asset A to withdraw ("0" to skip, "max" to withdraw all)
+     * @param params.amountB - Amount of asset B to withdraw ("0" to skip, "max" to withdraw all)
+     */
+    async withdrawConcentratedBalance(params) {
+        await this.ensureInitialized();
+        // Generate intent
+        const nonce = generateNonce();
+        const intentMessage = generateWithdrawBalanceIntentMessage({
+            userPublicKey: this.publicKey,
+            lpIdentityPublicKey: params.poolId,
+            amountA: params.amountA,
+            amountB: params.amountB,
+            nonce,
+        });
+        // Sign intent
+        const messageHash = sha256(intentMessage);
+        const signature = await this._wallet.config.signer.signMessageWithIdentityKey(messageHash, true);
+        const request = {
+            poolId: params.poolId,
+            amountA: params.amountA,
+            amountB: params.amountB,
+            nonce,
+            signature: getHexFromUint8Array(signature),
+        };
+        const response = await this.typedApi.withdrawConcentratedBalance(request);
+        if (!response.accepted) {
+            const errorMessage = response.error || "Withdraw balance rejected by the AMM";
+            throw new Error(errorMessage);
+        }
+        return response;
+    }
 }
 
 export { FlashnetClient };