@ickb/sdk 1000.0.82 → 9001.0.0

package/dist/logic.js

@@ -0,0 +1,173 @@
+import { ccc } from "@ckb-ccc/core";
+import { assertDaoOutputLimit, DAO_DEPOSIT_DATA, DaoOutputLimitError, depositMaturity, isDaoDeposit, pushHeaderDep, } from "./dao.js";
+import { decodeReceiptData, encodeReceiptData, IckbUdt, ickbValue, receiptDataBytes, } from "./udt.js";
+import { findCells, headersByNumber, } 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 Completion (`IckbSdk.completeTransaction`) adds the dep group that also
+     * resolves the xUDT script.
+     */
+    deposit(txLike, depositQuantity, depositCapacity, lock) {
+        // A zero quantity would mint a receipt for no deposits, which iCKB Logic refuses on chain.
+        if (!Number.isSafeInteger(depositQuantity) || depositQuantity <= 0) {
+            throw new TypeError("iCKB deposit quantity must be a positive safe integer");
+        }
+        const tx = ccc.Transaction.from(txLike);
+        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: DAO_DEPOSIT_DATA,
+        });
+        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`);
+            }
+        }
+        tx.addCellDeps(this.cellDeps);
+        for (const receipt of receipts) {
+            pushHeaderDep(tx, receipt.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 headersByNumber(client, receipts.map(({ blockNumber }) => blockNumber));
+        return receipts.map(({ cell, blockNumber }) => 
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- every receipt's block was read above.
+        receiptCell(cell, headers.get(blockNumber)));
+    }
+    /**
+     * Every live iCKB deposit, valued at its deposit header, with its claim epoch at the tip;
+     * each deposit block'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: DAO_DEPOSIT_DATA,
+                outputDataSearchMode: "exact",
+            },
+            scriptSearchMode: "exact",
+            withData: true,
+        })).filter(({ cell }) => this.isDeposit(cell));
+        const headers = await headersByNumber(client, cells.map(({ blockNumber }) => blockNumber));
+        return cells.map(({ cell, blockNumber }) => 
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- every deposit's block was read above.
+        ickbDepositCell(cell, headers.get(blockNumber), tip));
+    }
+}
+/** Values a DAO deposit cell at its deposit header and samples its claim epoch at the tip. */
+function ickbDepositCell(cell, header, tip) {
+    const interests = ccc.calcDaoProfit(cell.capacityFree, header, tip);
+    return {
+        cell,
+        header,
+        claimEpoch: ccc.calcDaoClaimEpoch(header, tip),
+        ckbValue: cell.cellOutput.capacity + interests,
+        udtValue: ickbValue(cell.capacityFree, 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) * 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,168 @@
+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;
+    /**
+     * Whether `descendant` can be this origin order's live continuation.
+     *
+     * @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}.
+     */
+    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 {
+    /** Raw live master cell that anchors an order group. */
+    readonly cell: ccc.Cell;
+    /**
+     * Creates an instance of MasterCell.
+     * @param cell - The ccc.Cell instance to be wrapped by the MasterCell.
+     */
+    constructor(cell: ccc.Cell);
+    /** Whether this master anchors `order`: its type is the order script and the order names it. */
+    anchors(order: OrderCell): boolean;
+}
+/**
+ * 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 and its master: how long the order has been on the book. */
+    readonly blockNumber: ccc.Num;
+    /**
+     * 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 and its master.
+     */
+    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;
+    /** Whether the master anchors both orders and the order continues its origin. */
+    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;
+}
+//# 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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"}

package/dist/order/cells.js

@@ -0,0 +1,309 @@
+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 class OrderCell {
+    /** Raw live cell that carries the order lock and UDT type. */
+    cell;
+    /** Decoded order payload from `cell.outputData`. */
+    data;
+    /** CKB capacity available for matching after occupied capacity is reserved. */
+    ckbUnoccupied;
+    /** Absolute total order value in the order's comparison units. */
+    absTotal;
+    /** Absolute matched progress in the order's comparison units. */
+    absProgress;
+    constructor({ cell, data, ckbUnoccupied, absTotal, absProgress, }) {
+        this.cell = cell;
+        this.data = data;
+        this.ckbUnoccupied = ckbUnoccupied;
+        this.absTotal = absTotal;
+        this.absProgress = absProgress;
+    }
+    /**
+     * Gets the order CKB amount.
+     *
+     * @returns The CKB amount as a `ccc.FixedPoint`.
+     */
+    get ckbValue() {
+        return this.cell.cellOutput.capacity;
+    }
+    /**
+     * Gets the order UDT amount.
+     *
+     * @returns The UDT amount as a `ccc.FixedPoint`.
+     */
+    get udtValue() {
+        return this.data.udtValue;
+    }
+    /**
+     * 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) {
+        try {
+            return OrderCell.mustFrom(cell);
+        }
+        catch {
+            return 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) {
+        let data;
+        try {
+            data = OrderData.decode(cell.outputData);
+            data.validate();
+        }
+        catch (error) {
+            throw new Error(`Invalid order payload at ${cell.outPoint.toHex()}`, {
+                cause: error,
+            });
+        }
+        const udtValue = data.udtValue;
+        const ckbUnoccupied = cell.capacityFree;
+        const { ckbToUdt, udtToCkb } = data.info;
+        const isCkb2Udt = data.info.isCkb2Udt();
+        const isUdt2Ckb = data.info.isUdt2Ckb();
+        const isDualRatio = isCkb2Udt && isUdt2Ckb;
+        // Compute total values in base units
+        const ckb2UdtValue = isCkb2Udt
+            ? ckbUnoccupied * ckbToUdt.ckbScale + udtValue * ckbToUdt.udtScale
+            : 0n;
+        const udt2CkbValue = isUdt2Ckb
+            ? ckbUnoccupied * udtToCkb.ckbScale + udtValue * udtToCkb.udtScale
+            : 0n;
+        const absTotal = absoluteOrderTotal(ckb2UdtValue, udt2CkbValue, data.info);
+        // What the order already holds of its output side; a dual-ratio order is complete.
+        let absProgress = ckbUnoccupied * udtToCkb.ckbScale;
+        if (isDualRatio) {
+            absProgress = absTotal;
+        }
+        else if (isCkb2Udt) {
+            absProgress = udtValue * ckbToUdt.udtScale;
+        }
+        return new OrderCell({ cell, data, ckbUnoccupied, absTotal, absProgress });
+    }
+    /**
+     * 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() {
+        return this.data.info.isCkb2Udt() && this.ckbUnoccupied > 0n;
+    }
+    /**
+     * 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() {
+        return this.data.info.isUdt2Ckb() && this.data.udtValue > 0n;
+    }
+    /** Returns true when either side is enabled and has nonzero inventory. */
+    isMatchable() {
+        return this.isCkb2UdtMatchable() || this.isUdt2CkbMatchable();
+    }
+    /**
+     * Checks if the order is fulfilled.
+     *
+     * @returns True if the order is fulfilled (not matchable), otherwise false.
+     */
+    isFulfilled() {
+        return !this.isMatchable();
+    }
+    /**
+     * Retrieves the master out point of the order.
+     * @returns The master out point associated with the order.
+     */
+    getMaster() {
+        return this.data.getMaster(this.cell.outPoint);
+    }
+    /**
+     * Whether `descendant` can be this origin order's live continuation.
+     *
+     * @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}.
+     */
+    isValid(descendant) {
+        const udt = this.cell.cellOutput.type;
+        return (this.data.isMint() &&
+            this.cell.cellOutput.lock.eq(descendant.cell.cellOutput.lock) &&
+            udt !== undefined &&
+            descendant.cell.cellOutput.type?.eq(udt) === true &&
+            descendant.getMaster().eq(this.getMaster()) &&
+            this.data.info.eq(descendant.data.info) &&
+            this.absTotal <= descendant.absTotal &&
+            this.absProgress <= descendant.absProgress);
+    }
+    /**
+     * 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) {
+        let resolution;
+        for (const descendant of descendants) {
+            if (!this.isValid(descendant)) {
+                continue;
+            }
+            resolution = betterOrderResolution(resolution, descendant);
+        }
+        if (resolution?.isAmbiguous === true) {
+            return undefined;
+        }
+        return resolution?.order;
+    }
+}
+function absoluteOrderTotal(ckb2UdtValue, udt2CkbValue, info) {
+    if (ckb2UdtValue === 0n) {
+        return udt2CkbValue;
+    }
+    if (udt2CkbValue === 0n) {
+        return ckb2UdtValue;
+    }
+    const { ckbToUdt, udtToCkb } = info;
+    return ((ckb2UdtValue * udtToCkb.ckbScale * udtToCkb.udtScale +
+        udt2CkbValue * ckbToUdt.ckbScale * ckbToUdt.udtScale) >>
+        1n);
+}
+function betterOrderResolution(current, candidate) {
+    if (current === undefined || compareOrderScore(current.order, candidate) < 0) {
+        return { isAmbiguous: false, order: candidate };
+    }
+    if (compareOrderScore(current.order, candidate) > 0) {
+        return current;
+    }
+    if (current.order.cell.outPoint.eq(candidate.cell.outPoint)) {
+        return current;
+    }
+    if (candidate.data.isMint() && !current.order.data.isMint()) {
+        return { isAmbiguous: false, order: candidate };
+    }
+    if (!candidate.data.isMint() && current.order.data.isMint()) {
+        return current;
+    }
+    return { ...current, isAmbiguous: true };
+}
+function compareOrderScore(left, right) {
+    if (left.absProgress !== right.absProgress) {
+        return left.absProgress < right.absProgress ? -1 : 1;
+    }
+    if (left.absTotal !== right.absTotal) {
+        return left.absTotal < right.absTotal ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Represents a master cell
+ */
+export class MasterCell {
+    /** Raw live master cell that anchors an order group. */
+    cell;
+    /**
+     * Creates an instance of MasterCell.
+     * @param cell - The ccc.Cell instance to be wrapped by the MasterCell.
+     */
+    constructor(cell) {
+        this.cell = cell;
+    }
+    /** Whether this master anchors `order`: its type is the order script and the order names it. */
+    anchors(order) {
+        return (this.cell.cellOutput.type?.eq(order.cell.cellOutput.lock) === true &&
+            order.getMaster().eq(this.cell.outPoint));
+    }
+}
+/**
+ * Represents a group of orders associated with a master cell.
+ */
+export class OrderGroup {
+    /** Master cell that authorizes and anchors the current order. */
+    master;
+    /** Current resolved order cell. */
+    order;
+    /** Origin order used to validate descendant progress and identity. */
+    origin;
+    /** The block that committed the origin and its master: how long the order has been on the book. */
+    blockNumber;
+    /**
+     * 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 and its master.
+     */
+    constructor(master, order, origin, blockNumber) {
+        this.master = master;
+        this.order = order;
+        this.origin = origin;
+        this.blockNumber = blockNumber;
+    }
+    /**
+     * 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() {
+        return this.order.cell.cellOutput.capacity + this.master.cell.cellOutput.capacity;
+    }
+    /**
+     * Gets the UDT value of the group.
+     *
+     * @returns The UDT amount as a `ccc.FixedPoint`, derived from the order cell.
+     */
+    get udtValue() {
+        return this.order.data.udtValue;
+    }
+    /**
+     * 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, order, origin, blockNumber) {
+        const og = new OrderGroup(master, order, origin, blockNumber);
+        if (og.isValid()) {
+            return og;
+        }
+        return undefined;
+    }
+    /** Whether the master anchors both orders and the order continues its origin. */
+    isValid() {
+        return (this.master.anchors(this.origin) &&
+            this.master.anchors(this.order) &&
+            this.origin.isValid(this.order));
+    }
+    /**
+     * 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) {
+        const lock = this.master.cell.cellOutput.lock;
+        return locks.some((l) => lock.eq(l));
+    }
+}
+//# sourceMappingURL=cells.js.map