@ickb/sdk 1000.0.82 → 9001.0.0

package/src/sdk.ts

@@ -1,513 +1,615 @@
 import { ccc } from "@ckb-ccc/core";
+import { getConfig } from "./constants.ts";
+import { minimumOrderAmount } from "./conversion/estimate.ts";
 import {
-  collect,
-  CapacityManager,
-  SmartTransaction,
-  binarySearch,
-  type ValueComponents,
-  hexFrom,
-  getHeader,
-  Epoch,
-} from "@ickb/utils";
+  ckbToIckbConversionPlans,
+  ickbToCkbConversionPlans,
+} from "./conversion/plans.ts";
+import type {
+  AccountState,
+  CompleteIckbTransactionOptions,
+  ConversionTransactionContext,
+  ConversionTransactionFailureReason,
+  ConversionTransactionOptions,
+  ConversionTransactionResult,
+  SdkManagers,
+  SystemState,
+} from "./conversion/types.ts";
 import {
-  convert,
-  ICKB_DEPOSIT_CAP,
-  ickbExchangeRatio,
-  type LogicManager,
-  type OwnedOwnerManager,
-} from "@ickb/core";
-import {
-  Info,
-  OrderManager,
-  Ratio,
-  type OrderCell,
-  type OrderGroup,
-} from "@ickb/order";
-import { getConfig } from "./constants.js";
-import { PoolSnapshot } from "./codec.js";
+  assertDaoOutputLimit,
+  assertFresh,
+  broadcastDeadline,
+  DaoHeaderIndexError,
+  DaoOutputLimitError,
+  type LockUpPolicy,
+  pushHeaderDep,
+  tipMaxAgeMs,
+} from "./dao.ts";
+import type { IckbDepositCell, LogicManager } from "./logic.ts";
+import type { OrderGroup } from "./order/cells.ts";
+import type { OrderManager } from "./order/order.ts";
+import { Ratio } from "./order/ratio.ts";
+import type { OwnedOwnerManager } from "./owned_owner.ts";
+import { ickbExchangeRatio, type IckbUdt, type ProtocolCell } from "./udt.ts";
+import type { SupportedChain } from "./utils/chain.ts";
+import { compareBigInt, findCells, isPlainCapacityCell, unique } from "./utils/utils.ts";
+import { verifiedClient } from "./utils/verified_client.ts";
 
 /**
- * SDK for managing iCKB operations.
+ * 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 class IckbSdk {
-  /**
-   * Creates an instance of IckbSdk.
-   *
-   * @param ownedOwner - The manager for owned owner operations.
-   * @param ickbLogic - The manager for iCKB logic operations.
-   * @param order - The manager for order operations.
-   * @param capacity - The capacity manager instance.
-   * @param bots - An array of bot lock scripts.
-   */
-  constructor(
-    private readonly ownedOwner: OwnedOwnerManager,
-    private readonly ickbLogic: LogicManager,
-    private readonly order: OrderManager,
-    private readonly capacity: CapacityManager,
-    private readonly bots: ccc.Script[],
-  ) {}
+export const SWEEP_INPUT_LIMIT = 1000;
 
