@ickb/sdk 1000.0.82 → 9001.0.0

package/src/conversion/types.ts

@@ -0,0 +1,302 @@
+import type { ccc } from "@ckb-ccc/core";
+import type { BroadcastDeadline, LockUpPolicy } from "../dao.ts";
+import type { IckbDepositCell, LogicManager, ReceiptCell } from "../logic.ts";
+import type { OrderCell, OrderGroup } from "../order/cells.ts";
+import type { Info } from "../order/info.ts";
+import type { OrderManager } from "../order/order.ts";
+import type { Ratio } from "../order/ratio.ts";
+import type { OwnedOwnerManager, WithdrawalGroup } from "../owned_owner.ts";
+import type { IckbUdt, ProtocolCell } from "../udt.ts";
+import type { ValueComponents } from "../utils/utils.ts";
+
+/**
+ * Direction requested by a conversion transaction.
+ */
+export type ConversionDirection = "ckb-to-ickb" | "ickb-to-ckb";
+
+/**
+ * Snapshot used to plan one wallet conversion transaction.
+ */
+export interface ConversionTransactionContext {
+  /** Public system state sampled for conversion planning. */
+  system: SystemState;
+  /** User receipt cells available for deposit completion. */
+  receipts: ReceiptCell[];
+  /** User withdrawal groups ready to complete. */
+  readyWithdrawals: WithdrawalGroup[];
+  /** Order groups available for collection or budgeting as account value. */
+  availableOrders: OrderGroup[];
+  /** The wallet's liquid cells, plain CKB and iCKB, that completion funds from and sweeps. */
+  cells: ccc.Cell[];
+  /** Projected CKB available to the wallet after pending state is considered. */
+  ckbAvailable: bigint;
+  /** Projected iCKB available to the wallet after pending state is considered. */
+  ickbAvailable: bigint;
+  /**
+   * The latest date at which everything the wallet has converting, plus this request, is
+   * collectable; an amount of zero is the collection itself.
+   */
+  estimatedMaturity: bigint;
+}
+
+/**
+ * Inputs and policy limits for building one conversion transaction.
+ */
+export interface ConversionTransactionOptions {
+  /** Conversion direction to build. */
+  direction: ConversionDirection;
+
+  /** Requested input amount in the source asset. */
+  amount: bigint;
+
+  /**
+   * Lock that owns every cell the transaction creates for the user, the conversion outputs
+   * and the change; the signer's recommended lock by default. Completion sweeps the liquid
+   * cells along within its input limit, so a foreign lock redirects those funds too.
+   */
+  lock?: ccc.Script;
+
+  /** Signer whose committed cells fund the completed transaction. */
+  signer: ccc.Signer;
+
+  /** Sampled state used to plan this conversion. */
+  context: ConversionTransactionContext;
+}
+
+/**
+ * Reason a conversion transaction could not be built without throwing.
+ */
+export type ConversionTransactionFailureReason =
+  | "amount-negative"
+  | "insufficient-ckb"
+  | "insufficient-ickb"
+  | "amount-too-small"
+  | "nothing-to-do";
+
+/**
+ * A dust iCKB-to-CKB order: too small for the default fee to clear the estimate threshold,
+ * so it pays the smallest fee that does. For callers to surface in UI or logs.
+ */
+export interface ConversionNotice {
+  /** iCKB input amount that triggered the notice. */
+  inputIckb: bigint;
+
+  /** CKB output estimate for the noticed path. */
+  outputCkb: bigint;
+
+  /** CKB incentive associated with the noticed path. */
+  incentiveCkb: bigint;
+}
+
+/** Composition category selected for a built conversion. */
+export type ConversionKind = "direct" | "order" | "direct-plus-order" | "collect-only";
+
+/**
+ * Result of attempting to build a conversion transaction.
+ */
+export type ConversionTransactionResult =
+  | {
+      ok: true;
+      /** Completed transaction, funded from the signer's committed cells. Callers own signing and send. */
+      tx: ccc.Transaction;
+      /** Estimated maturity timestamp for the conversion result. */
+      estimatedMaturity: bigint;
+      /** Composition of the selected conversion path. */
+      conversionKind: ConversionKind;
+      /** Optional notice about the selected path. */
+      conversionNotice?: ConversionNotice;
+      /**
+       * True when every liquid cell of the context is an input. False when the input limit
+       * left some behind: a move to another lock then needs another transaction.
+       */
+      isSweepComplete: boolean;
+      /**
+       * The epoch the transaction must be broadcast before for its withdrawal requests to
+       * claim at their sampled dates (`system.lockUp`); absent when it requests none.
+       */
+      broadcastBefore?: BroadcastDeadline;
+    }
+  | {
+      ok: false;
+      reason: "amount-too-small";
+      /** Best available maturity estimate from the input context. */
+      estimatedMaturity: bigint;
+      /**
+       * The smallest amount this direction accepts at the current fee rate, in the
+       * request's unit (CKB shannons or iCKB), so a caller can name it.
+       */
+      minimum: bigint;
+    }
+  | {
+      ok: false;
+      /** Machine-readable failure reason. */
+      reason: Exclude<ConversionTransactionFailureReason, "amount-too-small">;
+      /** Best available maturity estimate from the input context. */
+      estimatedMaturity: bigint;
+    };
+
+/**
+ * Options for completing a partial iCKB transaction before signing and sending.
+ */
+export interface CompleteIckbTransactionOptions {
+  /** Signer that prepares the transaction; its recommended lock owns the change by default. */
+  signer: ccc.Signer;
+
+  /** Lock that owns the change, iCKB and plain, when not the signer's recommended lock. */
+  lock?: ccc.Script;
+
+  /** Fee rate passed to CCC fee completion. */
+  feeRate: ccc.Num;
+
+  /** The signer's known liquid cells, plain CKB and iCKB, from the account state already read. */
+  cells: ccc.Cell[];
+
+  /**
+   * The receipts and iCKB deposits the transaction may spend, valued by the state read;
+   * any superset works, since only the spent ones are summed.
+   */
+  protocolCells: readonly ProtocolCell[];
+
+  /**
+   * The header the plan was priced at, the state read's `system.tip`, named as a header
+   * dep: the chain refuses a transaction whose deps are off the main chain, so a header a
+   * node invented, whose DAO rate set the exchange ratio, cannot price an accepted
+   * transaction.
+   */
+  tip: ccc.ClientBlockHeader;
+}
+
+/**
+ * Quote details for one order-based conversion path.
+ */
+export interface ConversionOrderEstimate {
+  /** Output amount after applying the order ratio and fee. */
+  convertedAmount: ccc.FixedPoint;
+  /** CKB fee component embedded in the order conversion. */
+  ckbFee: ccc.FixedPoint;
+  /** Order info that should be encoded into a created order. */
+  info: Info;
+  /** Estimated maturity timestamp, or `undefined` when it cannot be estimated. */
+  maturity: ccc.Num | undefined;
+  /** A non-fatal notice about the path this estimate took, for the caller to surface. */
+  notice?: ConversionNotice;
+}
+
+/**
+ * Input accepted by maturity estimation, either a live order cell or raw order data plus values.
+ */
+export type MaturityOrderInput =
+  | OrderCell
+  | {
+      info: Info;
+      amounts: ValueComponents;
+    };
+
+/**
+ * Raw wallet-owned cells and grouped iCKB state sampled from L1.
+ */
+export interface AccountState {
+  /** Plain capacity cells owned by the account locks. */
+  capacityCells: ccc.Cell[];
+  /** Native iCKB xUDT cells owned by the account locks. */
+  nativeUdtCells: ccc.Cell[];
+  /** Receipt cells owned by the account. */
+  receipts: ReceiptCell[];
+  /** Withdrawal groups owned by the account. */
+  withdrawalGroups: WithdrawalGroup[];
+}
+
+/**
+ * Account balances split into available, pending, and order/withdrawal buckets.
+ */
+export interface AccountAvailabilityProjection {
+  /**
+   * CKB in the account's liquid cells, plain and iCKB alike: what the wallet shows and what
+   * the next transaction spends, before the change cells, an order's master cell and the
+   * fee it must fund on top.
+   */
+  ckbNative: bigint;
+  /** iCKB in the account's native iCKB cells. */
+  ickbNative: bigint;
+  /** `ckbNative` plus the CKB the receipts, ready withdrawals and collectable orders return. */
+  ckbAvailable: bigint;
+  /** `ickbNative` plus the iCKB the receipts and collectable orders return. */
+  ickbAvailable: bigint;
+  /** CKB pending in withdrawals or orders. */
+  ckbPending: bigint;
+  /** iCKB pending in withdrawals or orders. */
+  ickbPending: bigint;
+  /** Total CKB balance including pending positions. */
+  ckbBalance: bigint;
+  /** Total iCKB balance including pending positions. */
+  ickbBalance: bigint;
+  /**
+   * Matured withdrawal groups one transaction can complete: at most the deposit-header slots
+   * the DAO script addresses (`DAO_HEADER_INDEX_LIMIT`), which the deposit headers hold alone.
+   */
+  readyWithdrawals: WithdrawalGroup[];
+  /** Withdrawal groups still waiting for DAO maturity or for a header slot in a later turn. */
+  pendingWithdrawals: WithdrawalGroup[];
+  /** Order groups available for collection or budgeting as account value. */
+  availableOrders: OrderGroup[];
+  /** Order groups that are owned but unavailable or unresolved. */
+  pendingOrders: OrderGroup[];
+}
+
+/**
+ * Combined projection and transaction-planning context for one sampled account state.
+ */
+export interface ConversionTransactionContextProjection {
+  /** User-facing availability projection. */
+  projection: AccountAvailabilityProjection;
+  /** Builder-facing transaction context derived from the same sampled state. */
+  context: ConversionTransactionContext;
+}
+
+/**
+ * Public sampled system state used for quotes, maturity, and conversion planning.
+ */
+export interface SystemState {
+  /** The fee rate for transactions. */
+  feeRate: ccc.Num;
+  /** The sampled tip's parent, this L1 scan's anchor. It may be stale after scans complete. */
+  tip: ccc.ClientBlockHeader;
+  /** The exchange ratio between CKB and UDT. */
+  exchangeRatio: Ratio;
+  /** Every order past par on the book, the wallet's own included: what the bot can fill. */
+  orderPool: OrderGroup[];
+  /** Every iCKB pool deposit with its claim epoch at this tip: the CKB supply. */
+  poolDeposits: IckbDepositCell[];
+  /** The caller's withdrawal timing rules, which every builder and the sender follow. */
+  lockUp: LockUpPolicy;
+}
+
+/** Manager set that builds one iCKB SDK instance. */
+export interface SdkManagers {
+  /** iCKB xUDT manager with receipt and DAO deposit aware completion. */
+  ickbUdt: IckbUdt;
+  /** Owned-owner manager for withdrawal request and claim cells. */
+  ownedOwner: OwnedOwnerManager;
+  /** iCKB Logic manager for deposits and receipts. */
+  ickbLogic: LogicManager;
+  /** Limit order manager. */
+  order: OrderManager;
+}
+
+export interface ConversionOrder {
+  amounts: ValueComponents;
+  estimate: ConversionOrderEstimate;
+}
+
+export interface CkbToIckbConversionPlan {
+  depositCapacity: bigint;
+  depositCount: number;
+  estimatedMaturity: bigint;
+  order?: ConversionOrder;
+}
+
+export interface IckbToCkbConversionPlan {
+  estimatedMaturity: bigint;
+  order?: ConversionOrder;
+  selectedDeposits: IckbDepositCell[];
+}

