@pafi-dev/trading 0.9.0 → 0.10.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Address, PublicClient, Hex, WalletClient, TransactionReceipt } from 'viem';
-import { PartialUserOperation, PoolKey, V3Path, BestQuote, ExactOutputBestQuote, QuoteResult, ExactOutputQuoteResult, BROKER_HASHES } from '@pafi-dev/core';
+import { PartialUserOperation, PoolKey, V3Path, BestQuote, ExactOutputBestQuote, QuoteResult, ExactOutputQuoteResult, BROKER_HASHES, Operation } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL, fetchPafiPools } from '@pafi-dev/core';
 
 interface ApiQuoteRequest {
@@ -291,6 +291,65 @@ interface ApiPerpDepositResponse {
     /** Relay address used. Same as `vaultAddress` when `path === "vault"`. */
     relayAddress: Address;
 }
+interface ApiErc20TransferRequest {
+    chainId: number;
+    userAddress: Address;
+    /** Token to transfer — must be USDC, USDT, or an active PointToken. */
+    tokenAddress: Address;
+    /**
+     * Final recipient. Rejected when:
+     *   - equals `getContractAddresses(chainId).pafiFeeRecipient` (self-fee abuse), or
+     *   - equals `0x0000...0000` (use the burn scenario for that).
+     */
+    recipient: Address;
+    /** Token-native units (6-dec for stables, 18-dec for PT). Must be > 0. */
+    amount: bigint;
+    /** ERC-4337 account nonce for the user's EOA (from EntryPoint). */
+    aaNonce: bigint;
+    /**
+     * Operator fee in the SAME token. Paid as a transfer to
+     * `pafiFeeRecipient` prepended to the batch.
+     *
+     * - `undefined` (default): auto-quote via `quoteOperatorFeeForTransfer`.
+     * - `0n`: strip fee transfer (forces single-call no-fee userOp).
+     * - explicit `bigint`: override (use a tighter Pimlico-derived
+     *   estimate if you have one).
+     */
+    feeAmount?: bigint;
+    /**
+     * Opt-in fallback when Chainlink / subgraph are unavailable during
+     * auto-quote. Default `false` — fails loud with the oracle's error so
+     * production knows to alert. Set `true` AND optionally configure
+     * `fallbackPtPriceUsdt` to absorb dev/staging RPC outages.
+     *
+     * Stable tokens (USDC/USDT) only use Chainlink; PT routes through both
+     * Chainlink and the V3 pool subgraph. Fallback applies to whichever
+     * fails. See `QuoteOperatorFeeForTransferConfig.allowStaleFallback`.
+     *
+     * Only consulted when `feeAmount` is undefined (auto-quote path).
+     */
+    allowStaleFallback?: boolean;
+    /** Fallback ETH price (USD) when Chainlink fails. Default 3000. */
+    fallbackEthPriceUsd?: number;
+    /** Fallback PT price (USDT per 1 PT) when subgraph fails. Default 0.1. */
+    fallbackPtPriceUsdt?: number;
+}
+interface ApiErc20TransferResponse {
+    /** Sponsored variant — 2 calls (fee transfer + actual transfer). */
+    userOp: PartialUserOperation;
+    /**
+     * Fee-stripped fallback variant — 1 call (transfer only). Emitted
+     * only when `feeAmount > 0n`. Submit when the paymaster refuses;
+     * user pays ETH gas directly. Same nonce as `userOp`.
+     */
+    userOpFallback?: PartialUserOperation;
+    /** Resolved operator fee in the same token. `0n` when no-fee mode. */
+    feeAmountUsed: bigint;
+    /** Recipient used for the fee transfer (= `pafiFeeRecipient`). */
+    feeRecipient: Address;
+    /** Echo of `tokenAddress` (checksummed). Use as a sanity tag in FE logs. */
+    tokenAddress: Address;
+}
 
 interface TradingHandlersConfig {
     provider: PublicClient;
@@ -396,6 +455,30 @@ declare class TradingHandlers {
      * sentinel (Relay not deployed for that chain).
      */
     handlePerpDeposit(authenticatedAddress: Address, request: ApiPerpDepositRequest): Promise<ApiPerpDepositResponse>;
+    /**
+     * Build a sponsored ERC-20 transfer UserOp pair (sponsored + fallback).
+     *
+     * Sponsored variant: `[token.transfer(PAFI, fee), token.transfer(recipient, amount)]`.
+     * Fallback variant: `[token.transfer(recipient, amount)]` (user pays ETH).
+     *
+     * Both calls hit the SAME token contract — fee currency equals the
+     * token being sent, so the user needs only ONE token (≥ `amount + fee`)
+     * to complete a gasless send.
+     *
+     * Allowlist enforced HERE (client-side fail-fast) **and** server-side
+     * by sponsor-relayer's IntentValidator:
+     *   - USDC (`getContractAddresses(chainId).usdc`)
+     *   - USDT (`getContractAddresses(chainId).usdt`)
+     *   - active PointToken (caller responsibility to check
+     *     `IssuerRegistry.isActiveByPointToken` if not stable)
+     *
+     * Recipient rejected when equal to `pafiFeeRecipient` (self-fee abuse)
+     * or `0x0` (use the burn scenario for that).
+     *
+     * See `docs/SPONSORED_ERC20_TRANSFER_SPEC.md` for the full call
+     * pattern, error codes, and edge cases.
+     */
+    handleErc20Transfer(authenticatedAddress: Address, request: ApiErc20TransferRequest): Promise<ApiErc20TransferResponse>;
 }
 
 declare function checkAllowance(client: PublicClient, token: Address, owner: Address, spender: Address): Promise<bigint>;
@@ -1007,4 +1090,1249 @@ interface PerpDepositDirectResult {
  */
 declare function perpDepositDirect(params: PerpDepositDirectParams): Promise<PerpDepositDirectResult>;
 
-export { type ApiPerpDepositRequest, type ApiPerpDepositResponse, type ApiQuoteError, type ApiQuoteExactOutRequest, type ApiQuoteExactOutResponse, type ApiQuoteRequest, type ApiQuoteResponse, type ApiSwapExactOutRequest, type ApiSwapExactOutResponse, type ApiSwapRequest, type ApiSwapResponse, type BuildSwapUserOpExactOutParams, type BuildSwapUserOpParams, type PerpDepositDirectParams, type PerpDepositDirectResult, type SwapDirectExactOutParams, type SwapDirectExactOutResult, type SwapDirectParams, type SwapDirectResult, type SwapSimulationResult, TradingHandlers, type TradingHandlersConfig, V3_SWAP_EXACT_IN, V3_SWAP_EXACT_OUT, buildAllPaths, buildErc20ApprovalCalldata, buildPermit2ApprovalCalldata, buildSwapUserOp, buildSwapUserOpExactOut, buildUniversalRouterExecuteArgs, buildUniversalRouterExecuteArgsExactOut, buildV3SwapInputExactIn, buildV3SwapInputExactOut, checkAllowance, combineRoutes, findBestQuote, findBestQuoteExactOut, perpDepositDirect, quoteBestRoute, quoteBestRouteExactOut, quoteExactInput, quoteExactInputSingle, quoteExactOutput, quoteExactOutputSingle, simulateSwap, swapDirect, swapDirectExactOut };
+interface AddLiquidityDirectParams {
+    /** User EOA — must be EIP-7702 delegated. */
+    userAddress: Address;
+    chainId: number;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    /** Pool token0 (must be sorted < token1). */
+    token0: Address;
+    /** Pool token1. */
+    token1: Address;
+    /** V3 fee tier (e.g. 500, 3000, 10000). */
+    fee: number;
+    /** Position range — both ticks must be multiples of the pool's tickSpacing. */
+    tickLower: number;
+    tickUpper: number;
+    /** Caller pins ONE side; the other is computed by the SDK. */
+    amount0Desired?: bigint;
+    amount1Desired?: bigint;
+    /** bps, default 50. Capped at 10000. */
+    slippageBps?: number;
+    /** Unix seconds. Default `now + 5min`. */
+    deadline?: bigint;
+    /** Wait for receipt + parse tokenId. Default `true`. */
+    waitForReceipt?: boolean;
+    onWarning?: (msg: string) => void;
+}
+interface AddLiquidityDirectResult {
+    txHash: Hex;
+    receipt?: TransactionReceipt;
+    /** Newly-minted position NFT id. Available when `waitForReceipt !== false`. */
+    tokenId?: bigint;
+    /** Amount0 baked into the calldata (after estimation). */
+    amount0Desired: bigint;
+    amount1Desired: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+    /** L value computed off-chain from amounts + range. Informational. */
+    liquidity: bigint;
+    deadline: bigint;
+}
+/**
+ * One-shot helper for the **FE-direct add-liquidity** path — no AA, no
+ * bundler, no PAFI sponsor-relayer. The user EOA pays gas in ETH and
+ * broadcasts a single type-2 transaction calling its own EIP-7702
+ * delegated bytecode (`Simple7702Account.executeBatch`).
+ *
+ * Flow:
+ *   1. Validate inputs (tick range, single-amount guard, slippage).
+ *   2. Verify the EOA is EIP-7702 delegated.
+ *   3. Read pool state (sqrtPriceX96).
+ *   4. Estimate the other side's amount + liquidity from one pinned side.
+ *   5. Apply slippage → (amount0Min, amount1Min).
+ *   6. Build 3-op batch: approve token0, approve token1, NPM.mint.
+ *   7. Send native tx.
+ *   8. Wait receipt + parse `Transfer(0x0 → user, tokenId)` → return tokenId.
+ *
+ * @example
+ * ```ts
+ * const result = await addLiquidityDirect({
+ *   userAddress: wallet.address,
+ *   chainId: 8453,
+ *   publicClient,
+ *   walletClient,
+ *   token0: PT,
+ *   token1: USDC,
+ *   fee: 3000,
+ *   tickLower: -60000,
+ *   tickUpper: -54000,
+ *   amount0Desired: parseUnits("100", 18),
+ * });
+ * console.log("Minted position:", result.tokenId);
+ * ```
+ */
+declare function addLiquidityDirect(params: AddLiquidityDirectParams): Promise<AddLiquidityDirectResult>;
+
+interface IncreaseLiquidityDirectParams {
+    userAddress: Address;
+    chainId: number;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    /** Existing position NFT id. SDK reads its range + token pair. */
+    tokenId: bigint;
+    amount0Desired?: bigint;
+    amount1Desired?: bigint;
+    slippageBps?: number;
+    deadline?: bigint;
+    waitForReceipt?: boolean;
+    onWarning?: (msg: string) => void;
+}
+interface IncreaseLiquidityDirectResult {
+    txHash: Hex;
+    receipt?: TransactionReceipt;
+    amount0Desired: bigint;
+    amount1Desired: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+    /** L added (estimated off-chain; receipt-parsed value would be authoritative). */
+    liquidityAdded: bigint;
+    deadline: bigint;
+}
+/**
+ * Top up an existing V3 LP position via NPM.increaseLiquidity.
+ *
+ * Range comes from the existing position; user only specifies one side's
+ * amount and the SDK computes the rest. Same 3-op batch as add (two
+ * approvals + the NPM call), but range is read on-chain rather than
+ * supplied by caller.
+ */
+declare function increaseLiquidityDirect(params: IncreaseLiquidityDirectParams): Promise<IncreaseLiquidityDirectResult>;
+
+interface RemoveLiquidityDirectParams {
+    userAddress: Address;
+    chainId: number;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    tokenId: bigint;
+    /** How much L to withdraw. Pass `liquidity` OR `liquidityBps`. Exactly one. */
+    liquidity?: bigint;
+    /** 0..10000 — percentage of current liquidity to remove. */
+    liquidityBps?: number;
+    slippageBps?: number;
+    deadline?: bigint;
+    waitForReceipt?: boolean;
+    onWarning?: (msg: string) => void;
+}
+interface RemoveLiquidityDirectResult {
+    txHash: Hex;
+    receipt?: TransactionReceipt;
+    liquidityRemoved: bigint;
+    amount0Expected: bigint;
+    amount1Expected: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+    deadline: bigint;
+}
+/**
+ * Partial withdraw from an existing V3 LP position.
+ *
+ * Batch shape:
+ *   1. NPM.decreaseLiquidity({ tokenId, liquidity, amount0Min, amount1Min, deadline })
+ *   2. NPM.collect({ tokenId, recipient: userAddress, amount0Max: MAX, amount1Max: MAX })
+ *
+ * No approvals — NPM doesn't pull tokens on remove. The collect leg is
+ * mandatory because decrease only credits `tokensOwed*`; tokens stay in
+ * the NPM until the user collects them.
+ */
+declare function removeLiquidityDirect(params: RemoveLiquidityDirectParams): Promise<RemoveLiquidityDirectResult>;
+
+interface ClosePositionDirectParams {
+    userAddress: Address;
+    chainId: number;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    tokenId: bigint;
+    slippageBps?: number;
+    deadline?: bigint;
+    waitForReceipt?: boolean;
+    onWarning?: (msg: string) => void;
+}
+interface ClosePositionDirectResult {
+    txHash: Hex;
+    receipt?: TransactionReceipt;
+    liquidityRemoved: bigint;
+    amount0Expected: bigint;
+    amount1Expected: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+    deadline: bigint;
+}
+/**
+ * Full close: decrease all liquidity (if any) + collect fees + burn the
+ * position NFT. The SDK picks the batch shape from current position state:
+ *
+ *   - liquidity > 0:                  decrease(all) → collect → burn   (3 ops)
+ *   - liquidity == 0 + fees > 0:      collect → burn                   (2 ops)
+ *   - liquidity == 0 + no fees:       burn                             (1 op)
+ *
+ * Useful for cleaning up an LP NFT off the user's EOA after they're done.
+ */
+declare function closePositionDirect(params: ClosePositionDirectParams): Promise<ClosePositionDirectResult>;
+
+interface CollectFeesDirectParams {
+    userAddress: Address;
+    chainId: number;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    tokenId: bigint;
+    /** Recipient of the collected fees. Default `userAddress`. */
+    recipient?: Address;
+    waitForReceipt?: boolean;
+    onWarning?: (msg: string) => void;
+}
+interface CollectFeesDirectResult {
+    txHash: Hex;
+    receipt?: TransactionReceipt;
+    /** Pre-tx estimate (tokensOwed + pending). Actual transferred amount in the receipt's Collect log. */
+    amount0Expected: bigint;
+    amount1Expected: bigint;
+    recipient: Address;
+}
+/**
+ * Collect accrued fees from a position without changing its liquidity.
+ *
+ * Single-op batch (`NPM.collect`). NPM internally calls
+ * `pool.burn(tickLower, tickUpper, 0)` when the position has active
+ * liquidity, which flushes newly-accrued swap fees from the pool into
+ * the position's `tokensOwed*` before transferring them out.
+ *
+ * The estimate combines `position.tokensOwed*` (already in NPM) with the
+ * "pending" fees still in the pool (derived off-chain from feeGrowth
+ * deltas). The actual transferred amount comes from the on-chain
+ * `Collect` event in the receipt and may differ slightly if another
+ * tx accrued more fees between the read and mine.
+ */
+declare function collectFeesDirect(params: CollectFeesDirectParams): Promise<CollectFeesDirectResult>;
+
+/**
+ * Uniswap V3 NonfungiblePositionManager (NPM) ABI — subset used by the
+ * `@pafi-dev/trading` liquidity flows. PAFI deployment lives at
+ * `V3_NPM_ADDRESSES[chainId]`.
+ *
+ * Hand-authored (not generated) — same convention as `v3QuoterV2Abi` in
+ * `@pafi-dev/core`. Only the methods + events the SDK actually uses are
+ * declared, to keep the surface small and the type narrowing precise.
+ *
+ * Intentionally omitted: `multicall`, `WETH9`, `refundETH`, `sweepToken`,
+ * `unwrapWETH9` (ETH wrap helpers — out of v1 scope), `tokenURI`, `name`,
+ * `symbol`, `tokenOfOwnerByIndex` (ERC-721 metadata + enumerable — position
+ * listing is the consumer backend's job), `permit`, `safeTransferFrom`.
+ */
+declare const nonfungiblePositionManagerAbi: readonly [{
+    readonly type: "function";
+    readonly name: "mint";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "token0";
+            readonly type: "address";
+        }, {
+            readonly name: "token1";
+            readonly type: "address";
+        }, {
+            readonly name: "fee";
+            readonly type: "uint24";
+        }, {
+            readonly name: "tickLower";
+            readonly type: "int24";
+        }, {
+            readonly name: "tickUpper";
+            readonly type: "int24";
+        }, {
+            readonly name: "amount0Desired";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount1Desired";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount0Min";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount1Min";
+            readonly type: "uint256";
+        }, {
+            readonly name: "recipient";
+            readonly type: "address";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "liquidity";
+        readonly type: "uint128";
+    }, {
+        readonly name: "amount0";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "increaseLiquidity";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenId";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount0Desired";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount1Desired";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount0Min";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount1Min";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "liquidity";
+        readonly type: "uint128";
+    }, {
+        readonly name: "amount0";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "decreaseLiquidity";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenId";
+            readonly type: "uint256";
+        }, {
+            readonly name: "liquidity";
+            readonly type: "uint128";
+        }, {
+            readonly name: "amount0Min";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount1Min";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amount0";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "collect";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenId";
+            readonly type: "uint256";
+        }, {
+            readonly name: "recipient";
+            readonly type: "address";
+        }, {
+            readonly name: "amount0Max";
+            readonly type: "uint128";
+        }, {
+            readonly name: "amount1Max";
+            readonly type: "uint128";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amount0";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "burn";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "positions";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "nonce";
+        readonly type: "uint96";
+    }, {
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "token0";
+        readonly type: "address";
+    }, {
+        readonly name: "token1";
+        readonly type: "address";
+    }, {
+        readonly name: "fee";
+        readonly type: "uint24";
+    }, {
+        readonly name: "tickLower";
+        readonly type: "int24";
+    }, {
+        readonly name: "tickUpper";
+        readonly type: "int24";
+    }, {
+        readonly name: "liquidity";
+        readonly type: "uint128";
+    }, {
+        readonly name: "feeGrowthInside0LastX128";
+        readonly type: "uint256";
+    }, {
+        readonly name: "feeGrowthInside1LastX128";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tokensOwed0";
+        readonly type: "uint128";
+    }, {
+        readonly name: "tokensOwed1";
+        readonly type: "uint128";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "factory";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "Transfer";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "IncreaseLiquidity";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "liquidity";
+        readonly type: "uint128";
+        readonly indexed: false;
+    }, {
+        readonly name: "amount0";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "DecreaseLiquidity";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "liquidity";
+        readonly type: "uint128";
+        readonly indexed: false;
+    }, {
+        readonly name: "amount0";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "Collect";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "recipient";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "amount0";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}];
+
+/**
+ * Uniswap V3 Pool ABI — read-only subset used by the
+ * `@pafi-dev/trading` liquidity flows to estimate amounts off-chain.
+ *
+ * Pool addresses are derived from `V3_FACTORY_ADDRESSES` +
+ * `V3_POOL_INIT_CODE_HASH` (both in `@pafi-dev/core`) via
+ * `computeV3PoolAddress()`.
+ *
+ * Intentionally omitted: pool-direct write methods (`swap`, `flash`,
+ * `mint`, `burn`, `collect`) — every write call goes through NPM, never
+ * the pool. Also omitted: `positions(bytes32)` (NPM-side is the canonical
+ * read), `protocolFees`, `observe`, `snapshotCumulativesInside`.
+ */
+declare const v3PoolAbi: readonly [{
+    readonly type: "function";
+    readonly name: "token0";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "token1";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "slot0";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "sqrtPriceX96";
+        readonly type: "uint160";
+    }, {
+        readonly name: "tick";
+        readonly type: "int24";
+    }, {
+        readonly name: "observationIndex";
+        readonly type: "uint16";
+    }, {
+        readonly name: "observationCardinality";
+        readonly type: "uint16";
+    }, {
+        readonly name: "observationCardinalityNext";
+        readonly type: "uint16";
+    }, {
+        readonly name: "feeProtocol";
+        readonly type: "uint8";
+    }, {
+        readonly name: "unlocked";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "liquidity";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint128";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "tickSpacing";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "int24";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "fee";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint24";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "feeGrowthGlobal0X128";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "feeGrowthGlobal1X128";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "ticks";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tick";
+        readonly type: "int24";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "liquidityGross";
+        readonly type: "uint128";
+    }, {
+        readonly name: "liquidityNet";
+        readonly type: "int128";
+    }, {
+        readonly name: "feeGrowthOutside0X128";
+        readonly type: "uint256";
+    }, {
+        readonly name: "feeGrowthOutside1X128";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tickCumulativeOutside";
+        readonly type: "int56";
+    }, {
+        readonly name: "secondsPerLiquidityOutsideX128";
+        readonly type: "uint160";
+    }, {
+        readonly name: "secondsOutside";
+        readonly type: "uint56";
+    }, {
+        readonly name: "initialized";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "tickBitmap";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wordPosition";
+        readonly type: "int16";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}];
+
+/**
+ * PAFI's V3 NonfungiblePositionManager (NPM) per chain. All LP flows
+ * encode calls against this address.
+ *
+ * Source of truth: `contracts.md` at the repo root.
+ */
+declare const V3_NPM_ADDRESSES: Record<number, Address>;
+/**
+ * uint128 ceiling. Used as `amount0Max` / `amount1Max` on
+ * `NPM.collect(...)` to mean "transfer everything owed."
+ */
+declare const UINT128_MAX: bigint;
+
+/**
+ * Uniswap V3 liquidity math — hand-rolled bigint primitives.
+ *
+ * Mirrors the algorithms in `@uniswap/v3-sdk` (TickMath, SqrtPriceMath,
+ * LiquidityAmounts) without taking the package as a runtime dependency.
+ * Unit tests cross-check golden values against the upstream SDK; the
+ * runtime trades a ~200 LoC implementation for zero new dependencies.
+ *
+ * All functions are pure and side-effect-free.
+ */
+/** Minimum tick allowed by the V3 tick range. */
+declare const MIN_TICK = -887272;
+/** Maximum tick allowed by the V3 tick range. */
+declare const MAX_TICK = 887272;
+/** sqrtPriceX96 at MIN_TICK. */
+declare const MIN_SQRT_RATIO: bigint;
+/** sqrtPriceX96 at MAX_TICK. */
+declare const MAX_SQRT_RATIO: bigint;
+/** 2^96 — the X96 scaling factor. */
+declare const Q96: bigint;
+/** 2^192 — used in sqrt² → ratio conversions. */
+declare const Q192: bigint;
+/**
+ * Convert a tick to its sqrtPriceX96, using V3's exact lookup-table
+ * algorithm. Equivalent to `TickMath.getSqrtRatioAtTick(tick)`.
+ *
+ * @throws if `tick` is outside `[MIN_TICK, MAX_TICK]`
+ */
+declare function tickToSqrtPriceX96(tick: number): bigint;
+/**
+ * Convert a sqrtPriceX96 back to the largest tick whose
+ * `tickToSqrtPriceX96(tick)` is <= the input. Inverse of
+ * `tickToSqrtPriceX96`, equivalent to
+ * `TickMath.getTickAtSqrtRatio(sqrtPriceX96)`.
+ *
+ * Uses a most-significant-bit (MSB) search + iterative refinement.
+ *
+ * @throws if `sqrtPriceX96` is outside `[MIN_SQRT_RATIO, MAX_SQRT_RATIO)`
+ */
+declare function sqrtPriceX96ToTick(sqrtPriceX96: bigint): number;
+/**
+ * Snap a tick to the nearest multiple of `tickSpacing` (rounds toward
+ * zero). Use to convert a user-entered tick to one the pool will accept.
+ */
+declare function nearestUsableTick(tick: number, tickSpacing: number): number;
+/** Minimum tick aligned to `tickSpacing`, clipped to `MIN_TICK`. */
+declare function minUsableTick(tickSpacing: number): number;
+/** Maximum tick aligned to `tickSpacing`, clipped to `MAX_TICK`. */
+declare function maxUsableTick(tickSpacing: number): number;
+/**
+ * Standard fee-tier → tickSpacing mapping. Matches Uniswap V3 mainnet
+ * conventions and is verified on-chain for PAFI's V3-fork deployment.
+ * Returns `undefined` for non-standard fees; the caller should then read
+ * `factory.feeAmountTickSpacing(fee)` to be safe.
+ */
+declare function tickSpacingForFee(fee: number): number | undefined;
+/**
+ * Convert a human-readable price (`token1` per `token0`) to a tick.
+ * Decimals are factored in so callers can pass real-world quantities.
+ *
+ * Returned tick may need `nearestUsableTick()` to be pool-valid.
+ */
+declare function priceToTick(params: {
+    price: number;
+    token0Decimals: number;
+    token1Decimals: number;
+}): number;
+/**
+ * Convert a tick back to a human-readable price (`token1` per `token0`).
+ * Inverse of `priceToTick`.
+ */
+declare function tickToPrice(params: {
+    tick: number;
+    token0Decimals: number;
+    token1Decimals: number;
+}): number;
+/**
+ * Token0 amount required to provide `liquidity` over [sqrtL, sqrtU].
+ * Matches `SqrtPriceMath.getAmount0Delta(..., roundUp=true)` from V3.
+ */
+declare function getAmount0ForLiquidity(sqrtPriceX96Lower: bigint, sqrtPriceX96Upper: bigint, liquidity: bigint): bigint;
+/**
+ * Token1 amount required to provide `liquidity` over [sqrtL, sqrtU].
+ * Matches `SqrtPriceMath.getAmount1Delta(..., roundUp=true)` from V3.
+ */
+declare function getAmount1ForLiquidity(sqrtPriceX96Lower: bigint, sqrtPriceX96Upper: bigint, liquidity: bigint): bigint;
+/**
+ * Canonical "given liquidity + range + current price, compute amounts"
+ * helper. Handles the three V3 cases (current below, in, or above range).
+ */
+declare function getAmountsForLiquidity(params: {
+    sqrtPriceX96Current: bigint;
+    sqrtPriceX96Lower: bigint;
+    sqrtPriceX96Upper: bigint;
+    liquidity: bigint;
+}): {
+    amount0: bigint;
+    amount1: bigint;
+};
+/**
+ * Liquidity that `amount0` of token0 would buy over [sqrtL, sqrtU].
+ * Used when the user pins `amount0Desired` and the range is at-or-below
+ * current price.
+ */
+declare function getLiquidityForAmount0(sqrtPriceX96Lower: bigint, sqrtPriceX96Upper: bigint, amount0: bigint): bigint;
+/**
+ * Liquidity that `amount1` of token1 would buy over [sqrtL, sqrtU].
+ * Used when the user pins `amount1Desired` and the range is at-or-above
+ * current price.
+ */
+declare function getLiquidityForAmount1(sqrtPriceX96Lower: bigint, sqrtPriceX96Upper: bigint, amount1: bigint): bigint;
+/**
+ * High-level estimator. Caller has current spot + range + ONE side's
+ * amount; returns the liquidity and the matching amounts.
+ *
+ * Branches:
+ *   - Current spot below range → amount0 drives, amount1 = 0.
+ *   - Current spot above range → amount1 drives, amount0 = 0.
+ *   - Current spot in range    → caller's pinned side drives liquidity;
+ *                                the other side is recomputed from that
+ *                                liquidity at the current price.
+ *
+ * @throws if neither or both of amount0Desired / amount1Desired are set,
+ *   or if the pinned side is incompatible with the position
+ *   (e.g. amount1 pinned but spot < range).
+ */
+declare function estimateLiquidityFromOneSide(params: {
+    sqrtPriceX96Current: bigint;
+    sqrtPriceX96Lower: bigint;
+    sqrtPriceX96Upper: bigint;
+    amount0Desired?: bigint;
+    amount1Desired?: bigint;
+}): {
+    liquidity: bigint;
+    amount0: bigint;
+    amount1: bigint;
+};
+/**
+ * Apply slippage to `(amount0Desired, amount1Desired)` for an add or
+ * increase, returning the `(amount0Min, amount1Min)` tuple to send to
+ * NPM. Floor div — the on-chain minimum must round DOWN for safety.
+ */
+declare function applyMintSlippage(params: {
+    amount0Desired: bigint;
+    amount1Desired: bigint;
+    slippageBps: number;
+}): {
+    amount0Min: bigint;
+    amount1Min: bigint;
+};
+/**
+ * Apply slippage to expected `(amount0, amount1)` for a decrease/close,
+ * returning `(amount0Min, amount1Min)` to send to NPM. Floor div, same
+ * rationale as `applyMintSlippage`.
+ */
+declare function applyRemoveSlippage(params: {
+    amount0Expected: bigint;
+    amount1Expected: bigint;
+    slippageBps: number;
+}): {
+    amount0Min: bigint;
+    amount1Min: bigint;
+};
+
+/**
+ * Decoded `NPM.positions(tokenId)` row.
+ *
+ * Fields mirror the 12-tuple returned by the contract, named for
+ * readability. `feeGrowthInside*LastX128` are Q128.128 fixed-point —
+ * used together with `pool.feeGrowthGlobal*X128()` and `pool.ticks(...)`
+ * to derive pending fees in `collectFeesDirect`.
+ */
+interface PositionInfo {
+    nonce: bigint;
+    operator: Address;
+    token0: Address;
+    token1: Address;
+    fee: number;
+    tickLower: number;
+    tickUpper: number;
+    liquidity: bigint;
+    feeGrowthInside0LastX128: bigint;
+    feeGrowthInside1LastX128: bigint;
+    tokensOwed0: bigint;
+    tokensOwed1: bigint;
+}
+/**
+ * Read an NFT position's state by tokenId.
+ *
+ * @param client viem PublicClient
+ * @param npm NonfungiblePositionManager address (`V3_NPM_ADDRESSES[chainId]`)
+ * @param tokenId The NFT id
+ */
+declare function readPosition(client: PublicClient, npm: Address, tokenId: bigint): Promise<PositionInfo>;
+
+/**
+ * Distilled V3 pool state — the fields LP flows need to estimate amounts
+ * and validate ticks.
+ */
+interface PoolState {
+    sqrtPriceX96: bigint;
+    /** Current tick (`int24` from slot0). */
+    tick: number;
+    /** In-range liquidity at the current tick. */
+    liquidity: bigint;
+    tickSpacing: number;
+    /** Fee tier in hundredths of a basis point (e.g. `3000` = 0.3%). */
+    fee: number;
+}
+/**
+ * Per-tick state read from `pool.ticks(tick)`. Only the fields LP flows
+ * use are kept; the rest of the tuple is dropped.
+ */
+interface TickInfo {
+    liquidityGross: bigint;
+    liquidityNet: bigint;
+    feeGrowthOutside0X128: bigint;
+    feeGrowthOutside1X128: bigint;
+    initialized: boolean;
+}
+/**
+ * Pool fee-growth globals — used together with `TickInfo` and the
+ * position's `feeGrowthInside*LastX128` to compute pending fees.
+ */
+interface PoolFeeGrowthGlobals {
+    feeGrowthGlobal0X128: bigint;
+    feeGrowthGlobal1X128: bigint;
+}
+/**
+ * Read a pool's current state in a single multicall.
+ *
+ * @param client viem PublicClient
+ * @param pool Pool address (use `computeV3PoolAddress` to derive)
+ */
+declare function readPoolState(client: PublicClient, pool: Address, 
+/** Pin reads to this block. Default: latest (matches prior behavior). */
+blockNumber?: bigint): Promise<PoolState>;
+/**
+ * Read tick info for `tickLower` and `tickUpper` in a single multicall.
+ *
+ * Used by `collectFeesDirect` to compute `feeGrowthInside*` (and from
+ * that, the pending-fee estimate).
+ */
+declare function readTicksAt(client: PublicClient, pool: Address, tickLower: number, tickUpper: number): Promise<{
+    lower: TickInfo;
+    upper: TickInfo;
+}>;
+/**
+ * Read pool fee-growth globals.
+ *
+ * Could be folded into `readPoolState` but kept separate so that flows
+ * which don't need fee tracking (mint, decrease) don't waste an RPC on
+ * the extra two reads.
+ */
+declare function readFeeGrowthGlobals(client: PublicClient, pool: Address): Promise<PoolFeeGrowthGlobals>;
+
+interface BuildMintParams {
+    /** NonfungiblePositionManager address (`V3_NPM_ADDRESSES[chainId]`). */
+    npm: Address;
+    token0: Address;
+    token1: Address;
+    fee: number;
+    tickLower: number;
+    tickUpper: number;
+    /** Exact amount0 caller is approving + sending. */
+    amount0Desired: bigint;
+    /** Exact amount1 caller is approving + sending. */
+    amount1Desired: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+    /** Position NFT recipient — typically the user's EOA. */
+    recipient: Address;
+    /** Unix seconds. NPM reverts if `block.timestamp > deadline`. */
+    deadline: bigint;
+}
+/**
+ * Build the 3-op batch for `addLiquidityDirect`:
+ *
+ *   1. token0.approve(NPM, amount0Desired)
+ *   2. token1.approve(NPM, amount1Desired)
+ *   3. NPM.mint({ ... })
+ *
+ * Approvals are per-call exact (not `max`) — leaves zero residual
+ * allowance after the batch, preventing a stale approve from being
+ * front-run on a later mint.
+ *
+ * Caller is responsible for ordering `token0 < token1` (V3 invariant);
+ * this builder doesn't sort, since the desired/min amounts are
+ * positional and re-sorting would break them.
+ */
+declare function buildMint(params: BuildMintParams): Operation[];
+
+interface BuildIncreaseLiquidityParams {
+    npm: Address;
+    token0: Address;
+    token1: Address;
+    tokenId: bigint;
+    amount0Desired: bigint;
+    amount1Desired: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+    deadline: bigint;
+}
+/**
+ * Build the 3-op batch for `increaseLiquidityDirect`:
+ *
+ *   1. token0.approve(NPM, amount0Desired)
+ *   2. token1.approve(NPM, amount1Desired)
+ *   3. NPM.increaseLiquidity({ tokenId, ... })
+ *
+ * Range comes from the existing position — caller resolves it via
+ * `readPosition(tokenId)` before calling this builder.
+ */
+declare function buildIncreaseLiquidity(params: BuildIncreaseLiquidityParams): Operation[];
+
+interface BuildDecreaseLiquidityParams {
+    npm: Address;
+    tokenId: bigint;
+    liquidity: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+    deadline: bigint;
+}
+/**
+ * Build a single `NPM.decreaseLiquidity({ ... })` Operation.
+ *
+ * No approvals needed — NPM doesn't pull tokens on decrease (it credits
+ * the position's `tokensOwed0/1`, which a subsequent `collect()` flushes
+ * to the recipient).
+ */
+declare function buildDecreaseLiquidity(params: BuildDecreaseLiquidityParams): Operation;
+
+interface BuildCollectParams {
+    npm: Address;
+    tokenId: bigint;
+    /** Where the collected fees + principal go. Typically the user's EOA. */
+    recipient: Address;
+    /** Caps on the transfer. Default `UINT128_MAX` → take everything owed. */
+    amount0Max?: bigint;
+    amount1Max?: bigint;
+}
+/**
+ * Build a single `NPM.collect({ ... })` Operation.
+ *
+ * When the position still has `liquidity > 0`, NPM internally calls
+ * `pool.burn(tickLower, tickUpper, 0)` to flush newly-accrued fees into
+ * `tokensOwed*` before transferring. So a standalone collect on an
+ * active position both accrues AND claims in one tx.
+ *
+ * For collect-everything use the default `UINT128_MAX` caps.
+ */
+declare function buildCollect(params: BuildCollectParams): Operation;
+
+interface BuildBurnParams {
+    npm: Address;
+    tokenId: bigint;
+}
+/**
+ * Build a single `NPM.burn(tokenId)` Operation.
+ *
+ * NPM enforces three preconditions on burn:
+ *   - `position.liquidity == 0`
+ *   - `position.tokensOwed0 == 0`
+ *   - `position.tokensOwed1 == 0`
+ *
+ * For a full close, batch `decreaseLiquidity(all) → collect → burn`. The
+ * `buildClosePosition` orchestrator wires that for you; this builder is
+ * exposed for callers that already know the preconditions hold (e.g.
+ * burning an already-emptied position).
+ */
+declare function buildBurn(params: BuildBurnParams): Operation;
+
+interface BuildClosePositionParams {
+    npm: Address;
+    tokenId: bigint;
+    /** Current `position.liquidity`. Determines batch shape. */
+    liquidity: bigint;
+    /** `tokensOwed0 + tokensOwed1 > 0` → still need a collect leg. */
+    hasOutstandingFees: boolean;
+    /** Recipient of the collected tokens. Typically the user's EOA. */
+    recipient: Address;
+    /** Slippage-applied minimums for the decrease leg. */
+    amount0Min: bigint;
+    amount1Min: bigint;
+    /** Unix seconds. Required for the decrease leg if liquidity > 0. */
+    deadline: bigint;
+}
+/**
+ * Build the full-close batch:
+ *
+ *   - `liquidity > 0`:           decreaseLiquidity(all) → collect → burn
+ *   - `liquidity == 0` + fees:   collect → burn
+ *   - `liquidity == 0` + no fees: burn (only)
+ *
+ * The shape selection avoids unnecessary calls — burning an empty
+ * position with no fees is a 1-op batch. Callers don't need to think
+ * about the cases; pass the snapshot and the builder picks.
+ */
+declare function buildClosePosition(params: BuildClosePositionParams): Operation[];
+
+/**
+ * Compute the (word, bit) position of a tick in V3's bitmap layout.
+ *
+ * Mirrors Solidity `TickBitmap.position(int24)`:
+ *   compressed = tick / tickSpacing                  (floor div, not trunc)
+ *   word       = compressed >> 8                     (JS arithmetic shift on int32)
+ *   bit        = ((compressed % 256) + 256) % 256    (JS `%` is sign-preserving — normalize)
+ *
+ * Throws if `tick` or `tickSpacing` is not an integer, if `tickSpacing <= 0`,
+ * or if `tick` is not aligned to `tickSpacing`.
+ */
+declare function tickToBitmapPosition(tick: number, tickSpacing: number): {
+    word: number;
+    bit: number;
+};
+/**
+ * Decode set bits of a single bitmap word into absolute tick indices.
+ * Returns sorted ascending. O(1) when `bitmap === 0n`.
+ *
+ * Bitmap is uint256 → scans bit positions 0..255 inclusive. Decoded with
+ * bigint primitives — `Number` would lose bits past position 53.
+ */
+declare function decodeBitmapWord(bitmap: bigint, wordPos: number, tickSpacing: number): number[];
+/**
+ * Min/max wordPos required to scan an entire V3 pool's bitmap for the
+ * given tickSpacing. Derived from `minUsableTick(spacing)` /
+ * `maxUsableTick(spacing)`, not raw MIN/MAX_TICK.
+ */
+declare function bitmapWordRange(tickSpacing: number): {
+    min: number;
+    max: number;
+};
+
+/**
+ * Discriminated error codes for the liquidity-curve subsystem. Use with
+ * `LiquidityCurveError`: callers `instanceof LiquidityCurveError` then
+ * branch on `code` to decide retry / Sentry / user-copy behavior.
+ */
+declare enum LiquidityCurveErrorCode {
+    /** fetchAllInitializedTicks: initTicks.length > maxTicks. Recovery: raise maxTicks. */
+    TOO_MANY_TICKS = "TOO_MANY_TICKS",
+    /** fetchAllInitializedTicks: bitmap-vs-ticks() mismatch. Recovery: retry against latest. */
+    ATOMICITY_VIOLATION = "ATOMICITY_VIOLATION",
+    /** buildLiquidityCurve: sum(liquidityNet) !== 0. Tick set incomplete or stale. */
+    CURVE_SUM_NONZERO = "CURVE_SUM_NONZERO",
+    /** buildLiquidityCurve: cumulative L went negative during walk. */
+    CURVE_NEGATIVE_L = "CURVE_NEGATIVE_L",
+    /** buildLiquidityCurve: edge L !== 0. currentLiquidity inconsistent with ticks. */
+    CURVE_EDGE_NONZERO = "CURVE_EDGE_NONZERO"
+}
+declare class LiquidityCurveError extends Error {
+    readonly code: LiquidityCurveErrorCode;
+    constructor(code: LiquidityCurveErrorCode, message: string);
+}
+interface InitializedTick extends TickInfo {
+    /** Absolute tick index — integer, divisible by `tickSpacing`. */
+    tick: number;
+}
+interface LiquidityCurveSegment {
+    /** Inclusive lower bound. For the leftmost segment, equals `minUsableTick(spacing)`. */
+    tickLower: number;
+    /** Exclusive upper bound. For the rightmost segment, equals `maxUsableTick(spacing)`. */
+    tickUpper: number;
+    /** `tickToSqrtPriceX96(tickLower)`. */
+    sqrtPriceLowerX96: bigint;
+    /** `tickToSqrtPriceX96(tickUpper)`. */
+    sqrtPriceUpperX96: bigint;
+    /** Active liquidity (`L`) constant across `[tickLower, tickUpper)`. */
+    liquidityActive: bigint;
+}
+interface BuildLiquidityCurveParams {
+    /** From `fetchAllInitializedTicks`. Must be the COMPLETE set, sorted asc. */
+    ticks: InitializedTick[];
+    /** From `poolState.tick`. */
+    currentTick: number;
+    /** From `poolState.liquidity`. */
+    currentLiquidity: bigint;
+    /** From `poolState.tickSpacing`. Drives edge-clamp + sqrt-price boundaries. */
+    tickSpacing: number;
+}
+/**
+ * Pure transformer. Produces N+1 half-open segments covering
+ * `[minUsableTick(spacing), maxUsableTick(spacing))`, each with the
+ * active liquidity that holds across it.
+ *
+ * Throws `LiquidityCurveError` on inconsistent input (see error codes).
+ */
+declare function buildLiquidityCurve(params: BuildLiquidityCurveParams): LiquidityCurveSegment[];
+/**
+ * Clip a curve to a tick viewport. Returns a new sub-range of `curve`
+ * covering `[tickLo, tickHi]`, splitting segments that straddle the
+ * viewport edges. Pure. O(log N) via binary search on `tickLower`.
+ *
+ * Returns `[]` if the viewport is entirely outside the curve's coverage.
+ */
+declare function clipCurveToTickRange(curve: LiquidityCurveSegment[], tickLo: number, tickHi: number): LiquidityCurveSegment[];
+
+/** Bytes of calldata per Phase 1 / Phase 2 call:
+ *  4 (selector) + 32 (single int16 or int24 arg, ABI-padded) = 36 bytes.
+ *  Update this constant if a wider arg is ever added. */
+declare const CALLDATA_BYTES_PER_CALL = 36;
+interface FetchAllInitializedTicksParams {
+    client: PublicClient;
+    pool: Address;
+    /** Pin reads to this block. Default: latest at fetch start. */
+    blockNumber?: bigint;
+    /** Override pool.tickSpacing read. Saves 1 RPC if caller has it. */
+    tickSpacing?: number;
+    /** Maximum *calls* per HTTP eth_call sub-batch. Default 250.
+     *  Translated to viem's byte-oriented batchSize via `* CALLDATA_BYTES_PER_CALL`. */
+    callsPerBatch?: number;
+    /** Hard cap on returned tick count. Default 50_000. */
+    maxTicks?: number;
+}
+interface FetchAllInitializedTicksResult {
+    blockNumber: bigint;
+    tickSpacing: number;
+    /** Sorted ascending by `tick`. */
+    ticks: InitializedTick[];
+}
+/**
+ * Fetch every initialized tick of a V3 pool atomically via two-phase
+ * multicall (`tickBitmap` → `ticks`), pinned to a single `blockNumber`.
+ */
+declare function fetchAllInitializedTicks(params: FetchAllInitializedTicksParams): Promise<FetchAllInitializedTicksResult>;
+
+interface FetchLiquidityCurveParams {
+    client: PublicClient;
+    pool: Address;
+    blockNumber?: bigint;
+    /** Pre-fetched pool state. If provided, MUST have been observed at
+     *  `blockNumber` (caller's responsibility). When omitted, fetched here. */
+    poolState?: PoolState;
+    /** Forwarded to fetchAllInitializedTicks. */
+    callsPerBatch?: FetchAllInitializedTicksParams["callsPerBatch"];
+    maxTicks?: FetchAllInitializedTicksParams["maxTicks"];
+}
+interface FetchLiquidityCurveResult {
+    blockNumber: bigint;
+    poolState: PoolState;
+    ticks: InitializedTick[];
+    curve: LiquidityCurveSegment[];
+    /** Index into `curve` of the segment containing `poolState.tick`.
+     *  Invariant: `curve[currentSegmentIndex].tickLower <= poolState.tick < curve[currentSegmentIndex].tickUpper`. */
+    currentSegmentIndex: number;
+}
+/**
+ * One-call convenience for the FE add-liquidity chart. Reads pool state,
+ * fetches all initialized ticks, builds the curve — all pinned to the
+ * same block.
+ *
+ * @throws {LiquidityCurveError} with `.code`:
+ *   - `TOO_MANY_TICKS` — pool has more than `maxTicks` initialized ticks
+ *   - `ATOMICITY_VIOLATION` — bitmap-vs-ticks() mismatch (rare; retry against latest)
+ *   - `CURVE_SUM_NONZERO` — tick set incomplete (caller passed a stale `poolState`)
+ *   - `CURVE_NEGATIVE_L` — cumulative liquidity went negative during walk
+ *   - `CURVE_EDGE_NONZERO` — `poolState` inconsistent with ticks (likely stale)
+ */
+declare function fetchLiquidityCurve(params: FetchLiquidityCurveParams): Promise<FetchLiquidityCurveResult>;
+
+export { type AddLiquidityDirectParams, type AddLiquidityDirectResult, type ApiPerpDepositRequest, type ApiPerpDepositResponse, type ApiQuoteError, type ApiQuoteExactOutRequest, type ApiQuoteExactOutResponse, type ApiQuoteRequest, type ApiQuoteResponse, type ApiSwapExactOutRequest, type ApiSwapExactOutResponse, type ApiSwapRequest, type ApiSwapResponse, type BuildBurnParams, type BuildClosePositionParams, type BuildCollectParams, type BuildDecreaseLiquidityParams, type BuildIncreaseLiquidityParams, type BuildLiquidityCurveParams, type BuildMintParams, type BuildSwapUserOpExactOutParams, type BuildSwapUserOpParams, CALLDATA_BYTES_PER_CALL, type ClosePositionDirectParams, type ClosePositionDirectResult, type CollectFeesDirectParams, type CollectFeesDirectResult, type FetchAllInitializedTicksParams, type FetchAllInitializedTicksResult, type FetchLiquidityCurveParams, type FetchLiquidityCurveResult, type IncreaseLiquidityDirectParams, type IncreaseLiquidityDirectResult, type InitializedTick, LiquidityCurveError, LiquidityCurveErrorCode, type LiquidityCurveSegment, MAX_SQRT_RATIO, MAX_TICK, MIN_SQRT_RATIO, MIN_TICK, type PerpDepositDirectParams, type PerpDepositDirectResult, type PoolFeeGrowthGlobals, type PoolState, type PositionInfo, Q192, Q96, type RemoveLiquidityDirectParams, type RemoveLiquidityDirectResult, type SwapDirectExactOutParams, type SwapDirectExactOutResult, type SwapDirectParams, type SwapDirectResult, type SwapSimulationResult, type TickInfo, TradingHandlers, type TradingHandlersConfig, UINT128_MAX, V3_NPM_ADDRESSES, V3_SWAP_EXACT_IN, V3_SWAP_EXACT_OUT, addLiquidityDirect, applyMintSlippage, applyRemoveSlippage, bitmapWordRange, buildAllPaths, buildBurn, buildClosePosition, buildCollect, buildDecreaseLiquidity, buildErc20ApprovalCalldata, buildIncreaseLiquidity, buildLiquidityCurve, buildMint, buildPermit2ApprovalCalldata, buildSwapUserOp, buildSwapUserOpExactOut, buildUniversalRouterExecuteArgs, buildUniversalRouterExecuteArgsExactOut, buildV3SwapInputExactIn, buildV3SwapInputExactOut, checkAllowance, clipCurveToTickRange, closePositionDirect, collectFeesDirect, combineRoutes, decodeBitmapWord, estimateLiquidityFromOneSide, fetchAllInitializedTicks, fetchLiquidityCurve, findBestQuote, findBestQuoteExactOut, getAmount0ForLiquidity, getAmount1ForLiquidity, getAmountsForLiquidity, getLiquidityForAmount0, getLiquidityForAmount1, increaseLiquidityDirect, maxUsableTick, minUsableTick, nearestUsableTick, nonfungiblePositionManagerAbi, perpDepositDirect, priceToTick, quoteBestRoute, quoteBestRouteExactOut, quoteExactInput, quoteExactInputSingle, quoteExactOutput, quoteExactOutputSingle, readFeeGrowthGlobals, readPoolState, readPosition, readTicksAt, removeLiquidityDirect, simulateSwap, sqrtPriceX96ToTick, swapDirect, swapDirectExactOut, tickSpacingForFee, tickToBitmapPosition, tickToPrice, tickToSqrtPriceX96, v3PoolAbi };