-  /**
-   * Creates an instance of IckbSdk from script dependencies.
-   *
-   * @param args - Parameters matching those of getConfig.
-   * @returns A new instance of IckbSdk.
-   */
-  static from(...args: Parameters<typeof getConfig>): IckbSdk {
-    const {
-      managers: { ownedOwner, logic, order, capacity },
-      bots,
-    } = getConfig(...args);
+/** The options with the lock resolved to the signer's recommended one when absent. */
+type ResolvedConversionOptions = ConversionTransactionOptions & { lock: ccc.Script };
 
-    return new IckbSdk(ownedOwner, logic, order, capacity, bots);
+/** What every own transaction collects along: the context's collectable positions. */
+type CollectSteps = Pick<
+  ConversionTransactionContext,
+  "availableOrders" | "receipts" | "readyWithdrawals"
+>;
+
+/**
+ * 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 {
+  private readonly ickbUdt: IckbUdt;
+  private readonly ownedOwner: OwnedOwnerManager;
+  private readonly ickbLogic: LogicManager;
+  private readonly order: OrderManager;
+
+  constructor({ ickbUdt, ownedOwner, ickbLogic, order }: SdkManagers) {
+    this.ickbUdt = ickbUdt;
+    this.ownedOwner = ownedOwner;
+    this.ickbLogic = ickbLogic;
+    this.order = order;
   }
 
+  /** Creates the SDK for one chain's deployment. */
+  public static fromChain(chain: SupportedChain): IckbSdk {
+    return new IckbSdk(getConfig(chain));
+  }
+
+  // ---- State reads -------------------------------------------------------------------
+
   /**
-   * Previews the conversion between CKB and UDT.
+   * 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.
    *
-   * This method calculates a conversion preview using an exchange ratio midpoint.
-   * Optionally, a fee may be applied that influences the effective conversion rate,
-   * scaling the converted amount by (feeBase - fee) / feeBase.
-   *
-   * @param isCkb2Udt - Indicates the conversion direction:
-   *                    - true: Convert CKB to UDT.
-   *                    - false: Convert UDT to CKB.
-   * @param amounts - An object containing value components (amounts for CKB and UDT).
-   * @param system - The current system state containing exchange ratio, fee rate, tip, and order-related information.
-   * @param options - Optional parameters for fee and matching:
-   *    - fee: The fee to apply in integer terms (defaults to 1n for 0.001% fee).
-   *    - feeBase: The base used for fee scaling (defaults to 100000n).
-   *
-   * @returns An object with:
-   *   - convertedAmount: The estimated converted amount as a FixedPoint.
-   *   - ckbFee: The fee (or gain) in CKB, as a FixedPoint.
-   *   - info: Additional conversion metadata.
-   *   - maturity: Optional maturity information (as ccc.Num) if meets criteria.
+   * @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.
    */
-  static estimate(
-    isCkb2Udt: boolean,
-    amounts: ValueComponents,
-    system: SystemState,
-    options?: {
-      fee?: ccc.Num;
-      feeBase?: ccc.Num;
-    },
-  ): {
-    convertedAmount: ccc.FixedPoint;
-    ckbFee: ccc.FixedPoint;
-    info: Info;
-    maturity: ccc.Num | undefined;
-  } {
-    // Apply a 0.001% default fee if none provided.
-    options = {
-      fee: 1n,
-      feeBase: 100000n,
-      ...options,
+  public async getL1AccountState(
+    plainClient: ccc.Client,
+    locks: ccc.Script[],
+    lockUp: LockUpPolicy,
+    maxFeeRate?: ccc.NumLike,
+  ): Promise<{
+    system: SystemState;
+    userOrders: OrderGroup[];
+    account: AccountState;
+  }> {
+    // 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,
-    );
-
-    // If the fee meets a threshold, calculate the order maturity; otherwise, maturity is undefined.
-    const maturity =
-      ckbFee >= 10n * system.feeRate
-        ? IckbSdk.maturity({ info, amounts }, system)
-        : undefined;
+  }
 
-    return { convertedAmount, ckbFee, info, maturity };
+  /** Every Stack cell one lock owns, classified from a single exact-lock scan. */
+  private async readLockCells(
+    client: ccc.Client,
+    lock: ccc.Script,
+    tip: ccc.ClientBlockHeader,
+  ): Promise<AccountState> {
+    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 -----------------------------------------------------------
+
   /**
-   * Estimates the maturity for an order formatted as a Unix timestamp.
-   *
-   * Depending on the order type and amount remaining, the method calculates an estimated timestamp
-   * when the order (or part thereof) might be fulfilled.
+   * Builds and completes one conversion transaction from a conversion context.
    *
-   * @param o - Either an OrderCell or an object containing order Info and value components.
-   * @param system - The current system state.
-   * @returns The Unix timestamp of estimated maturity as a bigint (in milliseconds) or undefined if not applicable.
+   * @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.
    */
-  static maturity(
-    o:
-      | OrderCell
-      | {
-          info: Info;
-          amounts: ValueComponents;
-        },
-    system: SystemState,
-  ): bigint | undefined {
-    const info = "info" in o ? o.info : o.data.info;
-    const amounts =
-      "amounts" in o
-        ? o.amounts
-        : { ckbValue: o.ckbUnoccupied, udtValue: o.udtValue };
-
-    // Dual-ratio orders have no fixed maturity.
-    if (info.isDualRatio()) {
-      return;
+  public async buildConversionTransaction(
+    options: ConversionTransactionOptions,
+  ): Promise<ConversionTransactionResult> {
+    const { amount, context, direction } = options;
+    if (amount < 0n) {
+      return conversionFailure("amount-negative", context.estimatedMaturity);
+    }
+    if (direction === "ckb-to-ickb" && amount > context.ckbAvailable) {
+      return conversionFailure("insufficient-ckb", context.estimatedMaturity);
+    }
+    if (direction === "ickb-to-ckb" && amount > context.ickbAvailable) {
+      return conversionFailure("insufficient-ickb", context.estimatedMaturity);
     }
 
-    const isCkb2Udt = info.isCkb2Udt();
-    const amount = isCkb2Udt ? amounts.ckbValue : amounts.udtValue;
-    const ratio = isCkb2Udt ? info.ckbToUdt : info.udtToCkb;
-
-    // If order is already fulfilled.
+    const resolved = {
+      ...options,
+      lock: options.lock ?? (await options.signer.getRecommendedAddressObj()).script,
+    };
     if (amount === 0n) {
-      return 0n;
+      return this.buildCollectOnlyConversion(resolved);
     }
+    return direction === "ckb-to-ickb"
+      ? this.buildCkbToIckbConversion(resolved)
+      : this.buildIckbToCkbConversion(resolved);
+  }
 
-    const { tip, exchangeRatio, orderPool, ckbAvailable, ckbMaturing } = system;
-
-    // Create a reference ratio instance for comparison.
-    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 not isCkb2Udt or a worse ratio, add available CKB.
-        if (!isCkb2Udt || a.ckb2UdtCompare(b) < 0) {
-          ckb += o.ckbUnoccupied;
-        }
-      } else {
-        // Conversely for UDT to CKB orders.
-        if (isCkb2Udt || a.udt2CkbCompare(b) < 0) {
-          udt += o.udtValue;
-        }
-      }
-    }
-    // Adjust ckb by the converted UDT amount.
-    ckb -= convert(false, udt, exchangeRatio);
-
-    // Minimum maturity of 10 minutes (in milliseconds).
-    let maturity = 10n * 60n * 1000n;
-    if (isCkb2Udt) {
-      // For CKB to UDT orders, extend maturity based on the CKB amount.
-      if (ckb > 0n) {
-        maturity *= 1n + ckb / ccc.fixedPointFrom("200000");
-      }
-      return maturity + ("info" in o ? BigInt(Date.now()) : tip.timestamp);
+  private async buildCollectOnlyConversion(
+    options: ResolvedConversionOptions,
+  ): Promise<ConversionTransactionResult> {
+    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),
+    };
+  }
 
-    // For UDT to CKB orders, add available CKB.
-    ckb += ckbAvailable;
-    if (ckb >= 0) {
-      return maturity + ("info" in o ? BigInt(Date.now()) : tip.timestamp);
+  private async buildCkbToIckbConversion(
+    options: ResolvedConversionOptions,
+  ): Promise<ConversionTransactionResult> {
+    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),
+      };
     }
-
-    // Find the earliest maturity in the ckbMaturing array that satisfies the required CKB.
-    const ckbNeeded = -ckb;
-    const i = binarySearch(
-      ckbMaturing.length,
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      (n) => ckbMaturing[n]!.ckbCumulative >= ckbNeeded,
+    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,
+          );
+        }
+        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),
     );
