@ickb/sdk 1000.0.82 → 9001.0.0

package/dist/sdk.js

@@ -1,242 +1,443 @@
 import { ccc } from "@ckb-ccc/core";
-import { collect, CapacityManager, SmartTransaction, binarySearch, hexFrom, getHeader, Epoch, } from "@ickb/utils";
-import { convert, ICKB_DEPOSIT_CAP, ickbExchangeRatio, } from "@ickb/core";
-import { Info, OrderManager, Ratio, } from "@ickb/order";
 import { getConfig } from "./constants.js";
-import { PoolSnapshot } from "./codec.js";
+import { minimumOrderAmount } from "./conversion/estimate.js";
+import { ckbToIckbConversionPlans, ickbToCkbConversionPlans, } from "./conversion/plans.js";
+import { assertDaoOutputLimit, assertFresh, broadcastDeadline, DaoHeaderIndexError, DaoOutputLimitError, pushHeaderDep, tipMaxAgeMs, } from "./dao.js";
+import { Ratio } from "./order/ratio.js";
+import { ickbExchangeRatio } from "./udt.js";
+import { compareBigInt, findCells, isPlainCapacityCell, unique } from "./utils/utils.js";
+import { verifiedClient } from "./utils/verified_client.js";
+/**
+ * Input count up to which one own transaction sweeps liquid cells.
+ *
+ * @remarks A compaction target, not a validity bound: required funding and the fee may go
+ * past it. Counted rather than measured in bytes because a same-lock input costs a fixed
+ * 44 bytes (52 with an extra witness slot), so 1,000 inputs stay near 50 KB, far under the
+ * node's 512,000-byte limit, and near the one measured point (1,000 inputs: 44 KB, about
+ * 180 ms of local completion). A miner paying the bot adds about forty cellbase cells per
+ * turn, which this outpaces; a larger backlog takes several transactions.
+ */
+export const SWEEP_INPUT_LIMIT = 1000;
+/**
+ * The whole SDK, which the Node actors drive by relative import; the package barrel
+ * exposes the two conversion-workflow methods, and its assignment checks they agree.
+ */
 export class IckbSdk {
-    constructor(ownedOwner, ickbLogic, order, capacity, bots) {
-        Object.defineProperty(this, "ownedOwner", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: ownedOwner
-        });
-        Object.defineProperty(this, "ickbLogic", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: ickbLogic
-        });
-        Object.defineProperty(this, "order", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: order
-        });
-        Object.defineProperty(this, "capacity", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: capacity
-        });
-        Object.defineProperty(this, "bots", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: bots
-        });
+    ickbUdt;
+    ownedOwner;
+    ickbLogic;
+    order;
+    constructor({ ickbUdt, ownedOwner, ickbLogic, order }) {
+        this.ickbUdt = ickbUdt;
+        this.ownedOwner = ownedOwner;
+        this.ickbLogic = ickbLogic;
+        this.order = order;
     }