package/src/conversion/withdrawal_ring.ts

@@ -0,0 +1,122 @@
+import { ccc } from "@ckb-ccc/core";
+import { DAO_OUTPUT_LIMIT } from "../dao.ts";
+import type { IckbDepositCell } from "../logic.ts";
+import { ICKB_DEPOSIT_CAP } from "../udt.ts";
+
+/**
+ * Ring segment of pool deposits grouped by maturity around the DAO cycle.
+ */
+export interface RingSegment {
+  /** Deposits assigned to this segment. */
+  deposits: IckbDepositCell[];
+
+  /** Total iCKB value of deposits in this segment. */
+  udtValue: bigint;
+}
+
+/**
+ * Splits pool deposits into power-of-two maturity ring segments, one segment per two
+ * deposit caps of pool iCKB.
+ */
+export function ringSegments(poolDeposits: readonly IckbDepositCell[]): RingSegment[] {
+  // Value, not count: zero-value deposits, made without iCKB Logic running, must not add segments.
+  // Two caps per segment, not one: the room the bot's own fills need, see node/docs/policy.md.
+  const totalUdt = poolDeposits.reduce((sum, deposit) => sum + deposit.udtValue, 0n);
+  let segmentCount = 1;
+  while (BigInt(segmentCount) * 2n * ICKB_DEPOSIT_CAP < totalUdt) {
+    segmentCount *= 2;
+  }
+  const segments = Array.from({ length: segmentCount }, (): RingSegment => ({
+    deposits: [],
+    udtValue: 0n,
+  }));
+
+  // The ring is one DAO cycle round, so a claim rolled a cycle lands in the same segment.
+  for (const deposit of poolDeposits) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- ringSegmentIndex returns 0 <= index < segmentCount.
+    const segment = segments[ringSegmentIndex(deposit.claimEpoch, segmentCount)]!;
+    segment.deposits.push(deposit);
+    segment.udtValue += deposit.udtValue;
+  }
+
+  return segments;
+}
+
+/** The segment index an epoch falls in, for a deposit's claim or the tip. */
+export function ringSegmentIndex(epoch: ccc.Epoch, segmentCount: number): number {
+  const { denominator } = epoch;
+  if (denominator <= 0n) {
+    throw new Error("Epoch denominator must be positive");
+  }
+  const scaled = epoch.integer * denominator + epoch.numerator;
+  const ring = ccc.Epoch.OneNervosDaoCycle.integer * denominator;
+  const wrapped = ((scaled % ring) + ring) % ring;
+  return Number((wrapped * BigInt(segmentCount)) / ring);
+}
+
+/**
+ * Returns a filter that excludes the ring anchor deposits from surplus selection: each
+ * segment keeps its anchor, the largest deposit not in `ready`, else the largest one.
+ */
+export function ringSurplusDepositFilter(
+  poolDeposits: readonly IckbDepositCell[],
+  ready: readonly IckbDepositCell[],
+): (deposit: IckbDepositCell) => boolean {
+  const isReady = new Set(ready.map((deposit) => deposit.cell.outPoint.toHex()));
+  const anchors = new Set(
+    ringSegments(poolDeposits).flatMap((segment) => {
+      const anchor = segment.deposits.reduce<IckbDepositCell | undefined>(
+        (best, deposit) =>
+          best === undefined || isBetterRingAnchor(deposit, best, isReady)
+            ? deposit
+            : best,
+        undefined,
+      );
+      return anchor === undefined ? [] : [anchor.cell.outPoint.toHex()];
+    }),
+  );
+  return (deposit) => !anchors.has(deposit.cell.outPoint.toHex());
+}
+
+function isBetterRingAnchor(
+  candidate: IckbDepositCell,
+  current: IckbDepositCell,
+  isReady: ReadonlySet<string>,
+): boolean {
+  const candidateReady = isReady.has(candidate.cell.outPoint.toHex());
+  if (candidateReady !== isReady.has(current.cell.outPoint.toHex())) {
+    return !candidateReady;
+  }
+  return candidate.udtValue > current.udtValue;
+}
+
+/**
+ * Walks the candidates in the given order and takes each one that still fits under
+ * `maxAmount`; the caller chooses the order, earliest claim first
+ * for a user (the wait they feel), surplus before anchors for the bot. The chain stops at
+ * the most requests one transaction can carry, a request and its owner marker per deposit;
+ * completion steps down from there when change and fees need more room.
+ */
+export function fitWithdrawalDeposits(
+  candidates: readonly IckbDepositCell[],
+  maxAmount: bigint,
+): IckbDepositCell[] {
+  const deposits: IckbDepositCell[] = [];
+  let total = 0n;
+  for (const deposit of candidates) {
+    if (deposits.length === DAO_OUTPUT_LIMIT / 2) {
+      break;
+    }
+    if (total + deposit.udtValue > maxAmount) {
+      continue;
+    }
+    total += deposit.udtValue;
+    deposits.push(deposit);
+  }
+  return deposits;
+}
+
+/** Earliest claim first: the deposit that turns into CKB soonest. */
+export function sortByClaim(deposits: readonly IckbDepositCell[]): IckbDepositCell[] {
+  return deposits.toSorted((left, right) => left.claimEpoch.compare(right.claimEpoch));
+}

