@ickb/sdk 1000.0.82 → 9001.0.0

package/dist/sdk.d.ts

@@ -1,51 +1,123 @@
 import { ccc } from "@ckb-ccc/core";
-import { CapacityManager, SmartTransaction, type ValueComponents } from "@ickb/utils";
-import { type LogicManager, type OwnedOwnerManager } from "@ickb/core";
-import { Info, OrderManager, Ratio, type OrderCell, type OrderGroup } from "@ickb/order";
-import { getConfig } from "./constants.js";
+import type { AccountState, CompleteIckbTransactionOptions, ConversionTransactionContext, ConversionTransactionOptions, ConversionTransactionResult, SdkManagers, SystemState } from "./conversion/types.js";
+import { type LockUpPolicy } from "./dao.js";
+import type { IckbDepositCell } from "./logic.js";
+import type { OrderGroup } from "./order/cells.js";
+import type { SupportedChain } from "./utils/chain.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 declare const SWEEP_INPUT_LIMIT = 1000;
+/** 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 declare class IckbSdk {
+    private readonly ickbUdt;
     private readonly ownedOwner;
     private readonly ickbLogic;
     private readonly order;
-    private readonly capacity;
-    private readonly bots;
-    constructor(ownedOwner: OwnedOwnerManager, ickbLogic: LogicManager, order: OrderManager, capacity: CapacityManager, bots: ccc.Script[]);
-    static from(...args: Parameters<typeof getConfig>): IckbSdk;
-    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;
-    };
-    static maturity(o: OrderCell | {
-        info: Info;
-        amounts: ValueComponents;
-    }, system: SystemState): bigint | undefined;
-    request(tx: SmartTransaction, user: ccc.Signer | ccc.Script, info: Info, amounts: ValueComponents): Promise<void>;
-    collect(tx: SmartTransaction, groups: OrderGroup[], options?: {
-        isFulfilledOnly?: boolean;
-    }): void;
-    getL1State(client: ccc.Client, locks: ccc.Script[]): Promise<{
+    constructor({ ickbUdt, ownedOwner, ickbLogic, order }: SdkManagers);
+    /** Creates the SDK for one chain's deployment. */
+    static fromChain(chain: SupportedChain): IckbSdk;
+    /**
+     * 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.
+     */
+    getL1AccountState(plainClient: ccc.Client, locks: ccc.Script[], lockUp: LockUpPolicy, maxFeeRate?: ccc.NumLike): Promise<{
         system: SystemState;
-        user: {
-            orders: OrderGroup[];
-        };
+        userOrders: OrderGroup[];
+        account: AccountState;
     }>;
-    private getCkb;
+    /** Every Stack cell one lock owns, classified from a single exact-lock scan. */
+    private readLockCells;
+    /**
+     * 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.
+     */
+    buildConversionTransaction(options: ConversionTransactionOptions): Promise<ConversionTransactionResult>;
+    private buildCollectOnlyConversion;
+    private buildCkbToIckbConversion;
+    private buildIckbToCkbConversion;
+    private completeConversion;
+    /**
+     * 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: ccc.TransactionLike, steps: CollectSteps, withdrawalRequest?: {
+        deposits: IckbDepositCell[];
+        lock: ccc.Script;
+    }): ccc.Transaction;
+    /**
+     * 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.
+     */
+    completeTransaction(txLike: ccc.TransactionLike, options: CompleteIckbTransactionOptions): Promise<ccc.Transaction>;
+    /** iCKB: what the outputs need first, then the sweep while the limit allows, then change. */
+    private completeIckb;
 }