-    static from(...args) {
-        const { managers: { ownedOwner, logic, order, capacity }, bots, } = getConfig(...args);
-        return new IckbSdk(ownedOwner, logic, order, capacity, bots);
+    /** Creates the SDK for one chain's deployment. */
+    static fromChain(chain) {
+        return new IckbSdk(getConfig(chain));
     }
-    static estimate(isCkb2Udt, amounts, system, options) {
-        options = {
-            fee: 1n,
-            feeBase: 100000n,
-            ...options,
+    // ---- State reads -------------------------------------------------------------------
+    /**
+     * Reads system, user-order, and account state at the sampled tip's parent, under the
+     * caller's withdrawal timing rules (`BOT_LOCK_UP` or `WALLET_LOCK_UP`) and, when given, a
+     * positive fee rate cap that replaces CCC's ceiling; a cap of zero or less throws.
+     *
+     * @remarks Every read goes through `verifiedClient` and the tip's parent is bounded by the
+     * policy's slack, so a caller passes a plain client. Every read is complete and uncapped: a large
+     * book or pool costs a slower read, never a partial or failed one. Each account lock is
+     * enumerated by one uncached unfiltered exact-lock scan and classified client-side.
+     */
+    async getL1AccountState(plainClient, locks, lockUp, maxFeeRate) {
+        // CCC reads a zero cap as no cap at all and would plan at a negative one.
+        if (maxFeeRate !== undefined && ccc.numFrom(maxFeeRate) <= ccc.Zero) {
+            throw new RangeError("maxFeeRate must be positive");
+        }
+        const client = verifiedClient(plainClient);
+        const live = await client.getTipHeader();
+        // The live tip can still lose a one-block race, and a transaction naming it as a header
+        // dep is then refused after signing; every recorded fork was one block deep.
+        const tip = await client.getHeaderByNumber(live.number - 1n);
+        if (tip?.hash !== live.parentHash) {
+            throw new Error(`Block ${String(live.number - 1n)} is not the parent of tip ${live.hash}`);
+        }
+        // The age bound is on the header the read is priced at: a fresh tip a node invented can
+        // name any old block as its parent.
+        assertFresh(tip, tipMaxAgeMs(lockUp));
+        const exchangeRatio = Ratio.from(ickbExchangeRatio(tip));
+        const [poolDeposits, orders, feeRate, accounts] = await Promise.all([
+            this.ickbLogic.findDeposits(client, tip),
+            this.order.findOrders(client),
+            // CCC clamps the sampled median at the cap, the connector's chosen rate too. A given cap
+            // replaces CCC's default ceiling, on purpose: the caller's cap is the ceiling.
+            client.getFeeRate(undefined, maxFeeRate === undefined ? undefined : { maxFeeRate }),
+            Promise.all([...unique(locks)].map(async (lock) => this.readLockCells(client, lock, tip))),
+        ]);
+        return {
+            system: {
+                feeRate,
+                tip,
+                exchangeRatio,
+                // One book, two filters: the market side is every order
+                // past par, the wallet's own included, since the bot fills by price, not by owner.
+                orderPool: orders.filter((group) => isPastPar(group, exchangeRatio)),
+                poolDeposits,
+                lockUp,
+            },
+            userOrders: orders.filter((group) => group.isOwner(...locks)),
+            account: {
+                capacityCells: accounts.flatMap((account) => account.capacityCells),
+                nativeUdtCells: accounts.flatMap((account) => account.nativeUdtCells),
+                receipts: accounts.flatMap((account) => account.receipts),
+                withdrawalGroups: accounts.flatMap((account) => account.withdrawalGroups),
+            },
         };
-        const { convertedAmount, ckbFee, info } = OrderManager.convert(isCkb2Udt, system.exchangeRatio, amounts, options);
-        const maturity = ckbFee >= 10n * system.feeRate
-            ? IckbSdk.maturity({ info, amounts }, system)
-            : undefined;
-        return { convertedAmount, ckbFee, info, maturity };
-    }
-    static maturity(o, system) {
-        const info = "info" in o ? o.info : o.data.info;
-        const amounts = "amounts" in o
-            ? o.amounts
-            : { ckbValue: o.ckbUnoccupied, udtValue: o.udtValue };
-        if (info.isDualRatio()) {
-            return;
+    }
+    /** Every Stack cell one lock owns, classified from a single exact-lock scan. */
+    async readLockCells(client, lock, tip) {
+        const scanned = await findCells(client, {
+            script: lock,
+            scriptType: "lock",
+            scriptSearchMode: "exact",
+            withData: true,
+        });
+        const cells = scanned.map(({ cell }) => cell);
+        const [receipts, withdrawalGroups] = await Promise.all([
+            this.ickbLogic.receiptsFrom(client, scanned),
+            this.ownedOwner.withdrawalGroupsFrom(client, scanned, tip),
+        ]);
+        return {
+            capacityCells: cells.filter(isPlainCapacityCell),
+            nativeUdtCells: cells.filter((cell) => this.ickbUdt.isUdt(cell)),
+            receipts,
+            withdrawalGroups,
+        };
+    }
+    // ---- Conversion planning -----------------------------------------------------------
+    /**
+     * Builds and completes one conversion transaction from a conversion context.
+     *
+     * @remarks
+     * Every branch returns a transaction funded from the signer's committed cells: the
+     * candidate plans (deposit counts, or prefixes of the greedy withdrawal selection with
+     * their rebuilt remainder order) are completed most direct first and the first fundable one
+     * wins, so a wallet short of CKB degrades to fewer direct actions plus a larger standing
+     * order rather than failing. Failure results are
+     * expected planning outcomes; when no plan can be funded the last completion error throws.
+     */
+    async buildConversionTransaction(options) {
+        const { amount, context, direction } = options;
+        if (amount < 0n) {
+            return conversionFailure("amount-negative", context.estimatedMaturity);
         }
-        const isCkb2Udt = info.isCkb2Udt();
-        const amount = isCkb2Udt ? amounts.ckbValue : amounts.udtValue;
-        const ratio = isCkb2Udt ? info.ckbToUdt : info.udtToCkb;
-        if (amount === 0n) {
-            return 0n;
-        }
-        const { tip, exchangeRatio, orderPool, ckbAvailable, ckbMaturing } = system;
-        const b = new Info(ratio, ratio, 1);
-        let ckb = isCkb2Udt ? amount : 0n;
-        let udt = isCkb2Udt ? 0n : amount;
-        for (const o of orderPool) {
-            const a = o.data.info;
-            if (a.isCkb2Udt()) {
-                if (!isCkb2Udt || a.ckb2UdtCompare(b) < 0) {
-                    ckb += o.ckbUnoccupied;
-                }
-            }
-            else {
-                if (isCkb2Udt || a.udt2CkbCompare(b) < 0) {
-                    udt += o.udtValue;
-                }
-            }
+        if (direction === "ckb-to-ickb" && amount > context.ckbAvailable) {
+            return conversionFailure("insufficient-ckb", context.estimatedMaturity);
         }
-        ckb -= convert(false, udt, exchangeRatio);
-        let maturity = 10n * 60n * 1000n;
-        if (isCkb2Udt) {
-            if (ckb > 0n) {
-                maturity *= 1n + ckb / ccc.fixedPointFrom("200000");
-            }
-            return maturity + ("info" in o ? BigInt(Date.now()) : tip.timestamp);
+        if (direction === "ickb-to-ckb" && amount > context.ickbAvailable) {
+            return conversionFailure("insufficient-ickb", context.estimatedMaturity);
         }
-        ckb += ckbAvailable;
-        if (ckb >= 0) {
-            return maturity + ("info" in o ? BigInt(Date.now()) : tip.timestamp);
+        const resolved = {
+            ...options,
+            lock: options.lock ?? (await options.signer.getRecommendedAddressObj()).script,
+        };
+        if (amount === 0n) {
+            return this.buildCollectOnlyConversion(resolved);
         }
-        const ckbNeeded = -ckb;
-        const i = binarySearch(ckbMaturing.length, (n) => ckbMaturing[n].ckbCumulative >= ckbNeeded);
-        return ckbMaturing[i]?.maturity;
+        return direction === "ckb-to-ickb"
+            ? this.buildCkbToIckbConversion(resolved)
+            : this.buildIckbToCkbConversion(resolved);
     }
-    async request(tx, user, info, amounts) {
-        user =
-            "codeHash" in user
-                ? user
-                : (await user.getRecommendedAddressObj()).script;
-        this.order.mint(tx, user, info, amounts);
-    }
-    collect(tx, groups, options) {
-        this.order.melt(tx, groups, options);
+    async buildCollectOnlyConversion(options) {
+        const { context, lock, signer } = options;
+        const tx = this.buildBaseTransaction(ccc.Transaction.default(), context);
+        // An empty collection to a lock of the signer's own would only compact the account;
+        // to another lock it moves the liquid cells, which completion builds from the sweep.
+        if (!hasTransactionActivity(tx) &&
+            (context.cells.length === 0 || (await isOwnLock(signer, lock)))) {
+            return conversionFailure("nothing-to-do", context.estimatedMaturity);
+        }
+        const completed = await this.completeConversion(tx, options);
+        return {
+            ok: true,
+            tx: completed,
+            estimatedMaturity: context.estimatedMaturity,
+            conversionKind: "collect-only",
+            isSweepComplete: sweepsAll(completed, context.cells),
+        };
     }
-    async getL1State(client, locks) {
-        const tip = await client.getTipHeader();
-        const exchangeRatio = Ratio.from(ickbExchangeRatio(tip));
-        const [{ ckbAvailable, ckbMaturing }, orders, feeRate] = await Promise.all([
-            this.getCkb(client, tip),
-            collect(this.order.findOrders(client)),
-            client.getFeeRate(),
-        ]);
-        const midInfo = new Info(exchangeRatio, exchangeRatio, 1);
-        const userOrders = [];
-        const systemOrders = [];
-        for (const group of orders) {
-            if (group.isOwner(...locks)) {
-                userOrders.push(group);
+    async buildCkbToIckbConversion(options) {
+        const { context, lock } = options;
+        // A plan is dropped only for an unrepresentable remainder order.
+        const plans = ckbToIckbConversionPlans(options);
+        if (plans.length === 0) {
+            return {
+                ok: false,
+                reason: "amount-too-small",
+                estimatedMaturity: context.estimatedMaturity,
+                minimum: minimumOrderAmount(true, context.system),
+            };
+        }
+        const { candidate: plan, tx } = await completeFirstFundable(plans, (candidate) => {
+            let partial = this.buildBaseTransaction(ccc.Transaction.default(), context);
+            if (candidate.depositCount > 0) {
+                partial = this.ickbLogic.deposit(partial, candidate.depositCount, candidate.depositCapacity, lock);
             }
-            const { order } = group;
-            const info = order.data.info;
-            if ((order.isCkb2UdtMatchable() && info.ckb2UdtCompare(midInfo) < 0) ||
-                (order.isUdt2CkbMatchable() && info.udt2CkbCompare(midInfo) < 0)) {
-                systemOrders.push(order);
+            if (candidate.order !== undefined) {
+                partial = this.order.mint(partial, lock, candidate.order.estimate.info, candidate.order.amounts);
             }
-        }
-        const system = {
-            feeRate,
-            tip,
-            exchangeRatio,
-            orderPool: systemOrders,
-            ckbAvailable,
-            ckbMaturing,
+            return partial;
+        }, async (partial) => this.completeConversion(partial, options));
+        return {
+            ok: true,
+            tx,
+            estimatedMaturity: plan.estimatedMaturity,
+            conversionKind: conversionKind(plan.depositCount > 0, plan.order !== undefined),
+            isSweepComplete: sweepsAll(tx, context.cells),
         };
-        for (const { order } of userOrders) {
-            order.maturity = IckbSdk.maturity(order, system);
+    }
+    async buildIckbToCkbConversion(options) {
+        const { context, lock } = options;
+        const plans = ickbToCkbConversionPlans(options, context.system.poolDeposits);
+        if (plans.length === 0) {
+            return {
+                ok: false,
+                reason: "amount-too-small",
+                estimatedMaturity: context.estimatedMaturity,
+                minimum: minimumOrderAmount(false, context.system),
+            };
         }
+        const { candidate: plan, tx } = await completeFirstFundable(plans, (candidate) => {
+            let partial = this.buildBaseTransaction(ccc.Transaction.default(), context, {
+                deposits: candidate.selectedDeposits,
+                lock,
+            });
+            if (candidate.order !== undefined) {
+                partial = this.order.mint(partial, lock, candidate.order.estimate.info, candidate.order.amounts);
+            }
+            return partial;
+        }, async (partial) => this.completeConversion(partial, options));
+        const notice = plan.order?.estimate.notice;
+        const broadcastBefore = broadcastDeadline(plan.selectedDeposits.map((deposit) => deposit.claimEpoch), context.system.lockUp);
         return {
-            system,
-            user: {
-                orders: userOrders,
-            },
+            ok: true,
+            tx,
+            estimatedMaturity: plan.estimatedMaturity,
+            conversionKind: conversionKind(plan.selectedDeposits.length > 0, plan.order !== undefined),
+            ...(notice === undefined ? {} : { conversionNotice: notice }),
+            isSweepComplete: sweepsAll(tx, context.cells),
+            ...(broadcastBefore === undefined ? {} : { broadcastBefore }),
         };
     }
-    async getCkb(client, tip) {
-        const opts = {
-            onChain: true,
-            tip,
-        };
-        const promiseBotWithdrawals = collect(this.ownedOwner.findWithdrawalGroups(client, this.bots, opts));
-        let poolSnapshotHex = "0x";
-        let poolSnapshotEpoch = Epoch.from([0n, 0n, 1n]);
-        const bot2Ckb = new Map();
-        const reserved = -ccc.fixedPointFrom("2000");
-        for await (const c of this.capacity.findCapacities(client, this.bots, opts)) {
-            const key = hexFrom(c.cell.cellOutput.lock);
-            const ckb = (bot2Ckb.get(key) ?? reserved) + c.ckbValue;
-            bot2Ckb.set(key, ckb);
-            const outputData = c.cell.outputData;
-            if (outputData.length % 256 === 2) {
-                const h = await getHeader(client, {
-                    type: "txHash",
-                    value: c.cell.outPoint.txHash,
-                });
-                const e = Epoch.from(h.epoch);
-                if (poolSnapshotEpoch.compare(e) < 0) {
-                    poolSnapshotHex = outputData;
-                    poolSnapshotEpoch = e;
-                }
+    async completeConversion(tx, options) {
+        return this.completeTransaction(tx, {
+            signer: options.signer,
+            lock: options.lock,
+            feeRate: options.context.system.feeRate,
+            cells: options.context.cells,
+            protocolCells: [
+                ...options.context.receipts,
+                ...options.context.system.poolDeposits,
+            ],
+            tip: options.context.system.tip,
+        });
+    }
+    // ---- Transaction building ----------------------------------------------------------
+    /**
+     * Adds the context's collect steps to a partial transaction: the withdrawal requests when
+     * given, then the collectable orders, the receipts, and the ready withdrawals.
+     *
+     * @remarks
+     * The result is still partial. Callers should use `completeTransaction` before
+     * signing and sending. The withdrawals move their deposit headers to the front of
+     * `headerDeps`, so the given transaction must not reference a header by position.
+     */
+    buildBaseTransaction(txLike, steps, withdrawalRequest) {
+        let tx = ccc.Transaction.from(txLike);
+        if (withdrawalRequest !== undefined && withdrawalRequest.deposits.length > 0) {
+            tx = this.ownedOwner.requestWithdrawal(tx, withdrawalRequest.deposits, withdrawalRequest.lock);
+        }
+        if (steps.availableOrders.length > 0) {
+            tx = this.order.melt(tx, steps.availableOrders);
+        }
+        if (steps.receipts.length > 0) {
+            tx = this.ickbLogic.completeDeposit(tx, steps.receipts);
+        }
+        if (steps.readyWithdrawals.length > 0) {
+            tx = this.ownedOwner.withdraw(tx, steps.readyWithdrawals);
+        }
+        return tx;
+    }
+    /**
+     * Completes iCKB inputs, iCKB change, plain change, and the fee from the cells it is given.
+     *
+     * @remarks Completion never scans. `cells` are the signer's known liquid cells, plain
+     * CKB and iCKB, from the account state already read: the largest ones fund what the
+     * outputs need, the rest ride along as a sweep while the transaction has fewer than
+     * {@link SWEEP_INPUT_LIMIT} inputs, so every own transaction compacts the account.
+     * Ordinary change is always a plain cell; existing outputs
+     * are never reinterpreted or resized as fee change. This does not sign or send.
+     */
+    async completeTransaction(txLike, options) {
+        const { signer, feeRate } = options;
+        const tx = ccc.Transaction.from(txLike).clone();
+        tx.addCellDeps(this.ickbUdt.cellDeps);
+        const changeLock = options.lock ?? (await signer.getRecommendedAddressObj()).script;
+        // Inputs come from one state read, each cell once, and each action spends its own
+        // cell kind, so a repeated out point is a builder bug: this is the one place that
+        // names it, the node would refuse the transaction anyway.
+        const spent = new Set();
+        for (const { previousOutput } of tx.inputs) {
+            const key = previousOutput.toHex();
+            if (spent.has(key)) {
+                throw new Error(`Input ${key} is spent twice`);
             }
+            spent.add(key);
         }
-        const ckbMaturing = new Array();
-        for (const wr of await promiseBotWithdrawals) {
-            if (wr.owned.isReady) {
-                const key = hexFrom(wr.owner.cell.cellOutput.lock);
-                const ckb = (bot2Ckb.get(key) ?? reserved) + wr.ckbValue;
-                bot2Ckb.set(key, ckb);
-                continue;
+        const unspent = options.cells.filter((cell) => !spent.has(cell.outPoint.toHex()));
+        const ickbCells = unspent
+            .filter((cell) => this.ickbUdt.isUdt(cell))
+            .toSorted((left, right) => compareBigInt(udtBalance(right), udtBalance(left)));
+        const plainCells = unspent
+            .filter(isPlainCapacityCell)
+            .toSorted((left, right) => compareBigInt(right.cellOutput.capacity, left.cellOutput.capacity));
+        await this.completeIckb(tx, signer.client, changeLock, ickbCells, options.protocolCells);
+        // Plain CKB: the sweep first, then whatever the fee still needs beyond the limit.
+        const swept = sweep(tx, plainCells);
+        // Last of the header deps, so no index another step names shifts, and before the fee so
+        // its 32 bytes are paid for.
+        pushHeaderDep(tx, options.tip.hash);
+        await completeFee(tx, signer, changeLock, feeRate, plainCells.slice(swept));
+        assertDaoOutputLimit(tx, this.ickbLogic.dao.script);
+        return tx;
+    }
+    /** iCKB: what the outputs need first, then the sweep while the limit allows, then change. */
+    async completeIckb(tx, client, changeLock, ickbCells, protocolCells) {
+        const required = tx.getOutputsUdtBalance(this.ickbUdt.script);
+        let balance = await this.ickbUdt.inputBalance(tx, client, protocolCells);
+        for (const cell of ickbCells) {
+            if (balance >= required && tx.inputs.length >= SWEEP_INPUT_LIMIT) {
+                break;
             }
-            ckbMaturing.push({
-                ckbValue: wr.ckbValue,
-                maturity: wr.owned.maturity.toUnix(tip),
+            tx.addInput(cell);
+            balance += udtBalance(cell);
+        }
+        if (balance < required) {
+            throw new IckbError(`Insufficient iCKB, need ${String(required - balance)} more`, {
+                code: "insufficient_ickb",
             });
         }
-        let ckbAvailable = 0n;
-        for (const ckb of bot2Ckb.values()) {
-            if (ckb > 0n) {
-                ckbAvailable += ckb;
-            }
+        this.ickbUdt.addChange(tx, changeLock, balance - required);
+    }
+}
+/** Whether the transaction already carries any input or output. */
+function hasTransactionActivity(tx) {
+    return tx.inputs.length > 0 || tx.outputs.length > 0;
+}
+/** An order the market can fill at a gain: priced past the DAO ratio on its matchable side. */
+function isPastPar(group, exchangeRatio) {
+    const { order } = group;
+    const { info } = order.data;
+    return ((order.isCkb2UdtMatchable() && info.ckbToUdt.compare(exchangeRatio) < 0) ||
+        (order.isUdt2CkbMatchable() && exchangeRatio.compare(info.udtToCkb) < 0));
+}
+function conversionFailure(reason, estimatedMaturity) {
+    return { ok: false, reason, estimatedMaturity };
+}
+/** A plan always carries a deposit or an order, else it would be a collection. */
+function conversionKind(hasDirect, hasOrder) {
+    if (hasDirect && hasOrder) {
+        return "direct-plus-order";
+    }
+    return hasDirect ? "direct" : "order";
+}
+/** Whether every liquid cell became an input; false when the input limit cut the sweep. */
+function sweepsAll(tx, cells) {
+    const spent = new Set(tx.inputs.map((input) => input.previousOutput.toHex()));
+    return cells.every((cell) => spent.has(cell.outPoint.toHex()));
+}
+async function isOwnLock(signer, lock) {
+    return (await signer.getAddressObjs()).some(({ script }) => script.eq(lock));
+}
+function udtBalance(cell) {
+    return ccc.udtBalanceFrom(cell.outputData);
+}
+/** Adds cells while the input count stays under the limit; returns how many were added. */
+function sweep(tx, cells) {
+    const added = Math.min(cells.length, Math.max(0, SWEEP_INPUT_LIMIT - tx.inputs.length));
+    for (const cell of cells.slice(0, added)) {
+        tx.addInput(cell);
+    }
+    return added;
+}
+/** Completes the fee, adding reserve cells one at a time while capacity is short. */
+async function completeFee(tx, signer, changeLock, feeRate, reserve) {
+    const remaining = [...reserve];
+    for (;;) {
+        try {
+            await tx.completeFeeChangeToLock(signer, changeLock, feeRate, undefined, {
+                shouldAddInputs: false,
+            });
+            return;
         }
-        const tipEpoch = Epoch.from(tip.epoch);
-        const oneCycle = Epoch.from([180n, 0n, 1n]);
-        if (poolSnapshotHex !== "0x") {
-            const eNumber = tip.epoch[0];
-            let start = Epoch.from([eNumber - (eNumber % 180n), 0n, 1n]);
-            const step = Epoch.from([0n, 180n, 1024n]);
-            const depositSize = convert(false, ICKB_DEPOSIT_CAP, tip);
-            for (const binAmount of PoolSnapshot.decode(poolSnapshotHex)) {
-                const end = start.add(step);
-                if (binAmount > 0) {
-                    ckbMaturing.push({
-                        ckbValue: BigInt(binAmount) * depositSize,
-                        maturity: tipEpoch.compare(tipEpoch) < 0
-                            ?
-                                end.add(oneCycle).toUnix(tip)
-                            :
-                                end.toUnix(tip),
-                    });
-                }
-                start = end;
+        catch (error) {
+            if (!(error instanceof ccc.ErrorTransactionInsufficientCapacity)) {
+                throw error;
             }
-        }
-        else {
-            for await (const d of this.ickbLogic.findDeposits(client, opts)) {
-                ckbMaturing.push({
-                    ckbValue: d.ckbValue,
-                    maturity: d.maturity.toUnix(tip),
+            const cell = remaining.shift();
+            if (cell === undefined) {
+                throw new IckbError(error.message, {
+                    code: "insufficient_capacity",
+                    cause: error,
                 });
             }
+            tx.addInput(cell);
         }
-        ckbMaturing.sort((a, b) => Number(a.maturity - b.maturity));
-        let cumulative = 0n;
-        const ckbCumulativeMaturing = [];
-        for (const { ckbValue, maturity } of ckbMaturing) {
-            cumulative += ckbValue;
-            ckbCumulativeMaturing.push({ ckbCumulative: cumulative, maturity });
+    }
+}
+/** Typed SDK failure with a stable machine-readable code. */
+export class IckbError extends Error {
+    /** Stable failure code for callers and observability. */
+    code;
+    /** Creates a typed SDK failure while preserving its cause. */
+    constructor(message, options) {
+        super(message, options);
+        this.name = "IckbError";
+        this.code = options.code;
+    }
+}
+/**
+ * Completes the first candidate that the real completer can fund.
+ *
+ * @remarks
+ * Only completion knows what a transaction costs once markers, remainder orders, change, and
+ * fee are in, so no count is computed up front: each candidate is built and completed in turn.
+ * Capacity, DAO output-limit and DAO header-index failures advance
+ * the walk; transport, scan, signer, and malformed-transaction errors propagate. Exhausting
+ * the candidates throws the last advancing failure.
+ */
+export async function completeFirstFundable(candidates, build, complete) {
+    let error;
+    for (const candidate of candidates) {
+        try {
+            return { candidate, tx: await complete(build(candidate)) };
+        }
+        catch (failure) {
+            if (!isFundabilityFailure(failure)) {
+                throw failure;
+            }
+            error = failure;
         }
-        return {
-            ckbAvailable,
-            ckbMaturing: ckbCumulativeMaturing,
-        };
     }
+    throw error ?? new Error("No candidate could be completed");
+}
+/**
+ * A failure the walk advances past: the candidate costs more than the account funds, or
+ * needs more DAO outputs or deposit-header slots than one transaction has.
+ */
+export function isFundabilityFailure(error) {
+    return (error instanceof IckbError ||
+        error instanceof ccc.ErrorTransactionInsufficientCapacity ||
+        error instanceof DaoOutputLimitError ||
+        error instanceof DaoHeaderIndexError);
 }
 //# sourceMappingURL=sdk.js.map