@ickb/sdk 1000.0.81 → 9000.0.1

package/dist/logic.js

@@ -0,0 +1,184 @@
+import { ccc } from "@ckb-ccc/core";
+import { assertDaoOutputLimit, DaoOutputLimitError, depositData, depositMaturity, isDaoDeposit, pushHeaderDep, } from "./dao.js";
+import { decodeReceiptData, encodeReceiptData, IckbUdt, ickbValue, receiptDataBytes, } from "./udt.js";
+import { transactionHeaders } from "./utils/transaction_header.js";
+import { findCells, } from "./utils/utils.js";
+const maxDepositQuantity = 63;
+// Receipts must carry enough capacity for phase 2 when the wallet has no other
+// CKB: one iCKB xUDT cell, one plain capacity cell, and the fee reserve.
+const phase2TxFeeReserve = ccc.One;
+/**
+ * Manages logic related to deposits and receipts in the blockchain.
+ */
+export class LogicManager {
+    /** The iCKB Logic script used as receipt type and DAO deposit lock. */
+    script;
+    /** Cell dependencies required to execute the iCKB Logic script. */
+    cellDeps;
+    /** The Nervos DAO script the deposits carry, with its cell deps. */
+    dao;
+    /** Creates the manager for one iCKB Logic deployment over one DAO deployment. */
+    constructor(script, cellDeps, dao) {
+        this.script = script;
+        this.cellDeps = cellDeps;
+        this.dao = dao;
+    }
+    /** Whether the cell is an iCKB receipt: typed by the logic script with a decodable prefix. */
+    isReceipt(cell) {
+        return (cell.cellOutput.type?.eq(this.script) === true &&
+            ccc.bytesFrom(cell.outputData).length >= receiptDataBytes);
+    }
+    /** Whether the cell is a DAO deposit locked by the logic script. */
+    isDeposit(cell) {
+        return isDaoDeposit(cell, this.dao.script) && cell.cellOutput.lock.eq(this.script);
+    }
+    /**
+     * Adds `depositQuantity` DAO deposits of `depositCapacity` locked by the logic script,
+     * then the receipt that mints their iCKB in phase 2, locked by `lock`.
+     *
+     * @remarks Caller must ensure UDT cellDeps are added to the transaction
+     * (e.g., via ickbUdt.addCellDeps(tx)).
+     */
+    deposit(txLike, depositQuantity, depositCapacity, lock) {
+        const tx = ccc.Transaction.from(txLike);
+        if (depositQuantity <= 0) {
+            return tx;
+        }
+        if (!Number.isSafeInteger(depositQuantity)) {
+            throw new TypeError("iCKB deposit quantity must be a safe integer");
+        }
+        if (depositQuantity > maxDepositQuantity) {
+            // The completion walk steps a plan down on this error.
+            throw new DaoOutputLimitError(tx.outputs.length + depositQuantity + 1);
+        }
+        const depositCell = ccc.Cell.from({
+            previousOutput: { txHash: `0x${"00".repeat(32)}`, index: 0 },
+            cellOutput: { capacity: depositCapacity, lock: this.script, type: this.dao.script },
+            outputData: depositData(),
+        });
+        const depositAmount = depositCell.capacityFree;
+        if (depositAmount < ccc.fixedPointFrom(1000)) {
+            throw new Error("iCKB deposit minimum is 1000 CKB free capacity (1082 CKB total capacity)");
+        }
+        if (depositAmount > ccc.fixedPointFrom(1000000)) {
+            throw new Error("iCKB deposit maximum is 1000000 CKB free capacity (1000082 CKB total capacity)");
+        }
+        tx.addCellDeps(this.cellDeps);
+        tx.addCellDeps(this.dao.cellDeps);
+        for (let i = 0; i < depositQuantity; i += 1) {
+            tx.addOutput(depositCell.cellOutput, depositCell.outputData);
+        }
+        // Receipts track the deposit's free capacity, not the full DAO cell capacity.
+        tx.addOutput({ capacity: receiptPhase2Capacity(lock), lock, type: this.script }, encodeReceiptData({ depositQuantity: BigInt(depositQuantity), depositAmount }));
+        assertDaoOutputLimit(tx, this.dao.script);
+        return tx;
+    }
+    /**
+     * Adds receipt inputs and their deposit header deps for iCKB deposit completion.
+     *
+     * @remarks This prepares the phase-2 inputs; the iCKB they mint is completed by
+     * `IckbSdk.completeTransaction`.
+     */
+    completeDeposit(txLike, receipts) {
+        const tx = ccc.Transaction.from(txLike);
+        if (receipts.length === 0) {
+            return tx;
+        }
+        for (const receipt of receipts) {
+            const outPoint = receipt.cell.outPoint.toHex();
+            if (!this.isReceipt(receipt.cell)) {
+                throw new Error(`Receipt ${outPoint} is not an iCKB receipt for this logic script`);
+            }
+            if (receipt.header.txHash !== receipt.cell.outPoint.txHash) {
+                throw new Error(`Receipt ${outPoint} header txHash ${String(receipt.header.txHash)} does not match cell txHash ${receipt.cell.outPoint.txHash}`);
+            }
+        }
+        tx.addCellDeps(this.cellDeps);
+        for (const receipt of receipts) {
+            pushHeaderDep(tx, receipt.header.header.hash);
+            tx.addInput(receipt.cell);
+        }
+        return tx;
+    }
+    /**
+     * The receipts among `cells`, valued at their deposit headers, each header read once.
+     */
+    async receiptsFrom(client, cells) {
+        const receipts = cells.filter((cell) => this.isReceipt(cell));
+        const headers = await transactionHeaders(client, receipts.map((cell) => cell.outPoint.txHash));
+        return receipts.map((cell) => {
+            const { txHash } = cell.outPoint;
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- every receipt's hash was read above.
+            return receiptCell(cell, { header: headers.get(txHash), txHash });
+        });
+    }
+    /**
+     * Every live iCKB deposit, valued at its deposit header, with its claim epoch at the tip;
+     * each deposit transaction's header is read once.
+     */
+    async findDeposits(client, tip) {
+        const cells = (await findCells(client, {
+            script: this.script,
+            scriptType: "lock",
+            filter: {
+                script: this.dao.script,
+                outputData: depositData(),
+                outputDataSearchMode: "exact",
+            },
+            scriptSearchMode: "exact",
+            withData: true,
+        })).filter((cell) => this.isDeposit(cell));
+        const headers = await transactionHeaders(client, cells.map((cell) => cell.outPoint.txHash));
+        return cells.map((cell) => {
+            const { txHash } = cell.outPoint;
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- every deposit's hash was read above.
+            return ickbDepositCell(cell, { header: headers.get(txHash), txHash }, tip);
+        });
+    }
+}
+/** Values a DAO deposit cell at its deposit header and samples its claim epoch at the tip. */
+export function ickbDepositCell(cell, depositHeader, tip) {
+    const interests = ccc.calcDaoProfit(cell.capacityFree, depositHeader.header, tip);
+    return {
+        cell,
+        headers: [depositHeader, { header: tip }],
+        interests,
+        claimEpoch: ccc.calcDaoClaimEpoch(depositHeader.header, tip),
+        ckbValue: cell.cellOutput.capacity + interests,
+        udtValue: ickbValue(cell.capacityFree, depositHeader.header),
+    };
+}
+/** The deposits a withdrawal request made now may claim at their sampled dates under the policy. */
+export function readyDeposits(deposits, tip, policy) {
+    return deposits.filter((deposit) => depositMaturity(deposit.claimEpoch, tip, policy).isReady);
+}
+/** Decodes a receipt cell and values it at its deposit header. */
+export function receiptCell(cell, header) {
+    let receipt;
+    try {
+        receipt = decodeReceiptData(cell.outputData);
+    }
+    catch (error) {
+        throw new Error(`Invalid iCKB receipt payload at ${cell.outPoint.toHex()}: ${cell.outputData}`, { cause: error });
+    }
+    return {
+        cell,
+        header,
+        ckbValue: cell.cellOutput.capacity,
+        udtValue: ickbValue(receipt.depositAmount, header.header) * receipt.depositQuantity,
+    };
+}
+/**
+ * Returns the CKB needed for the two phase-2 outputs created by one receipt.
+ *
+ * @remarks The value is sized with the actual user lock because lock args affect
+ * occupied capacity. It includes one plain output, one xUDT output, and the
+ * phase-2 fee reserve.
+ */
+export function receiptPhase2Capacity(lock) {
+    // Capacity is measured with the actual user lock. Lock args are wallet-specific
+    // and can make both phase-2 outputs larger than protocol-only examples.
+    const plainCellCapacity = BigInt(8 + lock.occupiedSize) * ccc.One;
+    return plainCellCapacity + IckbUdt.minimumXudtCellCapacity(lock) + phase2TxFeeReserve;
+}
+//# sourceMappingURL=logic.js.map