-
-    return ckbMaturing[i]?.maturity;
+    return {
+      ok: true,
+      tx,
+      estimatedMaturity: plan.estimatedMaturity,
+      conversionKind: conversionKind(plan.depositCount > 0, plan.order !== undefined),
+      isSweepComplete: sweepsAll(tx, context.cells),
+    };
   }
 
-  /**
-   * Mints a new order cell and appends it to the transaction.
-   *
-   * The method performs the following operations:
-   * - Creates order cell data using provided amounts and order information.
-   * - Adds required cell dependencies and UDT handlers to the transaction.
-   * - Appends the order cell to the transaction outputs.
-   *
-   * @param tx - The smart transaction to which the order cell is added.
-   * @param user - The user, represented either as a Signer or a Script.
-   * @param info - The order information meta data (usually computed via OrderManager.convert).
-   * @param amounts - The value components for the order, including:
-   *    - ckbValue: The CKB amount (may include an internal surplus).
-   *    - udtValue: The UDT amount.
-   *
-   * @returns A Promise resolving to void.
-   */
-  async request(
-    tx: SmartTransaction,
-    user: ccc.Signer | ccc.Script,
-    info: Info,
-    amounts: ValueComponents,
-  ): Promise<void> {
-    // If the user is provided as a Signer, extract the recommended lock script.
-    user =
-      "codeHash" in user
-        ? user
-        : (await user.getRecommendedAddressObj()).script;
+  private async buildIckbToCkbConversion(
+    options: ResolvedConversionOptions,
+  ): Promise<ConversionTransactionResult> {
+    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 {
+      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 }),
+    };
+  }
 
