@ickb/sdk 1000.0.81 → 9000.0.1

package/src/conversion/maturity.ts

@@ -0,0 +1,159 @@
+import type { ccc } from "@ckb-ccc/core";
+import { BOT_LOCK_UP, depositMaturity } from "../dao.ts";
+import type { IckbDepositCell } from "../logic.ts";
+import type { OrderGroup } from "../order/cells.ts";
+import { fillsWhole } from "../order/fill.ts";
+import type { Info } from "../order/info.ts";
+import { convert, ICKB_DEPOSIT_CAP } from "../udt.ts";
+import { compareBigInt, type ValueComponents } from "../utils/utils.ts";
+import type { MaturityOrderInput, SystemState } from "./types.ts";
+
+/**
+ * Assumed turn duration, allowing for restart delay, confirmation and slow reads.
+ * This is a modeling interval, not a bound on the runtime; see sdk/docs/pool_maturity_estimates.md.
+ */
+export const BOT_TURN_MS = 10n * 60n * 1000n;
+
+/**
+ * The estimated fill time of an order on the book or about to be placed, zero when it is
+ * already fulfilled. `takenDeposits` are the pool deposits the same plan withdraws
+ * directly, which cannot fill its order leg too. Dual-ratio orders never reach here: the
+ * scan drops them.
+ */
+export function maturity(
+  o: MaturityOrderInput,
+  system: SystemState,
+  takenDeposits: readonly IckbDepositCell[] = [],
+): bigint {
+  const { info, amounts, self } = maturityOrderParts(o);
+  const isCkb2Udt = info.isCkb2Udt();
+  const amount = isCkb2Udt ? amounts.ckbValue : amounts.udtValue;
+  if (amount === 0n) {
+    return 0n;
+  }
+
+  return isCkb2Udt
+    ? ckbToIckbOrderMaturity(info, amount, system, self)
+    : ickbToCkbOrderMaturity(info, amount, system, takenDeposits, self);
+}
+
+/** The order's terms, and its own out point when it is already on the book. */
+function maturityOrderParts(o: MaturityOrderInput): {
+  info: Info;
+  amounts: ValueComponents;
+  self: ccc.OutPoint | undefined;
+} {
+  if ("info" in o) {
+    return { ...o, self: undefined };
+  }
+
+  return {
+    info: o.data.info,
+    amounts: { ckbValue: o.ckbUnoccupied, udtValue: o.udtValue },
+    self: o.cell.outPoint,
+  };
+}
+
+/**
+ * A buyer waits for the bot to mint: the bot mints one cap-sized deposit per turn once its
+ * iCKB inventory is spent, and the inventory is unknown here, so the wait is one turn plus
+ * one per whole cap of positive net CKB demand (this request and buyers priced at least
+ * as well, less the iCKB sellers bring in). The model does not measure the bot's funds.
+ */
+function ckbToIckbOrderMaturity(
+  info: Info,
+  amount: bigint,
+  system: SystemState,
+  self: ccc.OutPoint | undefined,
+): bigint {
+  // An equal price counts as ahead: the bot fills ties in an order of its own choosing.
+  const buyersAhead = fillableOrders(system, true, self)
+    .filter((group) => group.order.data.info.ckbToUdt.compare(info.ckbToUdt) <= 0)
+    .reduce((ckb, group) => ckb + group.order.ckbUnoccupied, 0n);
+  const sellers = fillableOrders(system, false, self).reduce(
+    (udt, group) => udt + group.udtValue,
+    0n,
+  );
+  const demand = amount + buyersAhead - convert(false, sellers, system.exchangeRatio);
+  const capCkb = convert(false, ICKB_DEPOSIT_CAP, system.exchangeRatio);
+  const turns = demand > 0n ? 1n + demand / capCkb : 1n;
+  return system.tip.timestamp + BOT_TURN_MS * turns;
+}
+
+/**
+ * A seller waits for CKB: one deposit's worth of assumed working capital, zeroed when
+ * another fillable seller has sat beyond the threshold, plus dated pool supply. Return
+ * the first date covering demand, plus a turn. Insufficient supply falls back to the last
+ * date; this can understate an above-par ask's wait for further DAO growth.
+ */
+function ickbToCkbOrderMaturity(
+  info: Info,
+  amount: bigint,
+  system: SystemState,
+  takenDeposits: readonly IckbDepositCell[],
+  self: ccc.OutPoint | undefined,
+): bigint {
+  const sellers = fillableOrders(system, false, self);
+  const sellersAhead = sellers
+    .filter((group) => info.udtToCkb.compare(group.order.data.info.udtToCkb) <= 0)
+    .reduce((udt, group) => udt + group.udtValue, 0n);
+  // The CKB an order has already received belongs to its earlier fills; what it still
+  // needs is the remaining iCKB at its price.
+  const needed =
+    info.udtToCkb.convert(false, amount, true) +
+    convert(false, sellersAhead, system.exchangeRatio);
+  const taken = new Set(takenDeposits.map((deposit) => deposit.cell.outPoint.toHex()));
+  const steps = [
+    {
+      ckbValue: sellers.some((group) => sits(group, system))
+        ? 0n
+        : convert(false, ICKB_DEPOSIT_CAP, system.exchangeRatio),
+      at: system.tip.timestamp,
+    },
+    // A claim the bot can no longer request in time rolls a cycle: the bot's rule, not the
+    // caller's, since the bot is the one making the requests.
+    ...system.poolDeposits
+      .filter((deposit) => !taken.has(deposit.cell.outPoint.toHex()))
+      .map((deposit) => ({
+        ckbValue: deposit.ckbValue,
+        at: depositMaturity(deposit.claimEpoch, system.tip, BOT_LOCK_UP).maturity.toUnix(
+          system.tip,
+        ),
+      }))
+      .toSorted((left, right) => compareBigInt(left.at, right.at)),
+  ];
+  let supply = 0n;
+  let at = system.tip.timestamp;
+  for (const step of steps) {
+    supply += step.ckbValue;
+    at = step.at;
+    if (supply >= needed) {
+      break;
+    }
+  }
+  return at + BOT_TURN_MS;
+}
+
+/** The book orders the bot would take whole in the given direction, this one aside. */
+function fillableOrders(
+  system: SystemState,
+  isCkb2Udt: boolean,
+  self: ccc.OutPoint | undefined,
+): OrderGroup[] {
+  return system.orderPool.filter(
+    (group) =>
+      (self === undefined || !group.order.cell.outPoint.eq(self)) &&
+      fillsWhole(group, isCkb2Udt, system.exchangeRatio, system.feeRate),
+  );
+}
+
+/**
+ * Whether the order has been on the book for more than a turn, a twenty-fourth of an
+ * epoch in blocks: the bot has seen it and left it. An uncommitted origin is fresh.
+ */
+function sits(group: OrderGroup, { tip }: SystemState): boolean {
+  return (
+    group.blockNumber !== undefined &&
+    tip.number - group.blockNumber > tip.epoch.denominator / 24n
+  );
+}