package/dist/logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logic.js","sourceRoot":"","sources":["../src/logic.ts"],"names":[],"mappings":"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"}

package/dist/order/cells.d.ts

@@ -0,0 +1,207 @@
+import type { ccc } from "@ckb-ccc/core";
+import type { ValueComponents } from "../utils/utils.js";
+import { OrderData } from "./order_data.js";
+/**
+ * Represents a parsed order cell on the blockchain.
+ *
+ * Implements `ValueComponents` to expose the cell's raw data and its
+ * value breakdown (CKB and UDT).
+ */
+export declare class OrderCell implements ValueComponents {
+    /** Raw live cell that carries the order lock and UDT type. */
+    readonly cell: ccc.Cell;
+    /** Decoded order payload from `cell.outputData`. */
+    readonly data: OrderData;
+    /** CKB capacity available for matching after occupied capacity is reserved. */
+    readonly ckbUnoccupied: ccc.FixedPoint;
+    /** Absolute total order value in the order's comparison units. */
+    readonly absTotal: ccc.Num;
+    /** Absolute matched progress in the order's comparison units. */
+    readonly absProgress: ccc.Num;
+    constructor({ cell, data, ckbUnoccupied, absTotal, absProgress, }: {
+        cell: ccc.Cell;
+        data: OrderData;
+        ckbUnoccupied: ccc.FixedPoint;
+        absTotal: ccc.Num;
+        absProgress: ccc.Num;
+    });
+    /**
+     * Gets the order CKB amount.
+     *
+     * @returns The CKB amount as a `ccc.FixedPoint`.
+     */
+    get ckbValue(): ccc.FixedPoint;
+    /**
+     * Gets the order UDT amount.
+     *
+     * @returns The UDT amount as a `ccc.FixedPoint`.
+     */
+    get udtValue(): ccc.FixedPoint;
+    /**
+     * Attempts to parse an OrderCell from a raw cell.
+     *
+     * Returns `undefined` if parsing or validation fails.
+     *
+     * @param cell - The raw chain cell to convert.
+     * @returns An `OrderCell` instance or `undefined`.
+     */
+    static tryFrom(cell: ccc.Cell): OrderCell | undefined;
+    /**
+     * Parses and validates a raw cell as OrderCell.
+     *
+     * Throws if the cell is invalid or data validation fails.
+     *
+     * @param cell - The raw chain cell to convert.
+     * @returns A new `OrderCell` instance.
+     * @throws When decoding or validation fails.
+     */
+    static mustFrom(cell: ccc.Cell): OrderCell;
+    /**
+     * Checks whether the CKB-to-UDT side is enabled and has nonzero inventory.
+     *
+     * @remarks Executable-match checks for fee, minimum output, and ratio bounds happen during matching.
+     */
+    isCkb2UdtMatchable(): boolean;
+    /**
+     * Checks whether the UDT-to-CKB side is enabled and has nonzero inventory.
+     *
+     * @remarks Executable-match checks for fee, minimum output, and ratio bounds happen during matching.
+     */
+    isUdt2CkbMatchable(): boolean;
+    /** Returns true when either side is enabled and has nonzero inventory. */
+    isMatchable(): boolean;
+    /**
+     * Checks if the order is fulfilled.
+     *
+     * @returns True if the order is fulfilled (not matchable), otherwise false.
+     */
+    isFulfilled(): boolean;
+    /**
+     * Retrieves the master out point of the order.
+     * @returns The master out point associated with the order.
+     */
+    getMaster(): ccc.OutPoint;
+    /**
+     * Validates a descendant order against this origin order.
+     *
+     * @remarks
+     * This confusion-attack guard requires the same order script, UDT type,
+     * master, and info, while forbidding lower total value or lower progress.
+     * See {@link https://github.com/ickb/whitepaper/issues/19}.
+     */
+    validate(descendant: OrderCell): void;
+    /**
+     * Checks if the descendant order is valid against this order.
+     * @param descendant - The descendant order to validate.
+     * @returns True if the descendant is valid, otherwise false.
+     */
+    isValid(descendant: OrderCell): boolean;
+    /**
+     * Resolves the best valid descendant order.
+     *
+     * @remarks
+     * The genuine mint origin is the immutable validation baseline. Resolution
+     * prefers greater progress and then greater total value; candidate identity is
+     * irrelevant. Equal-score non-mint candidates are ambiguous, while the mint
+     * origin wins an equal-score tie when it is still live.
+     */
+    resolve(descendants: OrderCell[]): OrderCell | undefined;
+}
+/**
+ * Represents a master cell
+ */
+export declare class MasterCell implements ValueComponents {
+    /** Raw live master cell that anchors an order group. */
+    readonly cell: ccc.Cell;
+    /**
+     * Gets the UDT value of the cell.
+     *
+     * For a Master Cell, the UDT amount is always zero.
+     *
+     * @returns The UDT amount as a `ccc.FixedPoint` (0n).
+     */
+    readonly udtValue = 0n;
+    /**
+     * Creates an instance of MasterCell.
+     * @param cell - The ccc.Cell instance to be wrapped by the MasterCell.
+     */
+    constructor(cell: ccc.Cell);
+    /**
+     * Gets the CKB value of the cell.
+     *
+     * @returns The total CKB amount as a `ccc.FixedPoint`.
+     */
+    get ckbValue(): ccc.FixedPoint;
+    /**
+     * Validates the MasterCell against an OrderCell.
+     * @param order - The OrderCell to validate against.
+     * @throws Error if the order script is different or if the master is different.
+     */
+    validate(order: OrderCell): void;
+}
+/**
+ * Represents a group of orders associated with a master cell.
+ */
+export declare class OrderGroup implements ValueComponents {
+    /** Master cell that authorizes and anchors the current order. */
+    readonly master: MasterCell;
+    /** Current resolved order cell. */
+    readonly order: OrderCell;
+    /** Origin order used to validate descendant progress and identity. */
+    readonly origin: OrderCell;
+    /** The block that committed the origin, when known: how long the order has been on the book. */
+    readonly blockNumber: ccc.Num | undefined;
+    /**
+     * Creates an instance of OrderGroup.
+     * @param master - The master cell associated with the order group.
+     * @param order - The order within the group.
+     * @param origin - The original order associated with the group.
+     * @param blockNumber - The block that committed the origin, if committed.
+     */
+    constructor(master: MasterCell, order: OrderCell, origin: OrderCell, blockNumber?: ccc.Num);
+    /**
+     * Gets the CKB value of the group.
+     *
+     * @returns The total CKB amount as a `ccc.FixedPoint`, which is the sum of the CKB values of the order cell and the master cell.
+     */
+    get ckbValue(): ccc.FixedPoint;
+    /**
+     * Gets the UDT value of the group.
+     *
+     * @returns The UDT amount as a `ccc.FixedPoint`, derived from the order cell.
+     */
+    get udtValue(): ccc.FixedPoint;
+    /**
+     * Tries to create an OrderGroup from the provided parameters.
+     * @param master - The master cell.
+     * @param order - The order within the group.
+     * @param origin - The original order.
+     * @returns An OrderGroup instance or undefined if creation fails.
+     */
+    static tryFrom(master: MasterCell, order: OrderCell, origin: OrderCell, blockNumber?: ccc.Num): OrderGroup | undefined;
+    /**
+     * Validates the order group against its master and origin orders.
+     * @throws Will throw an error if validation fails.
+     */
+    validate(): void;
+    /**
+     * Checks if the order group is valid.
+     * @returns True if the order group is valid, otherwise false.
+     */
+    isValid(): boolean;
+    /**
+     * Checks if the specified lock is the owner of the master cell.
+     *
+     * @param locks - The locks to check ownership against.
+     * @returns True if the lock is the owner, otherwise false.
+     */
+    isOwner(...locks: ccc.Script[]): boolean;
+}
+/**
+ * Records canonical resolver output without exposing forgeable provenance data. The
+ * group and its parsed parts are frozen, since matching and transactions build on them.
+ */
+export declare function attestResolvedOrderGroup(group: OrderGroup): OrderGroup;
+/** Returns the resolver's group at a matching or transaction boundary. */
+export declare function validatedOrderGroup(group: OrderGroup): OrderGroup;
+//# sourceMappingURL=cells.d.ts.map

package/dist/order/cells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cells.d.ts","sourceRoot":"","sources":["../../src/order/cells.ts"],"names":[],"mappings":"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"}