-    this.order.mint(tx, user, info, amounts);
+  private async completeConversion(
+    tx: ccc.Transaction,
+    options: ResolvedConversionOptions,
+  ): Promise<ccc.Transaction> {
+    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 ----------------------------------------------------------
+
   /**
-   * Melts (cancels) the specified order groups.
-   *
-   * For each order group, if the option is set to process fulfilled orders only,
-   * it filters accordingly. Then, for every valid group, the master and order cells are added
-   * as inputs to the transaction.
-   *
-   * @param tx - The smart transaction to which the inputs are added.
-   * @param groups - An array of order groups to be melted.
-   * @param options - Optional parameters:
-   *    - isFulfilledOnly: If true, only order groups with fully or partially fulfilled orders are processed.
+   * 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.
    *
-   * @returns void
+   * @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.
    */
-  collect(
-    tx: SmartTransaction,
-    groups: OrderGroup[],
-    options?: {
-      isFulfilledOnly?: boolean;
-    },
-  ): void {
-    this.order.melt(tx, groups, options);
+  public buildBaseTransaction(
+    txLike: ccc.TransactionLike,
+    steps: CollectSteps,
+    withdrawalRequest?: { deposits: IckbDepositCell[]; lock: ccc.Script },
+  ): ccc.Transaction {
+    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;
   }
 
   /**
-   * Retrieves the L1 state from the blockchain.
-   *
-   * The method performs the following:
-   * - Obtains the current block tip and calculates the exchange ratio.
-   * - Fetches available CKB and the maturing CKB based on bot capacities and deposit snapshots.
-   * - Filters orders into user-owned and system orders based on the provided locks.
-   * - Estimates user-owned orders maturity.
+   * Completes iCKB inputs, iCKB change, plain change, and the fee from the cells it is given.
    *
-   * @param client - The blockchain client interface.
-   * @param locks - An array of lock scripts used to filter user cells.
-   * @returns A promise that resolves to an object containing:
-   *   - system: The system state (fee rate, tip header, exchange ratio, order pool, etc.).
-   *   - user: The user's orders grouped as an array of OrderGroup.
+   * @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 getL1State(
-    client: ccc.Client,
-    locks: ccc.Script[],
-  ): Promise<{ system: SystemState; user: { orders: OrderGroup[] } }> {
-    const tip = await client.getTipHeader();
-    const exchangeRatio = Ratio.from(ickbExchangeRatio(tip));
-
-    // Parallel fetching of system components.
-    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: OrderGroup[] = [];
-    const systemOrders: OrderCell[] = [];
-    for (const group of orders) {
-      if (group.isOwner(...locks)) {
-        userOrders.push(group);
+  public async completeTransaction(
+    txLike: ccc.TransactionLike,
+    options: CompleteIckbTransactionOptions,
+  ): Promise<ccc.Transaction> {
+    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<string>();
+    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 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;
+  }
 
-      const { order } = group;
-      const info = order.data.info;
-      if (
-        (order.isCkb2UdtMatchable() && info.ckb2UdtCompare(midInfo) < 0) ||
-        (order.isUdt2CkbMatchable() && info.udt2CkbCompare(midInfo) < 0)
-      ) {
-        systemOrders.push(order);
+  /** iCKB: what the outputs need first, then the sweep while the limit allows, then change. */
+  private async completeIckb(
+    tx: ccc.Transaction,
+    client: ccc.Client,
+    changeLock: ccc.Script,
+    ickbCells: readonly ccc.Cell[],
+    protocolCells: readonly ProtocolCell[],
+  ): Promise<void> {
+    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;
       }
+      tx.addInput(cell);
+      balance += udtBalance(cell);
     }
-
-    const system = {
-      feeRate,
-      tip,
-      exchangeRatio,
-      orderPool: systemOrders,
-      ckbAvailable,
-      ckbMaturing,
-    };
-
-    // Estimates user orders maturity.
-    for (const { order } of userOrders) {
-      order.maturity = IckbSdk.maturity(order, system);
+    if (balance < required) {
+      throw new IckbError(`Insufficient iCKB, need ${String(required - balance)} more`, {
+        code: "insufficient_ickb",
+      });
     }
-
-    return {
-      system,
-      user: {
-        orders: userOrders,
-      },
-    };
+    this.ickbUdt.addChange(tx, changeLock, balance - required);
   }
+}
 