package/src/conversion/plans.ts

@@ -0,0 +1,144 @@
+import { DAO_OUTPUT_LIMIT } from "../dao.ts";
+import { readyDeposits, type IckbDepositCell } from "../logic.ts";
+import { ICKB_DEPOSIT_CAP, convert } from "../udt.ts";
+import { maxBigInt } from "../utils/utils.ts";
+import {
+  DEFAULT_ORDER_FEE,
+  DEFAULT_ORDER_FEE_BASE,
+  estimateConversionOrder,
+  estimateIckbToCkbOrder,
+} from "./estimate.ts";
+import { sumUdt } from "./projection.ts";
+import type {
+  CkbToIckbConversionPlan,
+  ConversionOrder,
+  ConversionTransactionOptions,
+  IckbToCkbConversionPlan,
+} from "./types.ts";
+import {
+  fitWithdrawalDeposits,
+  ringSurplusDepositFilter,
+  sortByClaim,
+} from "./withdrawal_ring.ts";
+
+// The planner starts at the most `DAO_OUTPUT_LIMIT` can hold, one change output beside the
+// deposits, and the completion walk steps down from there when change and fees need more room.
+const MAX_PLANNED_DEPOSITS = DAO_OUTPUT_LIMIT - 1;
+
+/**
+ * Plans every deposit count from the most the amount covers down to zero, skipping
+ * unrepresentable remainders. Cap-sized deposits plus an order for the rest is the cheapest
+ * shape at every amount: a deposit's 82 CKB of occupied capacity goes to its withdrawer
+ * (0.082% at the cap, 8.2% at the contract's 1,000 CKB minimum), the excess above the cap
+ * is discounted 10%, and an order costs 0.01% at any size; the cap's CKB value grows with
+ * the DAO rate, so the order stays cheaper until the cap is worth 820,000 CKB.
+ */
+export function ckbToIckbConversionPlans(
+  options: ConversionTransactionOptions,
+): CkbToIckbConversionPlan[] {
+  const { amount, context } = options;
+  const depositCapacity = convert(false, ICKB_DEPOSIT_CAP, context.system.exchangeRatio);
+  const depositQuotient = depositCapacity === 0n ? 0n : amount / depositCapacity;
+  const maxDeposits =
+    depositQuotient > BigInt(MAX_PLANNED_DEPOSITS)
+      ? MAX_PLANNED_DEPOSITS
+      : Number(depositQuotient);
+  const plans: CkbToIckbConversionPlan[] = [];
+  for (let depositCount = maxDeposits; depositCount >= 0; depositCount -= 1) {
+    const plan = ckbToIckbConversionPlan(options, depositCapacity, depositCount);
+    if (plan !== undefined) {
+      plans.push(plan);
+    }
+  }
+  return plans;
+}
+
+/**
+ * Plans every prefix of the greedy ready-deposit selection, longest first, the remainder as
+ * an order: direct withdrawals are free and their claim date certain, an order pays a fee
+ * and waits for the bot, so the completion walk takes the most direct plan it can fund.
+ * The prefix shape keeps ring classification frozen: a prefix of surplus deposits stays
+ * surplus with the same anchors pinned.
+ */
+export function ickbToCkbConversionPlans(
+  options: ConversionTransactionOptions,
+  poolDeposits: readonly IckbDepositCell[],
+): IckbToCkbConversionPlan[] {
+  const { amount, context } = options;
+  const { tip, lockUp } = context.system;
+  const ready = readyDeposits(poolDeposits, tip, lockUp);
+  const isSurplus = ringSurplusDepositFilter(poolDeposits, ready);
+  const deposits = fitWithdrawalDeposits(sortByClaim(ready.filter(isSurplus)), amount);
+  const plans: IckbToCkbConversionPlan[] = [];
+  for (let count = deposits.length; count >= 0; count -= 1) {
+    const plan = ickbToCkbConversionPlan(options, deposits.slice(0, count));
+    if (plan !== undefined) {
+      plans.push(plan);
+    }
+  }
+  return plans;
+}
+
+function ckbToIckbConversionPlan(
+  options: ConversionTransactionOptions,
+  depositCapacity: bigint,
+  depositCount: number,
+): CkbToIckbConversionPlan | undefined {
+  const { amount, context } = options;
+  const remainder = amount - depositCapacity * BigInt(depositCount);
+  let estimatedMaturity = context.estimatedMaturity;
+  let order: ConversionOrder | undefined;
+
+  if (remainder > 0n) {
+    const amounts = { ckbValue: remainder, udtValue: 0n };
+    const estimate = estimateConversionOrder(true, amounts, context.system, {
+      fee: DEFAULT_ORDER_FEE,
+      feeBase: DEFAULT_ORDER_FEE_BASE,
+    });
+    if (estimate?.maturity === undefined) {
+      return undefined;
+    }
+    estimatedMaturity = maxBigInt(estimatedMaturity, estimate.maturity);
+    order = { amounts, estimate };
+  }
+
+  return {
+    depositCapacity,
+    depositCount,
+    estimatedMaturity,
+    ...(order === undefined ? {} : { order }),
+  };
+}
+
+function ickbToCkbConversionPlan(
+  options: ConversionTransactionOptions,
+  selectedDeposits: IckbDepositCell[],
+): IckbToCkbConversionPlan | undefined {
+  const { amount, context } = options;
+  let estimatedMaturity = context.estimatedMaturity;
+  // Selected deposits are ready, so their sampled claim is their date.
+  for (const deposit of selectedDeposits) {
+    estimatedMaturity = maxBigInt(
+      estimatedMaturity,
+      deposit.claimEpoch.toUnix(context.system.tip),
+    );
+  }
+  const remainder = amount - sumUdt(selectedDeposits);
+  let order: ConversionOrder | undefined;
+  if (remainder > 0n) {
+    const amounts = { ckbValue: 0n, udtValue: remainder };
+    // The deposits this plan withdraws directly cannot fill its order leg too.
+    const estimate = estimateIckbToCkbOrder(amounts, context.system, selectedDeposits);
+    if (estimate === undefined) {
+      return undefined;
+    }
+    estimatedMaturity = maxBigInt(estimatedMaturity, estimate.maturity);
+    order = { amounts, estimate };
+  }
+
+  return {
+    estimatedMaturity,
+    ...(order === undefined ? {} : { order }),
+    selectedDeposits,
+  };
+}

