@coffer_so/sdk 1.0.0

package/dist/clients/CubicPoolClient.js

@@ -0,0 +1,687 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CubicPoolClient = void 0;
+const quote_math_1 = require("./quote-math");
+const spl_token_1 = require("@solana/spl-token");
+const web3_js_1 = require("@solana/web3.js");
+const bn_js_1 = __importDefault(require("bn.js"));
+const result_1 = require("../types/result");
+const RpcClient_1 = require("./RpcClient");
+const poolAccount_1 = require("../parsers/poolAccount");
+const mintAccount_1 = require("../parsers/mintAccount");
+const events_1 = require("../parsers/events");
+const pda_1 = require("../utils/pda");
+const tokens_1 = require("../config/tokens");
+const extensions_1 = require("../utils/extensions");
+const cubicMath_1 = require("../math/cubicMath");
+const fixedPoint_1 = require("../math/fixedPoint");
+const weightedMath_1 = require("../math/weightedMath");
+const maxSelloff_1 = require("../math/maxSelloff");
+const slippage_1 = require("../math/slippage");
+const singleToken_1 = require("../math/singleToken");
+const maxSelloff_2 = require("../math/maxSelloff");
+const config_1 = require("../config");
+const tx_builders_1 = require("./tx-builders");
+const SingleTokenDepositClient_1 = require("./SingleTokenDepositClient");
+/**
+ * Per-pool client. Fetch the state with `sync()`, then call any of the
+ * quote / buildTx methods off the cached snapshot.
+ */
+class CubicPoolClient {
+    constructor(params) {
+        this.config = params.config;
+        this.poolAddress = params.poolAddress;
+        this.rpc =
+            params.rpc instanceof RpcClient_1.RpcClient
+                ? params.rpc
+                : new RpcClient_1.RpcClient({
+                    endpoint: params.rpc?.endpoint,
+                    endpoints: params.rpc?.endpoints ?? (params.rpc?.endpoint ? undefined : params.config.defaults.rpcEndpoints),
+                    fallbackEndpoints: params.rpc?.fallbackEndpoints,
+                    apiKey: params.rpc?.apiKey,
+                    commitment: params.rpc?.commitment ?? params.config.defaults.rpcCommitment,
+                    timeoutMs: params.rpc?.timeoutMs ?? params.config.defaults.rpcTimeoutMs,
+                });
+    }
+    /** Last-fetched pool state. `undefined` before first `sync()`. */
+    getCached() {
+        return this.cache;
+    }
+    /**
+     * Fetch and decode the pool account + BPT mint + per-token mint decimals.
+     * Safe to call repeatedly; subsequent calls replace the cache.
+     */
+    async sync() {
+        const poolInfo = await this.rpc.getAccountInfo(this.poolAddress);
+        if (!poolInfo.ok)
+            return poolInfo;
+        if (poolInfo.data === null) {
+            return (0, result_1.err)("account_not_found", `Pool ${this.poolAddress.toBase58()} does not exist on-chain`);
+        }
+        if (!poolInfo.data.owner.equals(this.config.programs.cubicPool))
+            return (0, result_1.err)("parse_failure", "Pool account has an unexpected owner");
+        let raw;
+        try {
+            raw = (0, poolAccount_1.decodePoolAccount)(poolInfo.data.data);
+        }
+        catch (e) {
+            return (0, result_1.err)("parse_failure", "Could not decode pool account", e);
+        }
+        const n = raw.tokenCount;
+        const mintAddrs = raw.tokenMints.slice(0, n);
+        const [bptMint, _bptBump] = (0, pda_1.deriveBptMint)(this.config.programs.cubicPool, this.poolAddress);
+        const mintInfos = await this.rpc.getMultipleAccountsWithInfo([bptMint, ...mintAddrs, web3_js_1.SYSVAR_CLOCK_PUBKEY]);
+        if (!mintInfos.ok)
+            return mintInfos;
+        const [bptInfo, ...rest] = mintInfos.data;
+        const tokenMintInfos = rest.slice(0, n);
+        const clockInfo = rest[n];
+        const bptMintData = bptInfo?.data;
+        if (bptInfo && ![spl_token_1.TOKEN_PROGRAM_ID, spl_token_1.TOKEN_2022_PROGRAM_ID].some(p => p.equals(bptInfo.owner)))
+            return (0, result_1.err)("parse_failure", "Invalid BPT token program");
+        if (!clockInfo || clockInfo.data.length < 40)
+            return (0, result_1.err)("parse_failure", "Solana Clock account missing");
+        const chainTimestamp = Number(clockInfo.data.readBigInt64LE(32));
+        const createdAt = Number(raw.createdAt.toString());
+        if (!Number.isSafeInteger(chainTimestamp) || !Number.isSafeInteger(createdAt)) {
+            return (0, result_1.err)("parse_failure", "Pool/Clock timestamp cannot be represented exactly by PoolInfo; use the raw account decoder for full i64 values");
+        }
+        if (!bptMintData) {
+            return (0, result_1.err)("account_not_found", "BPT mint account missing");
+        }
+        let bptMintAcc;
+        try {
+            bptMintAcc = (0, mintAccount_1.decodeMintAccount)(bptMintData);
+        }
+        catch (e) {
+            return (0, result_1.err)("parse_failure", "Could not decode BPT mint", e);
+        }
+        const tokens = [];
+        for (let i = 0; i < n; i++) {
+            const mintInfo = tokenMintInfos[i];
+            const mintRaw = mintInfo?.data;
+            if (mintInfo && !mintInfo.owner.equals(raw.tokenPrograms[i]))
+                return (0, result_1.err)("parse_failure", `Mint token program mismatch at index ${i}`);
+            if (!mintRaw) {
+                return (0, result_1.err)("account_not_found", `Mint account missing for token index ${i}`);
+            }
+            let mintAcc;
+            try {
+                mintAcc = (0, mintAccount_1.decodeMintAccount)(mintRaw);
+            }
+            catch (e) {
+                return (0, result_1.err)("parse_failure", `Could not decode mint ${mintAddrs[i].toBase58()}`, e);
+            }
+            const actualBalance = raw.actualBalances[i];
+            const virtualBalance = raw.virtualBalances[i];
+            if (raw.normalizedWeights[i].gt(new bn_js_1.default(Number.MAX_SAFE_INTEGER))) {
+                return (0, result_1.err)("parse_failure", `Weight cannot be represented exactly at token index ${i}`);
+            }
+            const concentration = virtualBalance.isZero() ? 0 : Number(actualBalance.toString()) / Number(virtualBalance.toString());
+            tokens.push({
+                index: i,
+                mint: raw.tokenMints[i],
+                tokenProgram: raw.tokenPrograms[i],
+                decimals: mintAcc.decimals,
+                weightBps: raw.normalizedWeights[i].toNumber(),
+                virtualBalance,
+                actualBalance,
+                protocolFeesOwed: raw.protocolFeesOwed[i],
+                vault: (0, pda_1.deriveAta)(this.poolAddress, raw.tokenMints[i], raw.tokenPrograms[i]),
+                metadata: this.config.tokens?.[raw.tokenMints[i].toBase58()] ??
+                    (0, tokens_1.resolveKnownToken)(raw.tokenMints[i].toBase58()),
+                concentration,
+                isActive: raw.isActive[i],
+                maxSelloffPct: raw.maxSelloffPct[i],
+                maxSelloffPeriodLength: raw.maxSelloffPeriodLength[i],
+                variableFeeThresholdPct: raw.variableFeeThresholdPct[i],
+                variableFeeSlopeLowPct: raw.variableFeeSlopeLowPct[i],
+                variableFeeSlopeHighPct: raw.variableFeeSlopeHighPct[i],
+                previousSelloff: raw.previousSelloff[i],
+                currentSelloff: raw.currentSelloff[i],
+                windowStartTimestamp: raw.windowStartTimestamp[i],
+                selloffVbSnapshot: raw.selloffVbSnapshot[i],
+                variableFeeSlopeMidPct: raw.variableFeeSlopeMidPct[i],
+                variableFeeKinkPct: raw.variableFeeKinkPct[i],
+                extensions: mintAcc.extensions,
+                unsupportedExtensions: (0, extensions_1.unsupportedMintExtensions)(mintAcc.extensions, raw.bannedExtensions),
+            });
+        }
+        const info = {
+            address: this.poolAddress,
+            config: raw.config,
+            bump: raw.bump,
+            poolId: raw.poolId,
+            tokenCount: n,
+            tokens,
+            unsupportedTokenIndices: tokens.filter((t) => (t.unsupportedExtensions?.length ?? 0) > 0).map((t) => t.index),
+            bptMint,
+            bptTokenProgram: bptInfo.owner,
+            poolAdmin: raw.poolAdmin,
+            pendingPoolAdmin: raw.pendingPoolAdmin,
+            rangeManager: raw.rangeManager,
+            rangeManagerEnabled: raw.rangeManagerEnabled,
+            rangeManagerMaxVbChangePct: raw.rangeManagerMaxVbChangePct,
+            rangeManagerMaxWeightChangePct: raw.rangeManagerMaxWeightChangePct,
+            rangeManagerMinUpdateIntervalSecs: raw.rangeManagerMinUpdateIntervalSecs,
+            rangeManagerLastUpdated: raw.rangeManagerLastUpdated,
+            chainTimestamp,
+            bptTotalSupply: bptMintAcc.supply,
+            swapFeeRate: raw.swapFeeRate,
+            protocolFeeRate: raw.protocolFeeRate,
+            poolEnabled: raw.poolEnabled,
+            swapsEnabled: raw.swapsEnabled,
+            createdAt,
+            lookupTable: raw.lookupTable,
+            bannedExtensions: raw.bannedExtensions,
+            rangeManagerMaxLeverageBps: raw.rangeManagerMaxLeverageBps,
+            rangeManagerMinLeverageBps: raw.rangeManagerMinLeverageBps,
+            syncedAt: Date.now(),
+        };
+        this.cache = info;
+        this.rawAccount = raw;
+        return (0, result_1.ok)(info);
+    }
+    /** Derived helper PDA for this pool (used by single-token-deposit). */
+    helperPda() {
+        return (0, pda_1.deriveHelperPda)(this.config.programs.singleTokenLiquidity, this.poolAddress)[0];
+    }
+    // ---------- Quote helpers (pure, require sync()) ----------
+    /**
+     * Quote a swap. Requires the cache to be populated (call `sync()` first).
+     * Returns exact on-chain math result + spot bound + price impact +
+     * slippage-derived minAmountOut.
+     */
+    quoteSwap(tokenInIndex, tokenOutIndex, amountIn, slippageHundredthsBps, nowSeconds) {
+        const pool = this.requireCache();
+        if (!pool.ok)
+            return pool;
+        const unsupported = this.requireSupported([tokenInIndex, tokenOutIndex], "swap");
+        if (!unsupported.ok)
+            return unsupported;
+        const slip = slippageHundredthsBps ?? this.config.defaults.slippageHundredthsBps;
+        try {
+            const q = (0, quote_math_1.simulatePoolSwap)(pool.data, tokenInIndex, tokenOutIndex, BigInt(amountIn.toString()), (0, quote_math_1.quoteTimestamp)(pool.data, nowSeconds));
+            // v5 display contract: post-trade window fill and static+surge fee
+            // pct (span-average) — the same fields the pre-merge v5 SDK returned.
+            const inTok = pool.data.tokens[tokenInIndex];
+            let windowFillPct = 0;
+            let surgePct = 0;
+            if (q.window && q.window.maxSelloffCap > 0n) {
+                const scale = BigInt(config_1.PERCENT_SCALE);
+                const fillRaw = (q.window.effectiveSelloff * scale) / q.window.maxSelloffCap;
+                windowFillPct = Number(fillRaw > scale ? scale : fillRaw);
+                surgePct = (0, maxSelloff_2.calcSurgeFeePct)(q.window.effectiveSelloffBefore, q.window.effectiveSelloff, q.window.maxSelloffCap, inTok.variableFeeThresholdPct ?? 0, inTok.variableFeeSlopeLowPct ?? 0, inTok.variableFeeSlopeMidPct ?? 0, inTok.variableFeeSlopeHighPct ?? 0, inTok.variableFeeKinkPct ?? 0);
+            }
+            const effectiveFeePct = (pool.data.swapFeeRate * config_1.PERCENT_SCALE) / config_1.SWAP_FEE_PRECISION + surgePct;
+            return (0, result_1.ok)({
+                tokenInIndex,
+                tokenOutIndex,
+                amountIn,
+                amountOut: new bn_js_1.default(q.amountOut.toString()),
+                grossAmountOut: new bn_js_1.default(q.grossAmountOut.toString()),
+                surgeFeeAmount: new bn_js_1.default(q.surgeFeeAmount.toString()),
+                feeAmount: new bn_js_1.default(q.feeAmount.toString()),
+                protocolFeeAmount: new bn_js_1.default(q.protocolFeeAmount.toString()),
+                spotOut: new bn_js_1.default(q.spotOut.toString()),
+                // Impact excludes fees and the surge charge (industry standard):
+                // measured against the GROSS curve output.
+                priceImpactHbps: (0, slippage_1.priceImpactHbps)(q.spotOut, q.grossAmountOut),
+                minAmountOut: new bn_js_1.default((0, slippage_1.applySlippage)(q.amountOut, slip).toString()),
+                effectiveFeePct,
+                windowFillPct,
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            // Keep the specific v5 error codes existing consumers rely on.
+            const code = msg === "MaxSelloffExceeded" ? "selloff_window_full"
+                : msg === "TokenInactive" ? "token_swaps_disabled"
+                    : msg === "PoolDisabled" ? "pool_disabled"
+                        : msg === "SwapsDisabled" ? "swaps_disabled"
+                            : "invalid_input";
+            const human = code === "selloff_window_full"
+                ? "Token max-selloff threshold exceeded for current window"
+                : `Swap quote failed: ${msg}`;
+            return (0, result_1.err)(code, human, e);
+        }
+    }
+    /**
+     * Read-only status of a token's max-selloff window at `now`
+     * (default: current unix seconds). Requires a prior `sync()`.
+     */
+    getSelloffWindowStatus(tokenIndex, now) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        const raw = this.rawAccount;
+        if (!raw) {
+            return (0, result_1.err)("invalid_input", "Call `sync()` first to populate window state");
+        }
+        const pool = poolRes.data;
+        if (tokenIndex < 0 || tokenIndex >= pool.tokens.length) {
+            return (0, result_1.err)("invalid_input", "Invalid tokenIndex");
+        }
+        const i = tokenIndex;
+        return (0, result_1.ok)((0, maxSelloff_2.computeSelloffWindow)({
+            maxSelloffPct: raw.maxSelloffPct[i],
+            periodLength: raw.maxSelloffPeriodLength[i],
+            previousSelloff: raw.previousSelloff[i],
+            currentSelloff: raw.currentSelloff[i],
+            windowStartTimestamp: raw.windowStartTimestamp[i],
+            selloffVbSnapshot: raw.selloffVbSnapshot[i],
+            virtualBalance: pool.tokens[i].virtualBalance,
+            now: now ?? Math.floor(Date.now() / 1000),
+        }));
+    }
+    /**
+     * Quote a single-token deposit: split amountIn by W-based shares, quote
+     * each swap leg, then execute the helper cap and proportional-join math.
+     * `helperBalances` supplies existing helper ATA holdings (defaults to zero).
+     * Pass them when the helper contains donations or dust; all leftovers are refunded.
+     */
+    quoteSingleTokenDeposit(tokenInIndex, amountIn, slippageHundredthsBps, nowSeconds, helperBalances) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        const pool = poolRes.data;
+        if (!Number.isInteger(tokenInIndex) || tokenInIndex < 0 || tokenInIndex >= pool.tokens.length) {
+            return (0, result_1.err)("invalid_input", "Invalid tokenInIndex");
+        }
+        if (!pool.poolEnabled)
+            return (0, result_1.err)("pool_disabled", "Pool is disabled");
+        if (!pool.swapsEnabled)
+            return (0, result_1.err)("invalid_input", "SwapsDisabled");
+        if (pool.bptTotalSupply.isZero())
+            return (0, result_1.err)("invalid_input", "PoolNotSeeded");
+        if (pool.tokens[tokenInIndex].actualBalance.isZero())
+            return (0, result_1.err)("invalid_input", "Input token is sidelined");
+        const unsupported = this.requireSupported(pool.tokens.filter(t => !t.actualBalance.isZero()).map(t => t.index), "deposit_single_token");
+        if (!unsupported.ok)
+            return unsupported;
+        const slip = slippageHundredthsBps ?? this.config.defaults.slippageHundredthsBps;
+        try {
+            const input = (0, quote_math_1.u64)(BigInt(amountIn.toString()), "amountIn");
+            if (input === 0n)
+                return (0, result_1.err)("invalid_input", "amountIn must be positive");
+            const now = (0, quote_math_1.quoteTimestamp)(pool, nowSeconds);
+            const actualBalances = pool.tokens.map(t => BigInt(t.actualBalance.toString()));
+            const virtualBalances = pool.tokens.map(t => BigInt(t.virtualBalance.toString()));
+            const alloc = (0, singleToken_1.computeAllocations)({ actualBalances, virtualBalances, weightsBps: pool.tokens.map(t => t.weightBps), amountIn: input, tokenInIndex });
+            if (alloc.allocations.some((a, i) => actualBalances[i] > 0n && a === 0n))
+                throw new Error("AmountTooSmall");
+            const simulated = { ...pool, tokens: pool.tokens.map(t => ({ ...t })) };
+            if (helperBalances && helperBalances.length !== pool.tokenCount)
+                throw new Error("Invalid helper balance vector length");
+            const helper = pool.tokens.map((_, i) => (0, quote_math_1.u64)(BigInt(helperBalances?.[i].toString() ?? "0"), "helper balance"));
+            const helperSupport = this.requireSupported(helper.flatMap((a, i) => a > 0n ? [i] : []), "helper refund");
+            if (!helperSupport.ok)
+                return helperSupport;
+            (0, quote_math_1.u64)(helper[tokenInIndex] + input, "helper input balance");
+            const expectedOuts = pool.tokens.map(() => new bn_js_1.default(0));
+            const minOuts = pool.tokens.map(() => new bn_js_1.default(0));
+            let remainingInput = input;
+            for (let i = 0; i < pool.tokenCount; i++) {
+                if (i === tokenInIndex || alloc.allocations[i] === 0n)
+                    continue;
+                const q = (0, quote_math_1.simulatePoolSwap)(simulated, tokenInIndex, i, alloc.allocations[i], now, true);
+                remainingInput -= alloc.allocations[i];
+                helper[i] = (0, quote_math_1.u64)(helper[i] + q.amountOut, "helper output balance");
+                expectedOuts[i] = new bn_js_1.default(q.amountOut.toString());
+                minOuts[i] = new bn_js_1.default((0, slippage_1.applySlippage)(q.amountOut, slip).toString());
+            }
+            helper[tokenInIndex] = (0, quote_math_1.u64)(helper[tokenInIndex] + remainingInput, "helper input balance");
+            const postActual = simulated.tokens.map(t => BigInt(t.actualBalance.toString()));
+            const capped = (0, singleToken_1.capDepositAmountsToLpRatio)({ helperBalances: helper, actualBalances: postActual });
+            // The helper's integer ratio cap is followed by cubic-pool's fixed-point proportional join.
+            if (capped.depositAmounts.some((v, i) => (v === 0n) !== (postActual[i] === 0n)))
+                throw new Error("TokenLivenessMismatch");
+            let ratio = null;
+            for (let i = 0; i < pool.tokenCount; i++)
+                if (postActual[i] > 0n) {
+                    const r = (0, fixedPoint_1.divDown)(capped.depositAmounts[i], postActual[i]);
+                    ratio = ratio === null || r < ratio ? r : ratio;
+                }
+            if (ratio === null)
+                throw new Error("Pool has no live tokens");
+            const deposited = postActual.map(a => (0, fixedPoint_1.mulDown)(a, ratio));
+            const estBpt = (0, cubicMath_1.calcBptOutGivenExactTokensIn)(postActual, capped.depositAmounts, BigInt(pool.bptTotalSupply.toString()));
+            if (estBpt === 0n || deposited.some((d, i) => postActual[i] > 0n && d === 0n))
+                throw new Error("DepositTooSmall");
+            (0, quote_math_1.u64)(estBpt + BigInt(pool.bptTotalSupply.toString()), "BPT supply");
+            for (let i = 0; i < pool.tokenCount; i++) {
+                (0, quote_math_1.u64)(postActual[i] + deposited[i], "reserve balance");
+                const vb = BigInt(simulated.tokens[i].virtualBalance.toString());
+                (0, quote_math_1.u64)(vb + (0, fixedPoint_1.mulDown)(vb, ratio), "virtual balance");
+            }
+            this.validateDepositWindows(simulated, ratio);
+            return (0, result_1.ok)({ tokenInIndex, amountIn, allocations: alloc.allocations.map(a => new bn_js_1.default(a.toString())),
+                expectedOuts, minOuts, depositedAmounts: deposited.map(a => new bn_js_1.default(a.toString())),
+                refundAmounts: helper.map((a, i) => new bn_js_1.default((a - deposited[i]).toString())),
+                estimatedBpt: new bn_js_1.default(estBpt.toString()),
+                sidelinedTokenIndices: pool.tokens.filter(t => t.actualBalance.isZero()).map(t => t.index),
+            });
+        }
+        catch (e) {
+            return (0, result_1.err)("invalid_input", `Single-token deposit quote failed: ${e instanceof Error ? e.message : String(e)}`, e);
+        }
+    }
+    /** Seed deposit: creator-only, exact amounts, BPT derived from virtual reserves. */
+    quoteSeedDeposit(user, tokenAmounts, slippageHundredthsBps) {
+        const state = this.requireCache();
+        if (!state.ok)
+            return state;
+        const pool = state.data;
+        if (!pool.poolEnabled)
+            return (0, result_1.err)("pool_disabled", "Pool is disabled");
+        if (!pool.bptTotalSupply.isZero())
+            return (0, result_1.err)("invalid_input", "Pool already seeded; use quoteAddLiquidity");
+        if (!pool.poolAdmin)
+            return (0, result_1.err)("invalid_input", "Pool admin missing: sync the pool before quoting");
+        if (pool.poolAdmin.equals(web3_js_1.PublicKey.default))
+            return (0, result_1.err)("invalid_input", "PoolAdminDisabled");
+        if (!pool.poolAdmin.equals(user))
+            return (0, result_1.err)("invalid_input", "SeedDepositNotPoolAdmin");
+        if (tokenAmounts.length !== pool.tokenCount || tokenAmounts.some(a => a.isNeg() || a.bitLength() > 64))
+            return (0, result_1.err)("invalid_input", "Expected one u64 amount per token");
+        if (tokenAmounts.every(a => a.isZero()))
+            return (0, result_1.err)("invalid_input", "FirstDepositRequiresNonzero");
+        const supported = this.requireSupported(tokenAmounts.flatMap((a, i) => a.isZero() ? [] : [i]), "seed deposit");
+        if (!supported.ok)
+            return supported;
+        try {
+            const virtual = pool.tokens.map(t => BigInt(t.virtualBalance.toString()));
+            const balances = virtual.every(v => v === 0n) ? tokenAmounts.map(a => BigInt(a.toString())) : virtual;
+            const bptOut = (0, quote_math_1.u64)((0, weightedMath_1.calculateInvariant)(balances, pool.tokens.map(t => t.weightBps), pool.tokens.map(t => t.decimals)), "BPT amount");
+            if (bptOut < 1000n)
+                return (0, result_1.err)("invalid_input", "InitialLiquidityTooSmall");
+            return (0, result_1.ok)({ tokenAmounts, depositAmounts: tokenAmounts.map(a => a.clone()), refundAmounts: tokenAmounts.map(() => new bn_js_1.default(0)),
+                bptOut: new bn_js_1.default(bptOut.toString()), minimumBptAmount: new bn_js_1.default((0, slippage_1.applySlippage)(bptOut, slippageHundredthsBps ?? this.config.defaults.slippageHundredthsBps).toString()),
+                limitingTokenIndex: -1 });
+        }
+        catch (e) {
+            return (0, result_1.err)("math_overflow", "Seed-deposit quote failed", e);
+        }
+    }
+    /**
+     * Proportional-join quote. `tokenAmounts` is a CEILING (v5.1, audit
+     * M-4 / I-1): the program takes the largest strictly-proportional basket
+     * that fits inside it and leaves the rest in the wallet. This returns the
+     * basket it will actually pull, the BPT it will mint, and a
+     * slippage-derived `minimumBptAmount` to pass to `buildAddLiquidityTx`.
+     *
+     * Not applicable to the seed deposit (BPT supply == 0): the program
+     * mints invariant-based BPT there and takes the full amounts.
+     */
+    quoteAddLiquidity(tokenAmounts, slippageHundredthsBps) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        const pool = poolRes.data;
+        if (tokenAmounts.length !== pool.tokenCount) {
+            return (0, result_1.err)("invalid_input", "tokenAmounts length must equal pool.tokenCount");
+        }
+        if (pool.bptTotalSupply.isZero()) {
+            return (0, result_1.err)("invalid_input", "Pool has zero BPT supply; use quoteSeedDeposit");
+        }
+        if (!pool.poolEnabled)
+            return (0, result_1.err)("pool_disabled", "Pool is disabled");
+        if (tokenAmounts.some((a) => a.isNeg() || a.bitLength() > 64)) {
+            return (0, result_1.err)("invalid_input", "tokenAmounts must be u64 values");
+        }
+        if (pool.tokens.some((t, i) => t.actualBalance.isZero() !== tokenAmounts[i].isZero())) {
+            return (0, result_1.err)("invalid_input", "TokenLivenessMismatch: live tokens need positive amounts; zero-balance tokens need zero amounts");
+        }
+        const unsupported = this.requireSupported(pool.tokens.filter(t => !t.actualBalance.isZero()).map(t => t.index), "add_liquidity");
+        if (!unsupported.ok)
+            return unsupported;
+        const slip = slippageHundredthsBps ?? this.config.defaults.slippageHundredthsBps;
+        try {
+            // Same inputs as cubic-pool/add_liquidity.rs: raw stored actual
+            // balances, ratio = min over tokens with actual > 0.
+            const bals = pool.tokens.map((t) => BigInt(t.actualBalance.toString()));
+            const amounts = tokenAmounts.map((a) => BigInt(a.toString()));
+            const supply = BigInt(pool.bptTotalSupply.toString());
+            let ratioMin = null;
+            let limiting = -1;
+            for (let i = 0; i < bals.length; i++) {
+                if (bals[i] === 0n)
+                    continue;
+                const r = (0, fixedPoint_1.divDown)(amounts[i], bals[i]);
+                if (ratioMin === null || r < ratioMin) {
+                    ratioMin = r;
+                    limiting = i;
+                }
+            }
+            if (ratioMin === null)
+                return (0, result_1.err)("invalid_input", "Pool has no token with a non-zero balance");
+            const bptOut = (0, cubicMath_1.calcBptOutGivenExactTokensIn)(bals, amounts, supply);
+            if (bptOut === 0n || bptOut > ((1n << 64n) - 1n) || supply + bptOut > ((1n << 64n) - 1n))
+                return (0, result_1.err)("invalid_input", "DepositTooSmall or BPT supply overflow");
+            const deposit = bals.map((b) => (b === 0n ? 0n : (0, fixedPoint_1.mulDown)(b, ratioMin)));
+            if (deposit.some((d, i) => bals[i] > 0n && d === 0n || bals[i] + d > ((1n << 64n) - 1n)))
+                return (0, result_1.err)("invalid_input", "DepositTooSmall or reserve overflow");
+            if (pool.tokens.some(t => BigInt(t.virtualBalance.toString()) + (0, fixedPoint_1.mulDown)(BigInt(t.virtualBalance.toString()), ratioMin) > ((1n << 64n) - 1n)))
+                return (0, result_1.err)("math_overflow", "Virtual balance overflow");
+            this.validateDepositWindows(pool, ratioMin);
+            const refund = amounts.map((a, i) => a - deposit[i]);
+            return (0, result_1.ok)({
+                tokenAmounts,
+                depositAmounts: deposit.map((d) => new bn_js_1.default(d.toString())),
+                refundAmounts: refund.map((r) => new bn_js_1.default(r.toString())),
+                bptOut: new bn_js_1.default(bptOut.toString()),
+                minimumBptAmount: new bn_js_1.default((0, slippage_1.applySlippage)(bptOut, slip).toString()),
+                limitingTokenIndex: limiting,
+            });
+        }
+        catch (e) {
+            return (0, result_1.err)("math_overflow", "Add-liquidity quote failed", e);
+        }
+    }
+    /** Proportional-withdraw quote for a given BPT amount. */
+    quoteRemove(bptIn) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        const pool = poolRes.data;
+        if (pool.bptTotalSupply.isZero()) {
+            return (0, result_1.err)("invalid_input", "Pool has zero BPT supply");
+        }
+        if (!pool.poolEnabled)
+            return (0, result_1.err)("pool_disabled", "Pool is disabled");
+        try {
+            // Match cubic-pool/remove_liquidity.rs exactly: it computes
+            // token_amounts via divDown(bpt_amount, bpt_supply), then mulDown(actual, ratio)
+            // against the raw stored actual (no protocol-fee subtraction). Use
+            // the same input here so the SDK quote equals what the contract
+            // actually transfers.
+            const bals = pool.tokens.map((t) => BigInt(t.actualBalance.toString()));
+            const supply = BigInt(pool.bptTotalSupply.toString());
+            const requested = BigInt(bptIn.toString());
+            if (requested <= 0n || requested > supply || supply <= 1000n)
+                return (0, result_1.err)("invalid_input", "InvalidBptAmount");
+            const effective = requested < supply - 1000n ? requested : supply - 1000n;
+            const outs = (0, cubicMath_1.calcTokensOutGivenBptIn)(bals, effective, supply);
+            const supported = this.requireSupported(outs.flatMap((amount, i) => amount > 0n ? [i] : []), "remove_liquidity");
+            if (!supported.ok)
+                return supported;
+            return (0, result_1.ok)({ tokenOuts: outs.map((o) => new bn_js_1.default(o.toString())), effectiveBptIn: new bn_js_1.default(effective.toString()) });
+        }
+        catch (e) {
+            return (0, result_1.err)("math_overflow", "Remove quote failed", e);
+        }
+    }
+    // ---------- Transaction builders ----------
+    //
+    // For external SDK users, deposit/swap/remove are one-call operations via
+    // the CubicPoolClient. The `singleTokenDeposit` field is a proxy into the
+    // dedicated SingleTokenDepositClient as the user expects: importing this
+    // class is enough, no need to know the helper program exists.
+    /** Build a swap transaction. Requires `sync()` first. */
+    buildSwapTx(params) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        const unsupported = this.requireSupported([params.tokenInIndex, params.tokenOutIndex], "swap");
+        if (!unsupported.ok)
+            return unsupported;
+        const slip = params.slippageHundredthsBps ?? this.config.defaults.slippageHundredthsBps;
+        let minOut;
+        if (params.minAmountOut) {
+            minOut = params.minAmountOut;
+        }
+        else {
+            const q = this.quoteSwap(params.tokenInIndex, params.tokenOutIndex, params.amountIn, slip);
+            if (!q.ok) {
+                return (0, result_1.err)(q.error.code, `Cannot build swap without minAmountOut: ${q.error.humanMessage}`, q.error.cause);
+            }
+            minOut = q.data.minAmountOut;
+        }
+        try {
+            const tx = (0, tx_builders_1.buildSwapTx)(this.config, poolRes.data, { ...params, minAmountOut: minOut });
+            return (0, result_1.ok)(tx);
+        }
+        catch (e) {
+            return (0, result_1.err)("tx_build_failed", "Failed to build swap tx", e);
+        }
+    }
+    /** Build a proportional add-liquidity transaction. Requires `sync()` first. */
+    buildAddLiquidityTx(params) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        if (params.tokenAmounts.length !== poolRes.data.tokenCount) {
+            return (0, result_1.err)("invalid_input", "tokenAmounts length must equal pool.tokenCount");
+        }
+        const unsupported = this.requireSupported(params.tokenAmounts.flatMap((a, i) => a.isZero() ? [] : [i]), "add_liquidity");
+        if (!unsupported.ok)
+            return unsupported;
+        try {
+            return (0, result_1.ok)((0, tx_builders_1.buildAddLiquidityTx)(this.config, poolRes.data, params));
+        }
+        catch (e) {
+            return (0, result_1.err)("tx_build_failed", "Failed to build add_liquidity tx", e);
+        }
+    }
+    /** Build a proportional remove-liquidity transaction. Requires `sync()` first. */
+    buildRemoveLiquidityTx(params) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        if (!params.minimumTokenAmounts) {
+            return (0, result_1.err)("invalid_input", "minimumTokenAmounts is required (one per token). Derive per-token floors from quoteRemove(); pass explicit zeros only to intentionally disable slippage protection.");
+        }
+        if (params.minimumTokenAmounts.length !== poolRes.data.tokenCount) {
+            return (0, result_1.err)("invalid_input", "minimumTokenAmounts length must equal pool.tokenCount");
+        }
+        const quote = this.quoteRemove(params.bptAmount);
+        if (!quote.ok)
+            return quote;
+        try {
+            return (0, result_1.ok)((0, tx_builders_1.buildRemoveLiquidityTx)(this.config, poolRes.data, params));
+        }
+        catch (e) {
+            return (0, result_1.err)("tx_build_failed", "Failed to build remove_liquidity tx", e);
+        }
+    }
+    /**
+     * Build a single-token deposit transaction (swaps + add_liquidity via the
+     * helper program + BPT forward to user). Requires `sync()` first.
+     */
+    buildSingleTokenDepositTx(params) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        if (params.amountIn.lten(0))
+            return (0, result_1.err)("invalid_input", "amountIn must be > 0");
+        const unsupported = this.requireSupported(poolRes.data.tokens.filter(t => !t.actualBalance.isZero() || t.index === params.tokenInIndex).map(t => t.index), "deposit_single_token");
+        if (!unsupported.ok)
+            return unsupported;
+        try {
+            return (0, result_1.ok)((0, tx_builders_1.buildSingleTokenDepositTx)(this.config, poolRes.data, params));
+        }
+        catch (e) {
+            return (0, result_1.err)("tx_build_failed", "Failed to build single-token deposit tx", e);
+        }
+    }
+    /**
+     * Single-token deposit split into `{ setup, deposit }` transactions.
+     *
+     * Required for pools beyond a handful of tokens: the ATA creates and the
+     * zap compete for the same 64-frame instruction-trace budget, and at
+     * N=10 the zap alone uses 52 of them. Send `setup` (idempotent, safe to
+     * repeat), wait for confirmation, then send `deposit` compiled against
+     * the pool's ALT via `compileBuiltTx`.
+     */
+    buildSingleTokenDepositTxs(params) {
+        const poolRes = this.requireCache();
+        if (!poolRes.ok)
+            return poolRes;
+        if (params.amountIn.lten(0))
+            return (0, result_1.err)("invalid_input", "amountIn must be > 0");
+        const unsupported = this.requireSupported(poolRes.data.tokens.filter(t => !t.actualBalance.isZero() || t.index === params.tokenInIndex).map(t => t.index), "deposit_single_token");
+        if (!unsupported.ok)
+            return unsupported;
+        try {
+            return (0, result_1.ok)((0, tx_builders_1.buildSingleTokenDepositTxs)(this.config, poolRes.data, params));
+        }
+        catch (e) {
+            return (0, result_1.err)("tx_build_failed", "Failed to build single-token deposit txs", e);
+        }
+    }
+    /** Proxy into the dedicated SingleTokenDepositClient for consumers who
+     *  want the quote/build methods exposed on a focused object. */
+    get singleTokenDeposit() {
+        if (!this._std) {
+            this._std = new SingleTokenDepositClient_1.SingleTokenDepositClient({
+                config: this.config,
+                poolAddress: this.poolAddress,
+                poolClient: this,
+            });
+        }
+        return this._std;
+    }
+    // ---------- Event helpers ----------
+    /** Parse logs from a confirmed transaction into typed events. */
+    parseEventsFromLogs(logs) {
+        return (0, events_1.parseCubicPoolEvents)(logs);
+    }
+    // ---------- Internals ----------
+    /**
+     * Refuse when any of `indices` (or every token, for `"all"`) has an
+     * unsupported Token-2022 extension. The program would revert inside the
+     * token program on transfer, so failing here saves the user a fee.
+     */
+    requireSupported(indices, op) {
+        const pool = this.cache;
+        if (!pool)
+            return (0, result_1.ok)(undefined);
+        const idx = indices === "all" ? pool.tokens.map((t) => t.index) : indices;
+        const bad = idx.map((i) => pool.tokens[i]).filter((t) => t && (t.unsupportedExtensions?.length ?? 0) > 0);
+        if (bad.length === 0)
+            return (0, result_1.ok)(undefined);
+        return (0, result_1.err)("unsupported_token_extension", `${op} refused: ${bad.map(extensions_1.describeUnsupportedToken).join("; ")}. ` +
+            "The cubic-pool program cannot transfer such tokens; the transaction would revert on-chain.");
+    }
+    validateDepositWindows(pool, ratio) {
+        for (const token of pool.tokens) {
+            if (token.maxSelloffPct === 0)
+                continue;
+            if ([token.previousSelloff, token.currentSelloff, token.selloffVbSnapshot, token.windowStartTimestamp].some(v => v === undefined))
+                throw new Error("Selloff state missing: sync the pool before quoting");
+            (0, maxSelloff_1.rescaleSelloffWindow)({ previousSelloff: BigInt(token.previousSelloff.toString()), currentSelloff: BigInt(token.currentSelloff.toString()),
+                selloffVbSnapshot: BigInt(token.selloffVbSnapshot.toString()), windowStartTimestamp: BigInt(token.windowStartTimestamp.toString()) }, ratio, true, token.maxSelloffPct);
+        }
+    }
+    requireCache() {
+        if (!this.cache) {
+            return (0, result_1.err)("invalid_input", "Call `sync()` first to populate pool state");
+        }
+        return (0, result_1.ok)(this.cache);
+    }
+}
+exports.CubicPoolClient = CubicPoolClient;
+//# sourceMappingURL=CubicPoolClient.js.map