-export interface SystemState {
-    feeRate: ccc.Num;
-    tip: ccc.ClientBlockHeader;
-    exchangeRatio: Ratio;
-    orderPool: OrderCell[];
-    ckbAvailable: ccc.FixedPoint;
-    ckbMaturing: CkbCumulative[];
-}
-export interface CkbCumulative {
-    ckbCumulative: ccc.FixedPoint;
-    maturity: ccc.Num;
+/** Stable machine-readable SDK failures. */
+export type IckbErrorCode = "insufficient_capacity" | "insufficient_ickb";
+/** Typed SDK failure with a stable machine-readable code. */
+export declare class IckbError extends Error {
+    /** Stable failure code for callers and observability. */
+    readonly code: IckbErrorCode;
+    /** Creates a typed SDK failure while preserving its cause. */
+    constructor(message: string, options: ErrorOptions & {
+        code: IckbErrorCode;
+    });
 }
+/**
+ * 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 declare function completeFirstFundable<T>(candidates: Iterable<T>, build: (candidate: T) => ccc.Transaction, complete: (tx: ccc.Transaction) => Promise<ccc.Transaction>): Promise<{
+    candidate: T;
+    tx: ccc.Transaction;
+}>;
+/**
+ * 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 declare function isFundabilityFailure(error: unknown): error is Error;
+export {};
 //# sourceMappingURL=sdk.d.ts.map

package/dist/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"../src/","sources":["sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACpC,OAAO,EAEL,eAAe,EACf,gBAAgB,EAEhB,KAAK,eAAe,EAIrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAM3C,qBAAa,OAAO;IAWhB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAJJ,UAAU,EAAE,iBAAiB,EAC7B,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE;IASrC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,GAAG,OAAO;IA+B3D,MAAM,CAAC,QAAQ,CACb,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;QACd,OAAO,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;KACnB,GACA;QACD,eAAe,EAAE,GAAG,CAAC,UAAU,CAAC;QAChC,MAAM,EAAE,GAAG,CAAC,UAAU,CAAC;QACvB,IAAI,EAAE,IAAI,CAAC;QACX,QAAQ,EAAE,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC;KAC/B;IAiCD,MAAM,CAAC,QAAQ,CACb,CAAC,EACG,SAAS,GACT;QACE,IAAI,EAAE,IAAI,CAAC;QACX,OAAO,EAAE,eAAe,CAAC;KAC1B,EACL,MAAM,EAAE,WAAW,GAClB,MAAM,GAAG,SAAS;IAwFf,OAAO,CACX,EAAE,EAAE,gBAAgB,EACpB,IAAI,EAAE,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,EAC7B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC;IAwBhB,OAAO,CACL,EAAE,EAAE,gBAAgB,EACpB,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,CAAC,EAAE;QACR,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,GACA,IAAI;IAmBD,UAAU,CACd,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,GAClB,OAAO,CAAC;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,UAAU,EAAE,CAAA;SAAE,CAAA;KAAE,CAAC;YAoErD,MAAM;CA8HrB;AAKD,MAAM,WAAW,WAAW;IAE1B,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC;IAGjB,GAAG,EAAE,GAAG,CAAC,iBAAiB,CAAC;IAG3B,aAAa,EAAE,KAAK,CAAC;IAGrB,SAAS,EAAE,SAAS,EAAE,CAAC;IAGvB,YAAY,EAAE,GAAG,CAAC,UAAU,CAAC;IAG7B,WAAW,EAAE,aAAa,EAAE,CAAC;CAC9B;AAKD,MAAM,WAAW,aAAa;IAE5B,aAAa,EAAE,GAAG,CAAC,UAAU,CAAC;IAE9B,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC;CACnB"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAOpC,OAAO,KAAK,EACV,YAAY,EACZ,8BAA8B,EAC9B,4BAA4B,EAE5B,4BAA4B,EAC5B,2BAA2B,EAC3B,WAAW,EACX,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAML,KAAK,YAAY,EAGlB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAKtC,sFAAsF;AACtF,KAAK,YAAY,GAAG,IAAI,CACtB,4BAA4B,EAC5B,iBAAiB,GAAG,UAAU,GAAG,kBAAkB,CACpD,CAAC;AAEF;;;GAGG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,WAAW,EAKjE;IAED,kDAAkD;IAClD,OAAc,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAEtD;IAID;;;;;;;;;OASG;IACU,iBAAiB,CAC5B,WAAW,EAAE,GAAG,CAAC,MAAM,EACvB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,EACnB,MAAM,EAAE,YAAY,EACpB,UAAU,CAAC,EAAE,GAAG,CAAC,OAAO,GACvB,OAAO,CAAC;QACT,MAAM,EAAE,WAAW,CAAC;QACpB,UAAU,EAAE,UAAU,EAAE,CAAC;QACzB,OAAO,EAAE,YAAY,CAAC;KACvB,CAAC,CAgDD;IAED,gFAAgF;YAClE,aAAa;IA0B3B;;;;;;;;;;OAUG;IACU,0BAA0B,CACrC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAsBtC;YAEa,0BAA0B;YAuB1B,wBAAwB;YA+CxB,wBAAwB;YAmDxB,kBAAkB;IAmBhC;;;;;;;;OAQG;IACI,oBAAoB,CACzB,MAAM,EAAE,GAAG,CAAC,eAAe,EAC3B,KAAK,EAAE,YAAY,EACnB,iBAAiB,CAAC,EAAE;QAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;QAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAA;KAAE,GACpE,GAAG,CAAC,WAAW,CAmBjB;IAED;;;;;;;;;OASG;IACU,mBAAmB,CAC9B,MAAM,EAAE,GAAG,CAAC,eAAe,EAC3B,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAyC1B;IAED,6FAA6F;YAC/E,YAAY;CAuB3B;AAyFD,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GAAG,uBAAuB,GAAG,mBAAmB,CAAC;AAE1E,6DAA6D;AAC7D,qBAAa,SAAU,SAAQ,KAAK;IAClC,yDAAyD;IACzD,SAAgB,IAAI,EAAE,aAAa,CAAC;IAEpC,8DAA8D;IAC9D,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG;QAAE,IAAI,EAAE,aAAa,CAAA;KAAE,EAI3E;CACF;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,EACvB,KAAK,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,GAAG,CAAC,WAAW,EACxC,QAAQ,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,GAC1D,OAAO,CAAC;IAAE,SAAS,EAAE,CAAC,CAAC;IAAC,EAAE,EAAE,GAAG,CAAC,WAAW,CAAA;CAAE,CAAC,CAahD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAOnE"}