package/src/conversion/projection.ts

@@ -0,0 +1,128 @@
+import { ccc } from "@ckb-ccc/core";
+import { DAO_HEADER_INDEX_LIMIT } from "../dao.ts";
+import type { OrderGroup } from "../order/cells.ts";
+import type { WithdrawalGroup } from "../owned_owner.ts";
+import { maxBigInt } from "../utils/utils.ts";
+import { maturity } from "./maturity.ts";
+import type {
+  AccountAvailabilityProjection,
+  AccountState,
+  ConversionTransactionContextProjection,
+  SystemState,
+} from "./types.ts";
+
+/**
+ * Builds the conversion planner context from account state and the caller's own orders,
+ * split by what it will melt: `available` orders are collected and budgeted as account
+ * value, `pending` ones stay on the book.
+ */
+export function projectConversionTransactionContext(
+  system: SystemState,
+  account: AccountState,
+  orders: { available: OrderGroup[]; pending: OrderGroup[] },
+): ConversionTransactionContextProjection {
+  const projection = projectAccountAvailability(account, orders);
+  const estimatedMaturity = [
+    ...projection.pendingWithdrawals.map((group) =>
+      group.owned.maturity.toUnix(system.tip),
+    ),
+    ...projection.pendingOrders.map((group) => maturity(group.order, system)),
+  ].reduce(maxBigInt, system.tip.timestamp);
+
+  return {
+    projection,
+    context: {
+      system,
+      receipts: account.receipts,
+      readyWithdrawals: projection.readyWithdrawals,
+      availableOrders: projection.availableOrders,
+      cells: [...account.capacityCells, ...account.nativeUdtCells],
+      ckbAvailable: projection.ckbAvailable,
+      ickbAvailable: projection.ickbAvailable,
+      estimatedMaturity,
+    },
+  };
+}
+
+/**
+ * Splits wallet-owned CKB and iCKB into immediately available and pending value.
+ */
+export function projectAccountAvailability(
+  account: AccountState,
+  {
+    available: availableOrders,
+    pending: pendingOrders,
+  }: { available: OrderGroup[]; pending: OrderGroup[] },
+): AccountAvailabilityProjection {
+  const { readyWithdrawals, pendingWithdrawals } = splitWithdrawals(
+    account.withdrawalGroups,
+  );
+  // An iCKB cell's capacity is the owner's CKB too: completion spends it like a plain cell.
+  const ckbNative = sumValues(
+    [...account.capacityCells, ...account.nativeUdtCells],
+    (cell) => cell.cellOutput.capacity,
+  );
+  const ickbNative = sumValues(account.nativeUdtCells, (cell) =>
+    ccc.udtBalanceFrom(cell.outputData),
+  );
+  const ckbAvailable =
+    ckbNative +
+    sumCkb(account.receipts) +
+    sumCkb(readyWithdrawals) +
+    sumCkb(availableOrders);
+  const ickbAvailable = ickbNative + sumUdt(account.receipts) + sumUdt(availableOrders);
+  const ckbPending = sumCkb(pendingWithdrawals) + sumCkb(pendingOrders);
+  const ickbPending = sumUdt(pendingOrders);
+
+  return {
+    ckbNative,
+    ickbNative,
+    ckbAvailable,
+    ickbAvailable,
+    ckbPending,
+    ickbPending,
+    ckbBalance: ckbAvailable + ckbPending,
+    ickbBalance: ickbAvailable + ickbPending,
+    readyWithdrawals,
+    pendingWithdrawals,
+    availableOrders,
+    pendingOrders,
+  };
+}
+
+/**
+ * `ready` is the batch one transaction can complete: the deployed DAO script addresses a
+ * withdrawal's deposit header only below `DAO_HEADER_INDEX_LIMIT`, and the builder puts
+ * those headers first, so matured withdrawals past that count wait a turn.
+ */
+function splitWithdrawals(withdrawalGroups: readonly WithdrawalGroup[]): {
+  readyWithdrawals: WithdrawalGroup[];
+  pendingWithdrawals: WithdrawalGroup[];
+} {
+  const readyWithdrawals: WithdrawalGroup[] = [];
+  const pendingWithdrawals: WithdrawalGroup[] = [];
+  for (const group of withdrawalGroups) {
+    if (group.owned.isReady && readyWithdrawals.length < DAO_HEADER_INDEX_LIMIT) {
+      readyWithdrawals.push(group);
+    } else {
+      pendingWithdrawals.push(group);
+    }
+  }
+  return { readyWithdrawals, pendingWithdrawals };
+}
+
+function sumCkb(items: ReadonlyArray<{ ckbValue: bigint }>): bigint {
+  return sumValues(items, (item) => item.ckbValue);
+}
+
+export function sumUdt(items: ReadonlyArray<{ udtValue: bigint }>): bigint {
+  return sumValues(items, (item) => item.udtValue);
+}
+
+function sumValues<T>(items: readonly T[], project: (item: T) => bigint): bigint {
+  let total = 0n;
+  for (const item of items) {
+    total += project(item);
+  }
+  return total;
+}