-  /**
-   * Retrieves available CKB and maturing CKB values from the blockchain.
-   *
-   * This method:
-   * - Fetches bot withdrawal requests and deposit snapshots.
-   * - Aggregates available CKB balances from bot capacities.
-   * - Calculates maturing CKB values (with their expected maturity timestamps)
-   *   based on deposit pool snapshots or via direct deposit cell lookups.
-   * - Sorts and cumulatively sums the maturing values for later lookup.
-   *
-   * @param client - The blockchain client used for fetching data.
-   * @param tip - The current block tip header.
-   * @returns A Promise that resolves with:
-   *   - ckbAvailable: The total available CKB (as a FixedPoint).
-   *   - ckbMaturing: An array of maturing CKB objects containing the cumulative CKB
-   *                  and the associated maturity timestamp.
-   */
-  private async getCkb(
-    client: ccc.Client,
-    tip: ccc.ClientBlockHeader,
-  ): Promise<{
-    ckbAvailable: ccc.FixedPoint;
-    ckbMaturing: CkbCumulative[];
-  }> {
-    const opts = {
-      onChain: true,
-      tip,
-    };
+/** Whether the transaction already carries any input or output. */
+function hasTransactionActivity(tx: ccc.Transaction): boolean {
+  return tx.inputs.length > 0 || tx.outputs.length > 0;
+}
 
-    // Start fetching bot iCKB withdrawal requests.
-    const promiseBotWithdrawals = collect(
-      this.ownedOwner.findWithdrawalGroups(client, this.bots, opts),
-    );
+/** An order the market can fill at a gain: priced past the DAO ratio on its matchable side. */
+function isPastPar(group: OrderGroup, exchangeRatio: Ratio): boolean {
+  const { order } = group;
+  const { info } = order.data;
+  return (
+    (order.isCkb2UdtMatchable() && info.ckbToUdt.compare(exchangeRatio) < 0) ||
+    (order.isUdt2CkbMatchable() && exchangeRatio.compare(info.udtToCkb) < 0)
+  );
+}
 
-    // Initialize deposit pool snapshot.
-    let poolSnapshotHex: ccc.Hex = "0x";
-    let poolSnapshotEpoch = Epoch.from([0n, 0n, 1n]);
-    // Map to track each bot's available CKB (minus a reserved amount for internal operations).
-    const bot2Ckb = new Map<string, ccc.FixedPoint>();
-    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);
-
-      // Find the most recent deposit pool snapshot from bot cell output data.
-      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;
-        }
-      }
-    }
+function conversionFailure(
+  reason: Exclude<ConversionTransactionFailureReason, "amount-too-small">,
+  estimatedMaturity: bigint,
+): ConversionTransactionResult {
+  return { ok: false, reason, estimatedMaturity };
+}
 
-    const ckbMaturing = new Array<{
-      ckbValue: ccc.FixedPoint;
-      maturity: ccc.Num;
-    }>();
-    for (const wr of await promiseBotWithdrawals) {
-      if (wr.owned.isReady) {
-        // Update the bot's CKB based on withdrawal if the bot is ready.
-        const key = hexFrom(wr.owner.cell.cellOutput.lock);
-        const ckb = (bot2Ckb.get(key) ?? reserved) + wr.ckbValue;
-        bot2Ckb.set(key, ckb);
-        continue;
-      }
+/** A plan always carries a deposit or an order, else it would be a collection. */
+function conversionKind(
+  hasDirect: boolean,
+  hasOrder: boolean,
+): "direct" | "order" | "direct-plus-order" {
+  if (hasDirect && hasOrder) {
+    return "direct-plus-order";
+  }
+  return hasDirect ? "direct" : "order";
+}
 
-      // Otherwise, add to maturing amounts.
-      ckbMaturing.push({
-        ckbValue: wr.ckbValue,
-        maturity: wr.owned.maturity.toUnix(tip),
-      });
-    }
+/** Whether every liquid cell became an input; false when the input limit cut the sweep. */
+function sweepsAll(tx: ccc.Transaction, cells: readonly ccc.Cell[]): boolean {
+  const spent = new Set(tx.inputs.map((input) => input.previousOutput.toHex()));
+  return cells.every((cell) => spent.has(cell.outPoint.toHex()));
+}
 