package/src/dao.ts

@@ -0,0 +1,196 @@
+import { ccc } from "@ckb-ccc/core";
+
+/**
+ * Maximum outputs accepted by deployed dao.c, not a general CKB consensus cap.
+ * A node upgrade cannot lift a limit in that deployed script.
+ */
+export const DAO_OUTPUT_LIMIT = 64;
+
+/**
+ * Deposit-header indices the deployed DAO script can address in a phase-2 witness.
+ *
+ * @remarks The script reads one byte of the u64 field (RFC 0023 erratum,
+ * nervosnetwork/rfcs pull 456).
+ */
+export const DAO_HEADER_INDEX_LIMIT = 256;
+
+/**
+ * Error thrown when a transaction exceeds the deployed DAO script's output limit.
+ */
+export class DaoOutputLimitError extends Error {
+  /**
+   * Creates an output-limit error for a transaction with too many outputs.
+   */
+  constructor(outputCount: number, options?: ErrorOptions) {
+    super(
+      `NervosDAO transaction has ${String(outputCount)} output cells, exceeding the limit of ${String(DAO_OUTPUT_LIMIT)}`,
+      options,
+    );
+    this.name = "DaoOutputLimitError";
+  }
+}
+
+/**
+ * Error thrown when a phase-2 withdrawal would reference a deposit header the
+ * deployed DAO script cannot address.
+ */
+export class DaoHeaderIndexError extends Error {
+  /**
+   * Creates a header-index error for one unrepresentable index.
+   */
+  constructor(headerIndex: number, options?: ErrorOptions) {
+    super(
+      `NervosDAO deposit header index ${String(headerIndex)} is not below ${String(DAO_HEADER_INDEX_LIMIT)}`,
+      options,
+    );
+    this.name = "DaoHeaderIndexError";
+  }
+}
+
+/**
+ * Throws when a transaction using the DAO script exceeds the Nervos DAO output limit. An
+ * oversized transaction with an unresolved input is refused too: whether it uses the DAO
+ * cannot be known, and the completion walk steps a plan down on this error either way.
+ */
+export function assertDaoOutputLimit(
+  txLike: ccc.TransactionLike,
+  daoScriptLike: ccc.ScriptLike,
+): void {
+  const tx = ccc.Transaction.from(txLike);
+  if (tx.outputs.length <= DAO_OUTPUT_LIMIT) {
+    return;
+  }
+  const daoScript = ccc.Script.from(daoScriptLike);
+  if (
+    tx.inputs.some(
+      (input) =>
+        input.cellOutput === undefined || input.cellOutput.type?.eq(daoScript) === true,
+    ) ||
+    tx.outputs.some((output) => output.type?.eq(daoScript) === true)
+  ) {
+    throw new DaoOutputLimitError(tx.outputs.length);
+  }
+}
+
+/** The canonical DAO deposit data payload: a zero Uint64, eight zero bytes. */
+export const DAO_DEPOSIT_DATA: ccc.Hex = "0x0000000000000000";
+
+/** Whether the cell is a DAO deposit of the given DAO script. */
+export function isDaoDeposit(cell: ccc.CellAny, daoScript: ccc.Script): boolean {
+  return (
+    cell.outputData === DAO_DEPOSIT_DATA && cell.cellOutput.type?.eq(daoScript) === true
+  );
+}
+
+/**
+ * Whether the cell uses the DAO script and is not deposit-shaped. This structural check
+ * does not decode the withdrawal request's deposit block number payload.
+ */
+export function isDaoWithdrawalRequest(
+  cell: ccc.CellAny,
+  daoScript: ccc.Script,
+): boolean {
+  return (
+    cell.outputData !== DAO_DEPOSIT_DATA && cell.cellOutput.type?.eq(daoScript) === true
+  );
+}
+
+/**
+ * A caller's timing rules for withdrawal requests, in epochs (the chain's clock, so no
+ * wall-clock drift). Selection: a deposit may be requested when its claim epoch is past
+ * `tip + minLockUp` (closer, the request would commit after the claim and lock for another
+ * cycle, so the deposit is judged on its next cycle) and before `tip + maxLockUp`.
+ * Broadcast: the signed request is sent only while the tip is before the earliest selected
+ * claim less `broadcastReserve`, else it is refused before broadcast.
+ */
+export interface LockUpPolicy {
+  minLockUp: ccc.Epoch;
+  maxLockUp: ccc.Epoch;
+  broadcastReserve: ccc.Epoch;
+}
+
+/**
+ * The bot's rules on the nominal four-hour epoch: claims twenty minutes to an hour out,
+ * sent while fifteen minutes remain. The bot signs at once, so a short window suffices, and
+ * the estimate models the pool's supply on it (`sdk/docs/pool_maturity_estimates.md`).
+ */
+export const BOT_LOCK_UP: LockUpPolicy = {
+  minLockUp: ccc.Epoch.from([0n, 1n, 12n]),
+  maxLockUp: ccc.Epoch.from([0n, 4n, 16n]),
+  broadcastReserve: ccc.Epoch.from([0n, 1n, 16n]),
+};
+
+/**
+ * A wallet's rules on the nominal four-hour epoch: claims two hours to three days out,
+ * sent while ninety minutes remain. A user may leave the request in a wallet popup.
+ */
+export const WALLET_LOCK_UP: LockUpPolicy = {
+  minLockUp: ccc.Epoch.from([0n, 1n, 2n]),
+  maxLockUp: ccc.Epoch.from([18n, 0n, 1n]),
+  broadcastReserve: ccc.Epoch.from([0n, 3n, 8n]),
+};
+
+/**
+ * How far a tip may trail the local clock under a policy: the selection margin less the
+ * broadcast reserve, the slack a stale tip would eat before a request commits after its
+ * claim. Five minutes for the bot, thirty for a wallet.
+ */
+export function tipMaxAgeMs(policy: LockUpPolicy): number {
+  // The span from the reserve to the margin, on CCC's nominal four-hour epoch.
+  return Number(
+    policy.minLockUp.toUnix({ epoch: policy.broadcastReserve, timestamp: 0n }),
+  );
+}
+
+/** Throws when `header` trails the local clock by more than `maxAgeMs`. */
+export function assertFresh(header: ccc.ClientBlockHeader, maxAgeMs: number): void {
+  if (BigInt(Date.now()) - header.timestamp > BigInt(maxAgeMs)) {
+    throw new Error(`Block ${header.hash} is more than ${String(maxAgeMs)} ms old`);
+  }
+}
+
+/** A deposit's maturity, rolled a cycle when its claim is too close, and whether it is ready. */
+export function depositMaturity(
+  claim: ccc.Epoch,
+  tip: ccc.ClientBlockHeader,
+  { minLockUp, maxLockUp }: LockUpPolicy,
+): { maturity: ccc.Epoch; isReady: boolean } {
+  const maturity =
+    claim.compare(minLockUp.add(tip.epoch)) <= 0
+      ? claim.add(ccc.Epoch.OneNervosDaoCycle)
+      : claim;
+  return { maturity, isReady: maxLockUp.add(tip.epoch).compare(maturity) > 0 };
+}
+
+/**
+ * The epoch a transaction requesting these deposits must be broadcast before: the earliest
+ * claim less the reserve; undefined when it requests none.
+ */
+export function broadcastDeadline(
+  claims: readonly ccc.Epoch[],
+  policy: LockUpPolicy,
+): BroadcastDeadline | undefined {
+  const earliest = claims.reduce<ccc.Epoch | undefined>(
+    (best, claim) => (best === undefined || claim.compare(best) < 0 ? claim : best),
+    undefined,
+  );
+  return earliest === undefined
+    ? undefined
+    : { epoch: earliest.sub(policy.broadcastReserve), tipMaxAgeMs: tipMaxAgeMs(policy) };
+}
+
+/**
+ * The epoch a withdrawal request must be broadcast before, and how far the tip read to
+ * check it may trail the clock, the policy's slack: a stale tip would pass the check late.
+ */
+export interface BroadcastDeadline {
+  epoch: ccc.Epoch;
+  tipMaxAgeMs: number;
+}
+
+/** Adds the header dep once. */
+export function pushHeaderDep(tx: ccc.Transaction, hash: ccc.Hex): void {
+  if (!tx.headerDeps.includes(hash)) {
+    tx.headerDeps.push(hash);
+  }
+}