@coffer_so/sdk 1.0.0

package/dist/clients/tx-builders.js

@@ -0,0 +1,861 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STLD_DEPOSIT_CU_LIMIT = exports.STLD_MAX_TOKENS = void 0;
+exports.buildSwapIx = buildSwapIx;
+exports.buildSwapTx = buildSwapTx;
+exports.buildAddLiquidityIx = buildAddLiquidityIx;
+exports.buildAddLiquidityTx = buildAddLiquidityTx;
+exports.buildRemoveLiquidityIx = buildRemoveLiquidityIx;
+exports.buildRemoveLiquidityTx = buildRemoveLiquidityTx;
+exports.buildSingleTokenDepositIx = buildSingleTokenDepositIx;
+exports.buildSingleTokenDepositAtaIxs = buildSingleTokenDepositAtaIxs;
+exports.buildSingleTokenDepositTx = buildSingleTokenDepositTx;
+exports.buildSingleTokenDepositTxs = buildSingleTokenDepositTxs;
+exports.buildInitializeConfigIx = buildInitializeConfigIx;
+exports.buildPoolInitializeConfigIx = buildPoolInitializeConfigIx;
+exports.buildInitializeCubicPoolIx = buildInitializeCubicPoolIx;
+exports.buildDeployPoolTx = buildDeployPoolTx;
+exports.deriveAltAddress = deriveAltAddress;
+exports.buildInitializePoolAltIx = buildInitializePoolAltIx;
+exports.buildInitializePoolAltTx = buildInitializePoolAltTx;
+exports.buildSetRangeManagerIx = buildSetRangeManagerIx;
+exports.buildSetRangeManagerConfigIx = buildSetRangeManagerConfigIx;
+exports.buildRangeManagerUpdateIx = buildRangeManagerUpdateIx;
+exports.buildSetSwapFeeRateIx = buildSetSwapFeeRateIx;
+exports.buildSetMaxSelloffIx = buildSetMaxSelloffIx;
+exports.buildInitiatePoolAdminTransferIx = buildInitiatePoolAdminTransferIx;
+exports.buildAcceptPoolAdminTransferIx = buildAcceptPoolAdminTransferIx;
+exports.buildCancelPoolAdminTransferIx = buildCancelPoolAdminTransferIx;
+exports.buildDisablePoolAdminIx = buildDisablePoolAdminIx;
+exports.buildGetPoolInfoIx = buildGetPoolInfoIx;
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const bn_js_1 = __importDefault(require("bn.js"));
+const config_1 = require("../config");
+const idl_1 = require("../idl");
+const pda_1 = require("../utils/pda");
+const contract_instructions_1 = require("./contract-instructions");
+const cubicMath_1 = require("../math/cubicMath");
+const fixedPoint_1 = require("../math/fixedPoint");
+const extensions_1 = require("../utils/extensions");
+/**
+ * Low-level transaction builders. Emit raw `TransactionInstruction`s suitable
+ * for combination with others (e.g. versioned transactions with ALTs) in a
+ * single tx. Higher-level convenience lives on `CubicPoolClient`.
+ */
+/**
+ * Anchor discriminator: sha256("global:<ix_name>")[0..8].
+ *
+ * Read straight out of the shipped IDL rather than hand-maintained, so a
+ * regenerated IDL can never silently disagree with the encoder. This table
+ * is a tripwire, not the source of truth: if a refreshed IDL changes bytes
+ * for an instruction we already ship, that is either a renamed instruction
+ * or a bad IDL copy, and we want a loud failure at import time instead of a
+ * transaction the program rejects with `InstructionFallbackNotFound`.
+ *
+ * NOTE: declared before `CUBIC_POOL_DISC` on purpose. Those maps call
+ * `computeDiscriminator` at module-evaluation time, and a `const` declared
+ * after them would still be in its temporal dead zone when they run.
+ */
+const PINNED = {
+    swap: "f8c69e91e17587c8",
+    add_liquidity: "b59d59438fb63448",
+    remove_liquidity: "5055d14818ceb16c",
+    initialize_cubic_pool: "d79474cf79686f83",
+    initialize_pool_alt: "fb874202f4490c90",
+    deposit_single_token: "a688a62fc7c056a9",
+    initialize_config: "d07f1501c2bec446",
+    set_range_manager: "6766ad7008022584",
+    set_range_manager_config: "67d300c8a4bdf5cd",
+    range_manager_update: "f5b72345c80aac2c",
+    pool_initialize_config: "d06eadbc279990b9",
+};
+function computeDiscriminator(ixName, idl = "cubicPool") {
+    const source = idl === "stld"
+        ? idl_1.SINGLE_TOKEN_LIQUIDITY_IDL
+        : idl === "protocolAdmin"
+            ? idl_1.PROTOCOL_ADMIN_IDL
+            : idl_1.CUBIC_POOL_IDL;
+    const ix = source.instructions.find((candidate) => candidate.name === ixName);
+    if (!ix) {
+        throw new Error(`tx-builders: no "${ixName}" instruction in the ${idl} IDL`);
+    }
+    const bytes = Buffer.from(ix.discriminator);
+    const pinned = PINNED[ixName];
+    if (pinned && bytes.toString("hex") !== pinned) {
+        throw new Error(`tx-builders: IDL discriminator for "${ixName}" is ${bytes.toString("hex")}, ` +
+            `pinned value is ${pinned}. The IDL and this encoder disagree — ` +
+            `do not ship until you know which one is right.`);
+    }
+    return bytes;
+}
+const CUBIC_POOL_DISC = {
+    swap: computeDiscriminator("swap"),
+    addLiquidity: computeDiscriminator("add_liquidity"),
+    removeLiquidity: computeDiscriminator("remove_liquidity"),
+    initializeCubicPool: computeDiscriminator("initialize_cubic_pool"),
+    initializePoolAlt: computeDiscriminator("initialize_pool_alt"),
+    setRangeManager: computeDiscriminator("set_range_manager"),
+    setRangeManagerConfig: computeDiscriminator("set_range_manager_config"),
+    rangeManagerUpdate: computeDiscriminator("range_manager_update"),
+};
+const PROTOCOL_ADMIN_DISC = {
+    poolInitializeConfig: computeDiscriminator("pool_initialize_config", "protocolAdmin"),
+};
+const STLD_DISC = {
+    depositSingleToken: computeDiscriminator("deposit_single_token", "stld"),
+};
+function bptProgram(pool) {
+    const program = pool.bptTokenProgram ?? spl_token_1.TOKEN_PROGRAM_ID;
+    if (!program.equals(spl_token_1.TOKEN_PROGRAM_ID) && !program.equals(spl_token_1.TOKEN_2022_PROGRAM_ID)) {
+        throw new Error("BPT mint must be owned by SPL Token or Token-2022");
+    }
+    return program;
+}
+function requirePositiveMinimumBpt(minimumBptAmount, ixName) {
+    if (!minimumBptAmount || minimumBptAmount.lte(new bn_js_1.default(0))) {
+        throw new Error(`${ixName}: minimumBptAmount must be positive`);
+    }
+    return minimumBptAmount;
+}
+/**
+ * Require an explicit per-token slippage floor for remove_liquidity.
+ *
+ * Previously this defaulted to all-zero when omitted, which silently shipped
+ * a remove tx with NO slippage protection (sandwich/MEV exposure). Callers
+ * must now pass `minimumTokenAmounts` (derive them from a fresh `quoteRemove()`
+ * minus tolerance). To intentionally disable protection, pass explicit zeros.
+ */
+function requireExplicitMinimums(minimumTokenAmounts, tokenCount, ixName) {
+    if (!minimumTokenAmounts) {
+        throw new Error(`${ixName}: minimumTokenAmounts must be provided (one per token). ` +
+            `Derive per-token floors from a fresh quoteRemove(); pass explicit zeros ` +
+            `only to intentionally disable slippage protection.`);
+    }
+    if (minimumTokenAmounts.length !== tokenCount) {
+        throw new Error(`${ixName}: minimumTokenAmounts length (${minimumTokenAmounts.length}) must equal token count (${tokenCount})`);
+    }
+    return minimumTokenAmounts;
+}
+// ============================================================
+// Swap
+// ============================================================
+function buildSwapIx(cfg, pool, params) {
+    (0, extensions_1.assertTokensSupported)(pool, [params.tokenInIndex, params.tokenOutIndex], "swap");
+    const inTok = pool.tokens[params.tokenInIndex];
+    const outTok = pool.tokens[params.tokenOutIndex];
+    const userTokenIn = (0, pda_1.deriveAta)(params.user, inTok.mint, inTok.tokenProgram);
+    const userTokenOut = (0, pda_1.deriveAta)(params.user, outTok.mint, outTok.tokenProgram);
+    const data = Buffer.concat([
+        CUBIC_POOL_DISC.swap,
+        encodeU64(params.amountIn),
+        encodeU64(params.minAmountOut),
+        encodeU8(params.tokenInIndex),
+        encodeU8(params.tokenOutIndex),
+    ]);
+    const keys = [
+        { pubkey: pool.address, isSigner: false, isWritable: true },
+        { pubkey: inTok.mint, isSigner: false, isWritable: false },
+        { pubkey: outTok.mint, isSigner: false, isWritable: false },
+        { pubkey: userTokenIn, isSigner: false, isWritable: true },
+        { pubkey: userTokenOut, isSigner: false, isWritable: true },
+        { pubkey: inTok.vault, isSigner: false, isWritable: true },
+        { pubkey: outTok.vault, isSigner: false, isWritable: true },
+        { pubkey: params.user, isSigner: true, isWritable: true },
+        { pubkey: inTok.tokenProgram, isSigner: false, isWritable: false },
+        { pubkey: outTok.tokenProgram, isSigner: false, isWritable: false },
+    ];
+    return new web3_js_1.TransactionInstruction({
+        programId: cfg.programs.cubicPool,
+        keys,
+        data,
+    });
+}
+function buildSwapTx(cfg, pool, params) {
+    return {
+        instructions: [
+            web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: 400000 }),
+            buildSwapIx(cfg, pool, params),
+        ],
+        suggestedCuLimit: 400000,
+    };
+}
+// ============================================================
+// Add liquidity (proportional)
+// ============================================================
+/**
+ * `add_liquidity` — proportional join.
+ *
+ * ⚠ **`params.tokenAmounts` is a CEILING, not an exact amount** (v5.1,
+ * audit M-4 / I-1). The program takes the largest strictly-proportional
+ * basket that fits inside the vector you pass and leaves the remainder in
+ * the wallet; it does NOT pull the full amounts. Any UI copy of the form
+ * "you will deposit exactly X" is wrong — quote the proportional basket
+ * instead (see `CubicPoolClient.quoteAddLiquidity`).
+ *
+ * The wire format is unchanged, so this is a behaviour note, not an
+ * encoding change: the same bytes now mean "at most this much".
+ */
+function buildAddLiquidityIx(cfg, pool, params) {
+    (0, extensions_1.assertTokensSupported)(pool, params.tokenAmounts.flatMap((amount, i) => amount.gt(new bn_js_1.default(0)) ? [i] : []), "add_liquidity");
+    const userBpt = (0, pda_1.deriveAta)(params.user, pool.bptMint, bptProgram(pool));
+    const minBpt = requirePositiveMinimumBpt(params.minimumBptAmount, "add_liquidity");
+    if (params.tokenAmounts.length !== pool.tokenCount) {
+        // The program rejects this with `InvalidArrayLength` (6064); catching it
+        // here costs a round trip less.
+        throw new Error(`add_liquidity: tokenAmounts length (${params.tokenAmounts.length}) ` +
+            `must equal the pool's token count (${pool.tokenCount})`);
+    }
+    // Refuse joins whose integer-rounded basket has a zero live leg. Such a
+    // basket can mint positive BPT in this deployment despite moving no tokens.
+    if (pool.bptTotalSupply.gt(new bn_js_1.default(0))) {
+        const balances = pool.tokens.map(token => BigInt(token.actualBalance.toString()));
+        const amounts = params.tokenAmounts.map(amount => BigInt(amount.toString()));
+        let ratio = null;
+        balances.forEach((balance, i) => {
+            if ((balance > 0n) !== (amounts[i] > 0n))
+                throw new Error("add_liquidity: token liveness mismatch");
+            if (balance === 0n)
+                return;
+            const candidate = (0, fixedPoint_1.divDown)(amounts[i], balance);
+            ratio = ratio === null || candidate < ratio ? candidate : ratio;
+        });
+        if (ratio === null || (0, cubicMath_1.calcBptOutGivenExactTokensIn)(balances, amounts, BigInt(pool.bptTotalSupply.toString())) === 0n ||
+            balances.some(balance => balance > 0n && (0, fixedPoint_1.mulDown)(balance, ratio) === 0n)) {
+            throw new Error("add_liquidity: deposit too small after proportional rounding");
+        }
+    }
+    const data = Buffer.concat([
+        CUBIC_POOL_DISC.addLiquidity,
+        encodeVecU64(params.tokenAmounts),
+        encodeU64(minBpt),
+    ]);
+    // remaining_accounts layout:
+    //   [user_token_i, vault_i] × N, mint_i × N, token_program_i × N
+    const remaining = [];
+    for (let i = 0; i < pool.tokenCount; i++) {
+        const t = pool.tokens[i];
+        const userAta = (0, pda_1.deriveAta)(params.user, t.mint, t.tokenProgram);
+        remaining.push({ pubkey: userAta, isSigner: false, isWritable: true });
+        remaining.push({ pubkey: t.vault, isSigner: false, isWritable: true });
+    }
+    for (let i = 0; i < pool.tokenCount; i++) {
+        remaining.push({ pubkey: pool.tokens[i].mint, isSigner: false, isWritable: false });
+    }
+    for (let i = 0; i < pool.tokenCount; i++) {
+        remaining.push({ pubkey: pool.tokens[i].tokenProgram, isSigner: false, isWritable: false });
+    }
+    const keys = [
+        { pubkey: pool.address, isSigner: false, isWritable: true },
+        { pubkey: pool.bptMint, isSigner: false, isWritable: true },
+        { pubkey: userBpt, isSigner: false, isWritable: true },
+        { pubkey: params.user, isSigner: true, isWritable: true },
+        { pubkey: bptProgram(pool), isSigner: false, isWritable: false },
+        ...remaining,
+    ];
+    return new web3_js_1.TransactionInstruction({
+        programId: cfg.programs.cubicPool,
+        keys,
+        data,
+    });
+}
+function buildAddLiquidityTx(cfg, pool, params) {
+    const userBpt = (0, pda_1.deriveAta)(params.user, pool.bptMint, bptProgram(pool));
+    return {
+        instructions: [
+            web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: 600000 }),
+            (0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(params.user, userBpt, params.user, pool.bptMint, bptProgram(pool)),
+            buildAddLiquidityIx(cfg, pool, params),
+        ],
+        suggestedCuLimit: 600000,
+    };
+}
+// ============================================================
+// Remove liquidity
+// ============================================================
+function buildRemoveLiquidityIx(cfg, pool, params) {
+    const supply = pool.bptTotalSupply;
+    const maxBurn = bn_js_1.default.max(supply.sub(new bn_js_1.default(config_1.MINIMUM_INITIAL_BPT.toString())), new bn_js_1.default(0));
+    const effectiveBurn = bn_js_1.default.min(params.bptAmount, maxBurn);
+    const transferred = supply.gt(new bn_js_1.default(0))
+        ? (0, cubicMath_1.calcTokensOutGivenBptIn)(pool.tokens.map(token => BigInt(token.actualBalance.toString())), BigInt(effectiveBurn.toString()), BigInt(supply.toString()))
+            .flatMap((amount, i) => amount > 0n ? [i] : [])
+        : [];
+    (0, extensions_1.assertTokensSupported)(pool, transferred, "remove_liquidity");
+    const userBpt = (0, pda_1.deriveAta)(params.user, pool.bptMint, bptProgram(pool));
+    const mins = requireExplicitMinimums(params.minimumTokenAmounts, pool.tokenCount, "remove_liquidity");
+    const data = Buffer.concat([
+        CUBIC_POOL_DISC.removeLiquidity,
+        encodeU64(params.bptAmount),
+        encodeVecU64(mins),
+    ]);
+    // remove_liquidity remaining_accounts format:
+    //   [vault_i, user_token_i] × N, mint_i × N, token_program_i × N
+    const remaining = [];
+    for (let i = 0; i < pool.tokenCount; i++) {
+        const t = pool.tokens[i];
+        const userAta = (0, pda_1.deriveAta)(params.user, t.mint, t.tokenProgram);
+        remaining.push({ pubkey: t.vault, isSigner: false, isWritable: true });
+        remaining.push({ pubkey: userAta, isSigner: false, isWritable: true });
+    }
+    for (let i = 0; i < pool.tokenCount; i++) {
+        remaining.push({ pubkey: pool.tokens[i].mint, isSigner: false, isWritable: false });
+    }
+    for (let i = 0; i < pool.tokenCount; i++) {
+        remaining.push({ pubkey: pool.tokens[i].tokenProgram, isSigner: false, isWritable: false });
+    }
+    const keys = [
+        { pubkey: pool.address, isSigner: false, isWritable: true },
+        { pubkey: pool.bptMint, isSigner: false, isWritable: true },
+        { pubkey: userBpt, isSigner: false, isWritable: true },
+        { pubkey: params.user, isSigner: true, isWritable: true },
+        { pubkey: bptProgram(pool), isSigner: false, isWritable: false },
+        ...remaining,
+    ];
+    return new web3_js_1.TransactionInstruction({
+        programId: cfg.programs.cubicPool,
+        keys,
+        data,
+    });
+}
+function buildRemoveLiquidityTx(cfg, pool, params) {
+    const ixs = [
+        web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: cfg.defaults.cuLimit }),
+    ];
+    // The contract transfers every pool token to the user's ATA. Include
+    // idempotent creates so a proportional burn works even when the user never
+    // held one of the receive tokens before.
+    for (const t of pool.tokens) {
+        const userAta = (0, pda_1.deriveAta)(params.user, t.mint, t.tokenProgram);
+        ixs.push((0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(params.user, userAta, params.user, t.mint, t.tokenProgram));
+    }
+    ixs.push(buildRemoveLiquidityIx(cfg, pool, params));
+    return {
+        instructions: ixs,
+        suggestedCuLimit: cfg.defaults.cuLimit,
+    };
+}
+// ============================================================
+// Single-token deposit (helper program)
+// ============================================================
+/**
+ * Largest pool the zap will accept, mirroring `STLD_MAX_TOKENS` in
+ * `single-token-liquidity/src/constants.rs` (which is defined as
+ * cubic-pool's `MAX_TOKENS`).
+ *
+ * Raised from 5 to 10 in v5.1 (audit SF-3): the old ceiling existed because
+ * the per-leg allocations exhausted the 32 KiB bump heap. Above this the
+ * program rejects with `PoolTooLargeForZap` (stld 6032).
+ */
+exports.STLD_MAX_TOKENS = 10;
+/**
+ * Compute units to request for the zap.
+ *
+ * Measured on the v5.1 build at the worst case N=10: 1,073,206 CU for
+ * classic SPL and 913,986 CU for Token-2022. 1.4M is the per-transaction
+ * maximum and leaves headroom for the surge-fee path.
+ */
+exports.STLD_DEPOSIT_CU_LIMIT = 1400000;
+function buildSingleTokenDepositIx(cfg, pool, params) {
+    // v5 / new contract: deposit_single_token args are
+    // (amount_in: u64, token_in_index: u8, minimum_bpt_amount: u64).
+    // The old per-call `slippage_hundredths_bps: u32` was removed — the single
+    // `minimum_bpt_amount` floor now bounds the whole zap (internal swaps +
+    // surge fees + join); per-leg swaps use min_out = 0.
+    if (pool.tokenCount > exports.STLD_MAX_TOKENS) {
+        throw new Error(`deposit_single_token: pool has ${pool.tokenCount} tokens, the zap supports at most ` +
+            `${exports.STLD_MAX_TOKENS} (PoolTooLargeForZap). Use add_liquidity instead.`);
+    }
+    (0, extensions_1.assertTokensSupported)(pool, "all", "deposit_single_token");
+    const minBpt = requirePositiveMinimumBpt(params.minimumBptAmount, "deposit_single_token");
+    const [helper] = (0, pda_1.deriveHelperPda)(cfg.programs.singleTokenLiquidity, pool.address);
+    const helperBpt = (0, pda_1.deriveAta)(helper, pool.bptMint, bptProgram(pool));
+    const userBpt = (0, pda_1.deriveAta)(params.user, pool.bptMint, bptProgram(pool));
+    const data = Buffer.concat([
+        STLD_DISC.depositSingleToken,
+        encodeU64(params.amountIn),
+        encodeU8(params.tokenInIndex),
+        encodeU64(minBpt),
+    ]);
+    // stld remaining_accounts: [mint_i, user_ata_i, helper_ata_i, vault_i, tp_i] × N
+    const remaining = [];
+    for (let i = 0; i < pool.tokenCount; i++) {
+        const t = pool.tokens[i];
+        const userAta = (0, pda_1.deriveAta)(params.user, t.mint, t.tokenProgram);
+        const helperAta = (0, pda_1.deriveAta)(helper, t.mint, t.tokenProgram);
+        remaining.push({ pubkey: t.mint, isSigner: false, isWritable: false });
+        remaining.push({ pubkey: userAta, isSigner: false, isWritable: true });
+        remaining.push({ pubkey: helperAta, isSigner: false, isWritable: true });
+        remaining.push({ pubkey: t.vault, isSigner: false, isWritable: true });
+        remaining.push({ pubkey: t.tokenProgram, isSigner: false, isWritable: false });
+    }
+    const keys = [
+        { pubkey: pool.address, isSigner: false, isWritable: true },
+        { pubkey: helper, isSigner: false, isWritable: false },
+        { pubkey: pool.bptMint, isSigner: false, isWritable: true },
+        { pubkey: helperBpt, isSigner: false, isWritable: true },
+        { pubkey: userBpt, isSigner: false, isWritable: true },
+        { pubkey: params.user, isSigner: true, isWritable: true },
+        { pubkey: cfg.programs.cubicPool, isSigner: false, isWritable: false },
+        { pubkey: bptProgram(pool), isSigner: false, isWritable: false },
+        ...remaining,
+    ];
+    return new web3_js_1.TransactionInstruction({
+        programId: cfg.programs.singleTokenLiquidity,
+        keys,
+        data,
+    });
+}
+/**
+ * The idempotent ATA creates a zap depends on: the user's and the helper's
+ * ATA for every pool token, plus both BPT ATAs. `2N + 2` instructions.
+ *
+ * The helper validates every user ATA up front because it may refund dust
+ * in any pool token, so these cannot be trimmed to just the input token.
+ */
+function buildSingleTokenDepositAtaIxs(cfg, pool, user) {
+    const [helper] = (0, pda_1.deriveHelperPda)(cfg.programs.singleTokenLiquidity, pool.address);
+    const helperBpt = (0, pda_1.deriveAta)(helper, pool.bptMint, bptProgram(pool));
+    const userBpt = (0, pda_1.deriveAta)(user, pool.bptMint, bptProgram(pool));
+    const ixs = [];
+    // User + helper ATAs (helper has an off-curve owner). Idempotent — safe to
+    // include even when the accounts already exist.
+    for (const t of pool.tokens) {
+        ixs.push((0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(user, (0, pda_1.deriveAta)(user, t.mint, t.tokenProgram), user, t.mint, t.tokenProgram));
+        ixs.push((0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(user, (0, pda_1.deriveAta)(helper, t.mint, t.tokenProgram), helper, t.mint, t.tokenProgram));
+    }
+    ixs.push((0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(user, helperBpt, helper, pool.bptMint, bptProgram(pool)));
+    ixs.push((0, spl_token_1.createAssociatedTokenAccountIdempotentInstruction)(user, userBpt, user, pool.bptMint, bptProgram(pool)));
+    return ixs;
+}
+/**
+ * Full single-token deposit in ONE transaction: idempotent ATA setup
+ * followed by the deposit itself.
+ *
+ * ⚠ **This only fits for small pools.** Two independent runtime ceilings
+ * bite as `N` grows, and neither is a byte-size problem an ALT can fix:
+ *
+ *  - `MAX_INSTRUCTION_TRACE_LENGTH = 64` counts CPI frames across the whole
+ *    transaction. One idempotent ATA create costs 5, and the v5.1 zap alone
+ *    uses 52/64 at N=10. The `2N + 2` setup instructions cost `10N + 10`
+ *    frames, so the combined transaction blows the limit well before N=10.
+ *  - Raw size at N=10 is 1796 bytes (437 with the pool's ALT), over the
+ *    1232-byte legacy ceiling.
+ *
+ * For anything but a small pool use {@link buildSingleTokenDepositTxs},
+ * which splits setup and deposit into two transactions, and compile the
+ * deposit leg through the pool's ALT via `compileBuiltTx`.
+ */
+function buildSingleTokenDepositTx(cfg, pool, params) {
+    const cuLimit = cfg.defaults.cuLimit ?? exports.STLD_DEPOSIT_CU_LIMIT;
+    return {
+        instructions: [
+            web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: cuLimit }),
+            ...buildSingleTokenDepositAtaIxs(cfg, pool, params.user),
+            buildSingleTokenDepositIx(cfg, pool, params),
+        ],
+        suggestedCuLimit: cuLimit,
+    };
+}
+/**
+ * Single-token deposit split into the two transactions large pools need.
+ *
+ * Send `setup` first and let it confirm, then send `deposit`. They are
+ * separated because the ATA creates and the zap compete for the same
+ * 64-frame instruction-trace budget (see {@link buildSingleTokenDepositTx}).
+ *
+ * `setup` is `null` when there is nothing to create — the caller can check
+ * ATA existence itself and skip the leg. Otherwise it is always safe to
+ * send: every instruction in it is idempotent.
+ *
+ * The `deposit` leg should be compiled as a v0 transaction against the
+ * pool's Address Lookup Table (`compileBuiltTx(conn, user, deposit, pool)`).
+ * At N=10 it is 1796 bytes raw and 437 with the ALT — the ALT is mandatory,
+ * not an optimisation. Note that an ALT cannot be referenced in the same
+ * slot it was extended, so a freshly-created table needs a slot to settle.
+ */
+function buildSingleTokenDepositTxs(cfg, pool, params) {
+    const ataIxs = buildSingleTokenDepositAtaIxs(cfg, pool, params.user);
+    const cuLimit = cfg.defaults.cuLimit ?? exports.STLD_DEPOSIT_CU_LIMIT;
+    // ~30k CU per idempotent create, with headroom.
+    const setupCu = Math.min(1400000, 50000 * ataIxs.length);
+    return {
+        setup: ataIxs.length === 0
+            ? null
+            : {
+                instructions: [
+                    web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: setupCu }),
+                    ...ataIxs,
+                ],
+                suggestedCuLimit: setupCu,
+            },
+        deposit: {
+            instructions: [
+                web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: cuLimit }),
+                buildSingleTokenDepositIx(cfg, pool, params),
+            ],
+            suggestedCuLimit: cuLimit,
+        },
+    };
+}
+// ============================================================
+// Deploy new pool (PoolFactory)
+// ============================================================
+/**
+ * Raw `cubic_pool::initialize_config`.
+ *
+ * ⚠ **This instruction is no longer directly callable from a wallet.** In
+ * v5.1 (audit H-2) the `protocol_admin: Pubkey` ARGUMENT was removed and
+ * the Treasury PDA account became a `Signer`. The config's admin is now
+ * whoever signs, which by construction can only be protocol-admin's
+ * Treasury PDA via `invoke_signed` — no keypair exists for it.
+ *
+ * Sending this instruction from a wallet fails signature verification. The
+ * only working path is `AdminClient.poolInitializeConfigIx()`, which calls
+ * `protocol_admin::pool_initialize_config` and CPIs in here. This builder
+ * is kept so the wire format stays documented and testable, and so the
+ * treasury meta carries `isSigner: true` — Anchor derives CPI account
+ * metas from the field type, and emitting it as a non-signer would strand
+ * the outer `invoke_signed` signature.
+ */
+function buildInitializeConfigIx(cfg, params) {
+    const [treasuryPda] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("treasury")], cfg.programs.protocolAdmin);
+    // Args are `(default_protocol_fee_rate: u16)` and nothing else. The
+    // leading 32-byte `protocol_admin` pubkey this used to encode is gone —
+    // leaving it in makes the program read the fee rate out of the middle of
+    // a pubkey.
+    const data = Buffer.concat([
+        computeDiscriminator("initialize_config"),
+        encodeU16(params.defaultProtocolFeeRate),
+    ]);
+    const keys = [
+        { pubkey: params.config, isSigner: true, isWritable: true },
+        { pubkey: treasuryPda, isSigner: true, isWritable: false },
+        { pubkey: params.payer, isSigner: true, isWritable: true },
+        { pubkey: web3_js_1.SystemProgram.programId, isSigner: false, isWritable: false },
+    ];
+    return new web3_js_1.TransactionInstruction({
+        programId: cfg.programs.cubicPool,
+        keys,
+        data,
+    });
+}
+/**
+ * `protocol_admin::pool_initialize_config` — the ONLY way to create a
+ * `CubicPoolConfig` that a wallet can actually sign.
+ *
+ * `cubic_pool::initialize_config` takes the Treasury PDA as a `Signer`
+ * (audit H-01: an unauthenticated config let anyone open a pool that charged
+ * a swap fee and paid the protocol nothing). A PDA cannot sign a transaction
+ * — only the program that owns its seeds can, via `invoke_signed`. So the
+ * direct instruction is unreachable from a wallet by design, and every caller
+ * has to come through this wrapper, where the Treasury `admin` is the human
+ * signer and protocol-admin performs the CPI.
+ *
+ * Signers: `admin` (must equal `Treasury.admin`) and `config` (a freshly
+ * generated keypair — the account is `init`, not a PDA).
+ */
+function buildPoolInitializeConfigIx(cfg, params) {
+    const [treasuryPda] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("treasury")], cfg.programs.protocolAdmin);
+    const data = Buffer.concat([
+        PROTOCOL_ADMIN_DISC.poolInitializeConfig,
+        encodeU16(params.defaultProtocolFeeRate),
+    ]);
+    const keys = [
+        { pubkey: treasuryPda, isSigner: false, isWritable: false },
+        { pubkey: params.admin, isSigner: true, isWritable: true },
+        { pubkey: params.config, isSigner: true, isWritable: true },
+        { pubkey: cfg.programs.cubicPool, isSigner: false, isWritable: false },
+        { pubkey: web3_js_1.SystemProgram.programId, isSigner: false, isWritable: false },
+    ];
+    return new web3_js_1.TransactionInstruction({
+        programId: cfg.programs.protocolAdmin,
+        keys,
+        data,
+    });
+}
+function buildInitializeCubicPoolIx(cfg, params) {
+    const tokenProgram = params.bptTokenProgram ?? spl_token_1.TOKEN_PROGRAM_ID;
+    const [pool] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("cubic_pool"), params.configKey.toBuffer(), params.poolId.toArrayLike(Buffer, "le", 8)], cfg.programs.cubicPool);
+    const [bptMint] = (0, pda_1.deriveBptMint)(cfg.programs.cubicPool, pool);
+    const data = Buffer.concat([
+        CUBIC_POOL_DISC.initializeCubicPool,
+        encodeVecU64(params.weightsBps.map((w) => new bn_js_1.default(w))),
+        encodeVecU64(params.virtualBalances),
+        encodeU32(params.swapFeeRate),
+        encodeU64(params.poolId),
+        // Option<u64> banned_extensions_override: 0x00 = None (inherit config
+        // default), 0x01 + u64 LE = Some(bitmap) chosen by the creator.
+        encodeOptionU64(params.bannedExtensions),
+    ]);
+    // There is no `tokens` ix arg — the pool's token set is defined SOLELY by
+    // `params.tokens` via remaining_accounts (one mint per token, in the same
+    // order as `weightsBps`/`virtualBalances`).
+    const remaining = params.tokens.map((m) => ({
+        pubkey: m,
+        isSigner: false,
+        isWritable: false,
+    }));
+    const keys = [
+        { pubkey: params.configKey, isSigner: false, isWritable: false },
+        { pubkey: pool, isSigner: false, isWritable: true },
+        { pubkey: bptMint, isSigner: false, isWritable: true },
+        { pubkey: params.payer, isSigner: true, isWritable: true },
+        { pubkey: tokenProgram, isSigner: false, isWritable: false },
+        { pubkey: spl_token_1.ASSOCIATED_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        { pubkey: web3_js_1.SystemProgram.programId, isSigner: false, isWritable: false },
+        ...remaining,
+    ];
+    return new web3_js_1.TransactionInstruction({
+        programId: cfg.programs.cubicPool,
+        keys,
+        data,
+    });
+}
+function buildDeployPoolTx(cfg, params) {
+    return {
+        instructions: [
+            web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: 400000 }),
+            buildInitializeCubicPoolIx(cfg, params),
+        ],
+        suggestedCuLimit: 400000,
+    };
+}
+/**
+ * Re-derives the Address Lookup Table address from `(authority, recent_slot)`
+ * the same way the upstream ALT program does.
+ *
+ * `@solana/web3.js` v1 doesn't expose `deriveLookupTableAddress` as a static,
+ * so we inline the seed derivation.
+ */
+function deriveAltAddress(authority, recentSlot) {
+    const slotBuf = recentSlot.toArrayLike(Buffer, "le", 8);
+    const [addr] = web3_js_1.PublicKey.findProgramAddressSync([authority.toBuffer(), slotBuf], web3_js_1.AddressLookupTableProgram.programId);
+    return addr;
+}
+/**
+ * Build the on-chain `initialize_pool_alt` instruction. Performs three
+ * upstream CPIs inside the program: create + extend + freeze. After
+ * this ix lands, the ALT is immutable and the pool's `lookup_table`
+ * field points at it.
+ *
+ * Caller must NOT use the ALT in the same slot (warmup) — wait at
+ * least one slot before sending any v0 tx that references it.
+ */
+function buildInitializePoolAltIx(cfg, params) {
+    const altAddr = deriveAltAddress(params.authority, params.recentSlot);
+    const data = Buffer.concat([
+        CUBIC_POOL_DISC.initializePoolAlt,
+        encodeU64(params.recentSlot),
+    ]);
+    // Account order MUST match cubic-pool's InitializePoolAlt context:
+    //   pool, config, authority, payer, lookup_table, system_program, alt_program.
+    const keys = [
+        { pubkey: params.pool, isSigner: false, isWritable: true },
+        { pubkey: params.config, isSigner: false, isWritable: false },
+        { pubkey: params.authority, isSigner: true, isWritable: false },
+        { pubkey: params.payer, isSigner: true, isWritable: true },
+        { pubkey: altAddr, isSigner: false, isWritable: true },
+        { pubkey: web3_js_1.SystemProgram.programId, isSigner: false, isWritable: false },
+        { pubkey: web3_js_1.AddressLookupTableProgram.programId, isSigner: false, isWritable: false },
+    ];
+    return new web3_js_1.TransactionInstruction({
+        programId: cfg.programs.cubicPool,
+        keys,
+        data,
+    });
+}
+function buildInitializePoolAltTx(cfg, params) {
+    return {
+        instructions: [
+            web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: 200000 }),
+            buildInitializePoolAltIx(cfg, params),
+        ],
+        suggestedCuLimit: 200000,
+        lookupTable: deriveAltAddress(params.authority, params.recentSlot),
+    };
+}
+// ============================================================
+// Range manager
+// ============================================================
+/**
+ * `set_range_manager` — appoint or disable a pool's range manager.
+ *
+ * ⚠ v5.1 (audit L-1) PREPENDED a `config` account before `pool`. The
+ * account list is `[config, pool, authority]`. A client still sending
+ * `[pool, authority]` has the program read the pool account as the config
+ * and fail on the discriminator, or worse pass a lookalike.
+ *
+ * Pool admin can appoint or change the manager. The contract also accepts a
+ * config protocol-admin signer for disable-only updates that retain the current
+ * manager key; the deployed protocol-admin program has no CPI wrapper for it. Combine
+ * `newManager = PublicKey.default` with `enabled = false` for the fully
+ * disabled state.
+ */
+function buildSetRangeManagerIx(cfg, pool, params) {
+    const data = Buffer.concat([
+        CUBIC_POOL_DISC.setRangeManager,
+        params.newManager.toBuffer(),
+        encodeBool(params.enabled),
+    ]);
+    const keys = [
+        { pubkey: params.config, isSigner: false, isWritable: false },
+        { pubkey: pool, isSigner: false, isWritable: true },
+        { pubkey: params.authority, isSigner: true, isWritable: false },
+    ];
+    return new web3_js_1.TransactionInstruction({ programId: cfg.programs.cubicPool, keys, data });
+}
+/**
+ * `set_range_manager_config` — the range manager's movement envelope.
+ *
+ * v5.1 appended `max_leverage_bps` and `min_leverage_bps` to the argument
+ * list. Both are required; pass `0` to leave a bound disabled.
+ */
+function buildSetRangeManagerConfigIx(cfg, pool, params) {
+    const data = Buffer.concat([
+        CUBIC_POOL_DISC.setRangeManagerConfig,
+        encodeU16(params.maxVbChangePct),
+        encodeU16(params.maxWeightChangePct),
+        encodeU32(params.minUpdateIntervalSecs),
+        encodeU32(params.maxLeverageBps),
+        encodeU32(params.minLeverageBps),
+    ]);
+    const keys = [
+        { pubkey: pool, isSigner: false, isWritable: true },
+        { pubkey: params.authority, isSigner: true, isWritable: false },
+    ];
+    return new web3_js_1.TransactionInstruction({ programId: cfg.programs.cubicPool, keys, data });
+}
+/**
+ * `range_manager_update` — sparse compare-and-swap over virtual balances
+ * and/or weights.
+ *
+ * Every {@link TokenChange} carries an `expectedCurrent` guard (v5.1, audit
+ * M-6). The program reverts the whole instruction with
+ * `RangeManagerStaleValue` (6061) if any entry no longer matches the stored
+ * value, so a bot MUST derive `expectedCurrent` and `newValue` from the
+ * same pool read and retry from a fresh read on failure — never re-send the
+ * same payload.
+ *
+ * The instruction also honours the pool kill switch now: it reverts while
+ * `pool_enabled` is false.
+ */
+function buildRangeManagerUpdateIx(cfg, pool, params) {
+    const vbChanges = params.vbChanges ?? [];
+    const weightChanges = params.weightChanges ?? [];
+    if (vbChanges.length === 0 && weightChanges.length === 0) {
+        // `RangeManagerEmptyUpdate` (6044) — cheaper to catch here.
+        throw new Error("range_manager_update: must change at least one virtual balance or weight");
+    }
+    const data = Buffer.concat([
+        CUBIC_POOL_DISC.rangeManagerUpdate,
+        encodeVecTokenChange(vbChanges),
+        encodeVecTokenChange(weightChanges),
+    ]);
+    const keys = [
+        { pubkey: pool, isSigner: false, isWritable: true },
+        { pubkey: params.authority, isSigner: true, isWritable: false },
+    ];
+    return new web3_js_1.TransactionInstruction({ programId: cfg.programs.cubicPool, keys, data });
+}
+/** Set the pool-local swap fee (hundredths of a basis point). */
+function buildSetSwapFeeRateIx(cfg, pool, authority, swapFeeRate) {
+    return (0, contract_instructions_1.buildContractInstruction)(cfg, "cubicPool", "set_swap_fee_rate", { swap_fee_rate: swapFeeRate }, { pool, authority });
+}
+/** Replace every token's sell-off policy, including both kink parameters. */
+function buildSetMaxSelloffIx(cfg, pool, authority, params) {
+    return (0, contract_instructions_1.buildContractInstruction)(cfg, "cubicPool", "set_max_selloff", { params: params.map(p => ({
+            max_selloff_pct: p.maxSelloffPct, period_length: p.periodLength,
+            fee_threshold_pct: p.feeThresholdPct, fee_slope_low_pct: p.feeSlopeLowPct,
+            fee_slope_high_pct: p.feeSlopeHighPct, fee_slope_mid_pct: p.feeSlopeMidPct,
+            fee_kink_pct: p.feeKinkPct,
+        })) }, { pool, authority });
+}
+function buildInitiatePoolAdminTransferIx(cfg, pool, authority, newAdmin) {
+    return (0, contract_instructions_1.buildContractInstruction)(cfg, "cubicPool", "initiate_pool_admin_transfer", { new_admin: newAdmin }, { pool, authority });
+}
+function buildAcceptPoolAdminTransferIx(cfg, pool, newAdmin) {
+    return (0, contract_instructions_1.buildContractInstruction)(cfg, "cubicPool", "accept_pool_admin_transfer", {}, { pool, new_admin: newAdmin });
+}
+function buildCancelPoolAdminTransferIx(cfg, pool, authority) {
+    return (0, contract_instructions_1.buildContractInstruction)(cfg, "cubicPool", "cancel_pool_admin_transfer", {}, { pool, authority });
+}
+/** Permanently renounce the pool-local admin role. */
+function buildDisablePoolAdminIx(cfg, pool, authority) {
+    return (0, contract_instructions_1.buildContractInstruction)(cfg, "cubicPool", "disable_pool_admin", {}, { pool, authority });
+}
+function buildGetPoolInfoIx(cfg, pool) {
+    return (0, contract_instructions_1.buildContractInstruction)(cfg, "cubicPool", "get_pool_info", {}, { pool });
+}
+// ============================================================
+// Borsh encoding helpers (subset used above)
+// ============================================================
+function encodeU8(v) {
+    const b = Buffer.alloc(1);
+    requireUnsignedNumber(v, 8);
+    b.writeUInt8(v, 0);
+    return b;
+}
+function encodeU16(v) {
+    const b = Buffer.alloc(2);
+    requireUnsignedNumber(v, 16);
+    b.writeUInt16LE(v, 0);
+    return b;
+}
+function encodeU32(v) {
+    const b = Buffer.alloc(4);
+    requireUnsignedNumber(v, 32);
+    b.writeUInt32LE(v, 0);
+    return b;
+}
+function requireUnsignedNumber(value, bits) {
+    if (!Number.isSafeInteger(value) || value < 0 || value >= 2 ** bits) {
+        throw new Error(`Expected an unsigned ${bits}-bit integer`);
+    }
+}
+function encodeU64(v) {
+    if (!bn_js_1.default.isBN(v) || v.isNeg() || v.bitLength() > 64)
+        throw new Error("Expected an unsigned 64-bit BN");
+    return v.toArrayLike(Buffer, "le", 8);
+}
+/** Borsh `Option<u64>`: 1 tag byte (0=None, 1=Some) + u64 LE when Some. */
+function encodeOptionU64(v) {
+    if (v === undefined || v === null)
+        return Buffer.from([0]);
+    if (typeof v === "number" && (!Number.isSafeInteger(v) || v < 0))
+        throw new Error("Bitmap must be a non-negative safe integer or BN");
+    const bn = bn_js_1.default.isBN(v) ? v : new bn_js_1.default(v);
+    return Buffer.concat([Buffer.from([1]), encodeU64(bn)]);
+}
+function encodeVecU64(vs) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32LE(vs.length, 0);
+    return Buffer.concat([len, ...vs.map(encodeU64)]);
+}
+function encodeBool(v) {
+    if (typeof v !== "boolean")
+        throw new Error("Expected boolean");
+    return Buffer.from([v ? 1 : 0]);
+}
+/**
+ * Borsh `TokenChange { index: u8, expected_current: u64, new_value: u64 }`.
+ *
+ * Field order verified against the `TokenChange` type in
+ * `src/idl/cubic_pool.json`. `expected_current` sits IN THE MIDDLE — it was
+ * inserted between `index` and `new_value`, not appended. Encoding it last
+ * produces a 17-byte record the program happily parses as
+ * `(index, new_value=expected, expected=new)`, which either reverts as
+ * stale or writes the wrong value.
+ */
+function encodeTokenChange(c) {
+    return Buffer.concat([encodeU8(c.index), encodeU64(c.expectedCurrent), encodeU64(c.newValue)]);
+}
+function encodeVecTokenChange(cs) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32LE(cs.length, 0);
+    return Buffer.concat([len, ...cs.map(encodeTokenChange)]);
+}
+//# sourceMappingURL=tx-builders.js.map