-    // Sum available CKB across all bot lock scripts.
-    let ckbAvailable = 0n;
-    for (const ckb of bot2Ckb.values()) {
-      if (ckb > 0n) {
-        ckbAvailable += ckb;
-      }
-    }
+async function isOwnLock(signer: ccc.Signer, lock: ccc.Script): Promise<boolean> {
+  return (await signer.getAddressObjs()).some(({ script }) => script.eq(lock));
+}
 
-    // Estimate available CKB from deposit pool snapshot.
-    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
-                ? // If the bin has already started, assume worst-case timing.
-                  end.add(oneCycle).toUnix(tip)
-                : // Otherwise, use the bin end as the maturity.
-                  end.toUnix(tip),
-          });
-        }
+function udtBalance(cell: ccc.Cell): ccc.Num {
+  return ccc.udtBalanceFrom(cell.outputData);
+}
 
-        start = end;
+/** Adds cells while the input count stays under the limit; returns how many were added. */
+function sweep(tx: ccc.Transaction, cells: readonly ccc.Cell[]): number {
+  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: ccc.Transaction,
+  signer: ccc.Signer,
+  changeLock: ccc.Script,
+  feeRate: ccc.Num,
+  reserve: readonly ccc.Cell[],
+): Promise<void> {
+  const remaining = [...reserve];
+  for (;;) {
+    try {
+      await tx.completeFeeChangeToLock(signer, changeLock, feeRate, undefined, {
+        shouldAddInputs: false,
+      });
+      return;
+    } catch (error) {
+      if (!(error instanceof ccc.ErrorTransactionInsufficientCapacity)) {
+        throw error;
       }
-    } else {
-      // Without snapshot data, fetch deposits directly.
-      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);
     }
+  }
+}
 
-    // Sort maturing CKB entries by their maturity timestamp.
-    ckbMaturing.sort((a, b) => Number(a.maturity - b.maturity));
+/** Stable machine-readable SDK failures. */
+export type IckbErrorCode = "insufficient_capacity" | "insufficient_ickb";
 
-    // Calculate cumulative maturing CKB values.
-    let cumulative = 0n;
-    const ckbCumulativeMaturing: CkbCumulative[] = [];
-    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. */
+  public readonly code: IckbErrorCode;
 
-    return {
-      ckbAvailable,
-      ckbMaturing: ckbCumulativeMaturing,
-    };
+  /** Creates a typed SDK failure while preserving its cause. */
+  constructor(message: string, options: ErrorOptions & { code: IckbErrorCode }) {
+    super(message, options);
+    this.name = "IckbError";
+    this.code = options.code;
   }
 }
 
 /**
- * Represents the state of the system.
+ * 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 interface SystemState {
-  /** The fee rate for transactions. */
-  feeRate: ccc.Num;
-
-  /** The tip for the current block header. */
-  tip: ccc.ClientBlockHeader;
-
-  /** The exchange ratio between CKB and UDT. */
-  exchangeRatio: Ratio;
-
-  /** The order pool containing order cells matching system criteria. */
-  orderPool: OrderCell[];
-
-  /** The total available CKB (as FixedPoint). */
-  ckbAvailable: ccc.FixedPoint;
-
-  /** Array of CKB maturing entries with cumulative amounts and maturity timestamps. */
-  ckbMaturing: CkbCumulative[];
+export async function completeFirstFundable<T>(
+  candidates: Iterable<T>,
+  build: (candidate: T) => ccc.Transaction,
+  complete: (tx: ccc.Transaction) => Promise<ccc.Transaction>,
+): Promise<{ candidate: T; tx: ccc.Transaction }> {
+  let error: Error | undefined;
+  for (const candidate of candidates) {
+    try {
+      return { candidate, tx: await complete(build(candidate)) };
+    } catch (failure) {
+      if (!isFundabilityFailure(failure)) {
+        throw failure;
+      }
+      error = failure;
+    }
+  }
+  throw error ?? new Error("No candidate could be completed");
 }
 
 /**
- * Represents a cumulative CKB maturing entry.
+ * 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 interface CkbCumulative {
-  /** The cumulative CKB value (as FixedPoint) up to this maturity. */
-  ckbCumulative: ccc.FixedPoint;
-  /** The maturity timestamp (as ccc.Num). */
-  maturity: ccc.Num;
+export function isFundabilityFailure(error: unknown): error is Error {
+  return (
+    error instanceof IckbError ||
+    error instanceof ccc.ErrorTransactionInsufficientCapacity ||
+    error instanceof DaoOutputLimitError ||
+    error instanceof DaoHeaderIndexError
+  );
 }