@ckbfs/api 1.5.1 → 2.0.0

package/dist/utils/transactions/v3.d.ts

@@ -0,0 +1,124 @@
+import { ccc, Transaction, Script, Signer } from "@ckb-ccc/core";
+import { CKBFSDataType } from "../molecule";
+import { NetworkType, ProtocolVersion } from "../constants";
+import { BaseCKBFSCellOptions } from "./shared";
+/**
+ * V3 CKBFS transaction utilities - witnesses-based storage with backlinks
+ */
+/**
+ * V3-specific Options for publishing a file to CKBFS
+ */
+export interface PublishV3Options extends Omit<BaseCKBFSCellOptions, 'version'> {
+    contentChunks: Uint8Array[];
+    feeRate?: number;
+    from?: Transaction;
+    version: typeof ProtocolVersion.V3;
+}
+/**
+ * V3-specific Options for appending content to a CKBFS file
+ */
+export interface AppendV3Options {
+    ckbfsCell: {
+        outPoint: {
+            txHash: string;
+            index: number;
+        };
+        data: CKBFSDataType;
+        type: Script;
+        lock: Script;
+        capacity: bigint;
+    };
+    contentChunks: Uint8Array[];
+    feeRate?: number;
+    network?: NetworkType;
+    version: typeof ProtocolVersion.V3;
+    from?: Transaction;
+    previousTxHash: string;
+    previousWitnessIndex: number;
+    previousChecksum: number;
+}
+/**
+ * V3-specific Options for transferring a CKBFS file
+ */
+export interface TransferV3Options {
+    ckbfsCell: {
+        outPoint: {
+            txHash: string;
+            index: number;
+        };
+        data: CKBFSDataType;
+        type: Script;
+        lock: Script;
+        capacity: bigint;
+    };
+    newLock: Script;
+    feeRate?: number;
+    network?: NetworkType;
+    version: typeof ProtocolVersion.V3;
+    from?: Transaction;
+    previousTxHash: string;
+    previousWitnessIndex: number;
+    previousChecksum: number;
+}
+/**
+ * Creates a CKBFS v3 cell
+ * @param options Options for creating the CKBFS cell
+ * @returns The created cell output
+ */
+export declare function createCKBFSV3Cell(options: BaseCKBFSCellOptions): {
+    lock: ccc.Script;
+    type: ccc.Script;
+    capacity: bigint;
+};
+/**
+ * Prepares a transaction for publishing a file to CKBFS v3 without fee and change handling
+ * @param options Options for publishing the file
+ * @returns Promise resolving to the prepared transaction and the output index of CKBFS Cell
+ */
+export declare function preparePublishV3Transaction(options: PublishV3Options): Promise<{
+    tx: Transaction;
+    outputIndex: number;
+    emptyTypeID: boolean;
+}>;
+/**
+ * Creates a transaction for publishing a file to CKBFS v3
+ * @param signer The signer to use for the transaction
+ * @param options Options for publishing the file
+ * @returns Promise resolving to the created transaction
+ */
+export declare function createPublishV3Transaction(signer: Signer, options: PublishV3Options): Promise<Transaction>;
+/**
+ * Creates a transaction for appending content to a CKBFS v3 file
+ * @param signer The signer to use for the transaction
+ * @param options Options for appending content
+ * @returns Promise resolving to the created transaction
+ */
+export declare function createAppendV3Transaction(signer: Signer, options: AppendV3Options): Promise<Transaction>;
+/**
+ * Creates a transaction for transferring ownership of a CKBFS v3 file
+ * @param signer The signer to use for the transaction
+ * @param options Options for transferring the file
+ * @returns Promise resolving to the created transaction
+ */
+export declare function createTransferV3Transaction(signer: Signer, options: TransferV3Options): Promise<Transaction>;
+/**
+ * Creates a complete transaction for publishing a file to CKBFS v3
+ * @param signer The signer to use for the transaction
+ * @param options Options for publishing the file
+ * @returns Promise resolving to the signed transaction
+ */
+export declare function publishCKBFSV3(signer: Signer, options: PublishV3Options): Promise<Transaction>;
+/**
+ * Creates a complete transaction for appending content to a CKBFS v3 file
+ * @param signer The signer to use for the transaction
+ * @param options Options for appending content
+ * @returns Promise resolving to the signed transaction
+ */
+export declare function appendCKBFSV3(signer: Signer, options: AppendV3Options): Promise<Transaction>;
+/**
+ * Creates a complete transaction for transferring ownership of a CKBFS v3 file
+ * @param signer The signer to use for the transaction
+ * @param options Options for transferring the file
+ * @returns Promise resolving to the signed transaction
+ */
+export declare function transferCKBFSV3(signer: Signer, options: TransferV3Options): Promise<Transaction>;

package/dist/utils/transactions/v3.js

@@ -0,0 +1,369 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCKBFSV3Cell = createCKBFSV3Cell;
+exports.preparePublishV3Transaction = preparePublishV3Transaction;
+exports.createPublishV3Transaction = createPublishV3Transaction;
+exports.createAppendV3Transaction = createAppendV3Transaction;
+exports.createTransferV3Transaction = createTransferV3Transaction;
+exports.publishCKBFSV3 = publishCKBFSV3;
+exports.appendCKBFSV3 = appendCKBFSV3;
+exports.transferCKBFSV3 = transferCKBFSV3;
+const core_1 = require("@ckb-ccc/core");
+const checksum_1 = require("../checksum");
+const molecule_1 = require("../molecule");
+const witness_1 = require("../witness");
+const constants_1 = require("../constants");
+const shared_1 = require("./shared");
+/**
+ * Creates a CKBFS v3 cell
+ * @param options Options for creating the CKBFS cell
+ * @returns The created cell output
+ */
+function createCKBFSV3Cell(options) {
+    const { contentType, filename, capacity, lock, network = constants_1.DEFAULT_NETWORK, useTypeID = false, } = options;
+    // Get CKBFS script config for v3
+    const config = (0, constants_1.getCKBFSScriptConfig)(network, constants_1.ProtocolVersion.V3, useTypeID);
+    // Create pre CKBFS type script
+    const preCkbfsTypeScript = new core_1.Script((0, shared_1.ensureHexPrefix)(config.codeHash), config.hashType, "0x0000000000000000000000000000000000000000000000000000000000000000");
+    // Return the cell output
+    return {
+        lock,
+        type: preCkbfsTypeScript,
+        capacity: capacity || 200n * 100000000n, // Default 200 CKB
+    };
+}
+/**
+ * Prepares a transaction for publishing a file to CKBFS v3 without fee and change handling
+ * @param options Options for publishing the file
+ * @returns Promise resolving to the prepared transaction and the output index of CKBFS Cell
+ */
+async function preparePublishV3Transaction(options) {
+    const { from, contentChunks, contentType, filename, lock, capacity, network = constants_1.DEFAULT_NETWORK, useTypeID = false, } = options;
+    // Calculate checksum for the combined content
+    const combinedContent = Buffer.concat(contentChunks);
+    const checksum = await (0, checksum_1.calculateChecksum)(combinedContent);
+    // V3 format uses single index (first witness containing content)
+    const contentStartIndex = from?.witnesses.length || 1;
+    // Create CKBFS v3 witnesses (no backlinks for publish operation)
+    const ckbfsWitnesses = (0, witness_1.createChunkedCKBFSV3Witnesses)(contentChunks, {
+        // For publish operation, all previous fields are zero
+        previousTxHash: '0x' + '00'.repeat(32),
+        previousWitnessIndex: 0,
+        previousChecksum: 0,
+        startIndex: contentStartIndex,
+    });
+    // Create CKBFS v3 cell output data
+    const outputData = molecule_1.CKBFSData.pack({
+        index: contentStartIndex,
+        checksum,
+        contentType,
+        filename,
+    }, constants_1.ProtocolVersion.V3);
+    // Get CKBFS script config
+    const config = (0, constants_1.getCKBFSScriptConfig)(network, constants_1.ProtocolVersion.V3, useTypeID);
+    // Create pre CKBFS type script
+    const preCkbfsTypeScript = new core_1.Script((0, shared_1.ensureHexPrefix)(config.codeHash), config.hashType, "0x0000000000000000000000000000000000000000000000000000000000000000");
+    // Calculate the required capacity for the output cell
+    const ckbfsCellSize = BigInt(outputData.length +
+        preCkbfsTypeScript.occupiedSize +
+        lock.occupiedSize +
+        8) * 100000000n;
+    // Create pre transaction without cell deps initially
+    let preTx;
+    if (from) {
+        // If from is not empty, inject/merge the fields
+        preTx = core_1.Transaction.from({
+            ...from,
+            outputs: from.outputs.length === 0
+                ? [
+                    createCKBFSV3Cell({
+                        contentType,
+                        filename,
+                        lock,
+                        network,
+                        useTypeID,
+                        capacity: ckbfsCellSize || capacity,
+                    }),
+                ]
+                : [
+                    ...from.outputs,
+                    createCKBFSV3Cell({
+                        contentType,
+                        filename,
+                        lock,
+                        network,
+                        useTypeID,
+                        capacity: ckbfsCellSize || capacity,
+                    }),
+                ],
+            witnesses: from.witnesses.length === 0
+                ? [
+                    [], // Empty secp witness for signing if not provided
+                    ...ckbfsWitnesses.map((w) => `0x${Buffer.from(w).toString("hex")}`),
+                ]
+                : [
+                    ...from.witnesses,
+                    ...ckbfsWitnesses.map((w) => `0x${Buffer.from(w).toString("hex")}`),
+                ],
+            outputsData: from.outputsData.length === 0
+                ? [outputData]
+                : [
+                    ...from.outputsData,
+                    outputData,
+                ],
+        });
+    }
+    else {
+        preTx = core_1.Transaction.from({
+            outputs: [
+                createCKBFSV3Cell({
+                    contentType,
+                    filename,
+                    lock,
+                    network,
+                    useTypeID,
+                    capacity: ckbfsCellSize || capacity,
+                }),
+            ],
+            witnesses: [
+                [], // Empty secp witness for signing
+                ...ckbfsWitnesses.map((w) => `0x${Buffer.from(w).toString("hex")}`),
+            ],
+            outputsData: [outputData],
+        });
+    }
+    // Add the CKBFS dep group cell dependency
+    preTx.addCellDeps({
+        outPoint: {
+            txHash: (0, shared_1.ensureHexPrefix)(config.depTxHash),
+            index: config.depIndex || 0,
+        },
+        depType: "depGroup",
+    });
+    // Create type ID args
+    const outputIndex = from ? from.outputs.length : 0;
+    const args = preTx.inputs.length > 0 ? core_1.ccc.hashTypeId(preTx.inputs[0], outputIndex) : "0x0000000000000000000000000000000000000000000000000000000000000000";
+    // Create CKBFS type script with type ID
+    const ckbfsTypeScript = new core_1.Script((0, shared_1.ensureHexPrefix)(config.codeHash), config.hashType, args);
+    // Create final transaction with same cell deps as preTx
+    const tx = core_1.Transaction.from({
+        cellDeps: preTx.cellDeps,
+        witnesses: preTx.witnesses,
+        outputsData: preTx.outputsData,
+        inputs: preTx.inputs,
+        outputs: outputIndex === 0
+            ? [
+                {
+                    lock,
+                    type: ckbfsTypeScript,
+                    capacity: preTx.outputs[outputIndex].capacity,
+                },
+            ]
+            : [
+                ...preTx.outputs.slice(0, outputIndex), // Include rest of outputs (e.g., change)
+                {
+                    lock,
+                    type: ckbfsTypeScript,
+                    capacity: preTx.outputs[outputIndex].capacity,
+                },
+            ],
+    });
+    return { tx, outputIndex, emptyTypeID: args === "0x0000000000000000000000000000000000000000000000000000000000000000" };
+}
+/**
+ * Creates a transaction for publishing a file to CKBFS v3
+ * @param signer The signer to use for the transaction
+ * @param options Options for publishing the file
+ * @returns Promise resolving to the created transaction
+ */
+async function createPublishV3Transaction(signer, options) {
+    const { feeRate, lock, } = options;
+    // Use preparePublishV3Transaction to create the base transaction
+    const { tx: preTx, outputIndex, emptyTypeID } = await preparePublishV3Transaction(options);
+    // Complete inputs by capacity
+    await preTx.completeInputsByCapacity(signer);
+    // Complete fee change to lock
+    await preTx.completeFeeChangeToLock(signer, lock, feeRate || 2000);
+    // If emptyTypeID is true, we need to create the proper type ID args
+    if (emptyTypeID) {
+        // Get CKBFS script config
+        const config = (0, constants_1.getCKBFSScriptConfig)(options.network || constants_1.DEFAULT_NETWORK, constants_1.ProtocolVersion.V3, options.useTypeID || false);
+        // Create type ID args
+        const args = core_1.ccc.hashTypeId(preTx.inputs[0], outputIndex);
+        // Create CKBFS type script with type ID
+        const ckbfsTypeScript = new core_1.Script((0, shared_1.ensureHexPrefix)(config.codeHash), config.hashType, args);
+        // Create final transaction with updated type script
+        const tx = core_1.Transaction.from({
+            cellDeps: preTx.cellDeps,
+            witnesses: preTx.witnesses,
+            outputsData: preTx.outputsData,
+            inputs: preTx.inputs,
+            outputs: preTx.outputs.map((output, index) => index === outputIndex
+                ? {
+                    ...output,
+                    type: ckbfsTypeScript,
+                }
+                : output),
+        });
+        return tx;
+    }
+    return preTx;
+}
+/**
+ * Creates a transaction for appending content to a CKBFS v3 file
+ * @param signer The signer to use for the transaction
+ * @param options Options for appending content
+ * @returns Promise resolving to the created transaction
+ */
+async function createAppendV3Transaction(signer, options) {
+    const { ckbfsCell, contentChunks, feeRate, network = constants_1.DEFAULT_NETWORK, previousTxHash, previousWitnessIndex, previousChecksum, } = options;
+    // Calculate new checksum by updating from previous checksum
+    const combinedContent = Buffer.concat(contentChunks);
+    const newChecksum = await (0, checksum_1.updateChecksum)(previousChecksum, combinedContent);
+    // Create CKBFS v3 witnesses with backlink info
+    const ckbfsWitnesses = (0, witness_1.createChunkedCKBFSV3Witnesses)(contentChunks, {
+        previousTxHash,
+        previousWitnessIndex,
+        previousChecksum,
+    });
+    // V3 format uses single index (first witness containing content)
+    const contentStartIndex = 1; // First witness is for signer, content starts at index 1
+    // Create updated CKBFS v3 cell output data
+    const outputData = molecule_1.CKBFSData.pack({
+        index: contentStartIndex,
+        checksum: newChecksum,
+        contentType: ckbfsCell.data.contentType,
+        filename: ckbfsCell.data.filename,
+    }, constants_1.ProtocolVersion.V3);
+    // Get CKBFS script config
+    const config = (0, constants_1.getCKBFSScriptConfig)(network, constants_1.ProtocolVersion.V3, false);
+    // Calculate the required capacity for the output cell
+    const ckbfsCellSize = BigInt(outputData.length + ckbfsCell.type.occupiedSize + ckbfsCell.lock.occupiedSize + 8) *
+        100000000n;
+    // Use the maximum value between calculated size and original capacity
+    const outputCapacity = ckbfsCellSize > ckbfsCell.capacity ? ckbfsCellSize : ckbfsCell.capacity;
+    // Create transaction
+    const tx = core_1.Transaction.from({
+        inputs: [
+            {
+                previousOutput: ckbfsCell.outPoint,
+                since: "0x0",
+            },
+        ],
+        outputs: [
+            {
+                lock: ckbfsCell.lock,
+                type: ckbfsCell.type,
+                capacity: outputCapacity,
+            },
+        ],
+        witnesses: [
+            [], // Empty secp witness for signing
+            ...ckbfsWitnesses.map((w) => `0x${Buffer.from(w).toString("hex")}`),
+        ],
+        outputsData: [outputData],
+    });
+    // Add the CKBFS dep group cell dependency
+    tx.addCellDeps({
+        outPoint: {
+            txHash: (0, shared_1.ensureHexPrefix)(config.depTxHash),
+            index: config.depIndex || 0,
+        },
+        depType: "depGroup",
+    });
+    // Complete inputs by capacity for fees
+    await tx.completeInputsByCapacity(signer);
+    // Complete fee change to lock
+    await tx.completeFeeChangeToLock(signer, ckbfsCell.lock, feeRate || 2000);
+    return tx;
+}
+/**
+ * Creates a transaction for transferring ownership of a CKBFS v3 file
+ * @param signer The signer to use for the transaction
+ * @param options Options for transferring the file
+ * @returns Promise resolving to the created transaction
+ */
+async function createTransferV3Transaction(signer, options) {
+    const { ckbfsCell, newLock, feeRate, network = constants_1.DEFAULT_NETWORK, previousTxHash, previousWitnessIndex, previousChecksum, } = options;
+    // Create CKBFS v3 witness with backlink info but no content (transfer only)
+    const ckbfsWitnesses = (0, witness_1.createChunkedCKBFSV3Witnesses)([new Uint8Array(0)], {
+        previousTxHash,
+        previousWitnessIndex,
+        previousChecksum,
+    });
+    // V3 format uses single index (first witness containing backlink)
+    const contentStartIndex = 1; // First witness is for signer, backlink at index 1
+    // Create CKBFS v3 cell output data (unchanged for transfer)
+    const outputData = molecule_1.CKBFSData.pack({
+        index: contentStartIndex,
+        checksum: ckbfsCell.data.checksum, // Checksum unchanged in transfer
+        contentType: ckbfsCell.data.contentType,
+        filename: ckbfsCell.data.filename,
+    }, constants_1.ProtocolVersion.V3);
+    // Get CKBFS script config
+    const config = (0, constants_1.getCKBFSScriptConfig)(network, constants_1.ProtocolVersion.V3, false);
+    // Create transaction
+    const tx = core_1.Transaction.from({
+        inputs: [
+            {
+                previousOutput: ckbfsCell.outPoint,
+                since: "0x0",
+            },
+        ],
+        outputs: [
+            {
+                lock: newLock,
+                type: ckbfsCell.type,
+                capacity: ckbfsCell.capacity,
+            },
+        ],
+        witnesses: [
+            [], // Empty secp witness for signing
+            ...ckbfsWitnesses.map((w) => `0x${Buffer.from(w).toString("hex")}`),
+        ],
+        outputsData: [outputData],
+    });
+    // Add the CKBFS dep group cell dependency
+    tx.addCellDeps({
+        outPoint: {
+            txHash: (0, shared_1.ensureHexPrefix)(config.depTxHash),
+            index: config.depIndex || 0,
+        },
+        depType: "depGroup",
+    });
+    // Complete inputs by capacity for fees
+    await tx.completeInputsByCapacity(signer);
+    // Complete fee change to lock
+    await tx.completeFeeChangeToLock(signer, newLock, feeRate || 2000);
+    return tx;
+}
+/**
+ * Creates a complete transaction for publishing a file to CKBFS v3
+ * @param signer The signer to use for the transaction
+ * @param options Options for publishing the file
+ * @returns Promise resolving to the signed transaction
+ */
+async function publishCKBFSV3(signer, options) {
+    const tx = await createPublishV3Transaction(signer, options);
+    return signer.signTransaction(tx);
+}
+/**
+ * Creates a complete transaction for appending content to a CKBFS v3 file
+ * @param signer The signer to use for the transaction
+ * @param options Options for appending content
+ * @returns Promise resolving to the signed transaction
+ */
+async function appendCKBFSV3(signer, options) {
+    const tx = await createAppendV3Transaction(signer, options);
+    return signer.signTransaction(tx);
+}
+/**
+ * Creates a complete transaction for transferring ownership of a CKBFS v3 file
+ * @param signer The signer to use for the transaction
+ * @param options Options for transferring the file
+ * @returns Promise resolving to the signed transaction
+ */
+async function transferCKBFSV3(signer, options) {
+    const tx = await createTransferV3Transaction(signer, options);
+    return signer.signTransaction(tx);
+}

package/dist/utils/witness.d.ts

@@ -1,6 +1,16 @@
 /**
  * Utility functions for creating and handling CKBFS witnesses
  */
+/**
+ * V3 witness structure for backlinks and content chaining
+ */
+export interface CKBFSV3WitnessOptions {
+    previousTxHash?: string;
+    previousWitnessIndex?: number;
+    previousChecksum?: number;
+    nextIndex?: number;
+    content: Uint8Array;
+}
 /**
  * Creates a CKBFS witness with content
  * @param content The content to include in the witness
@@ -30,6 +40,41 @@ export declare function extractCKBFSWitnessContent(witness: Uint8Array): {
  * @returns Boolean indicating whether the witness is a valid CKBFS witness
  */
 export declare function isCKBFSWitness(witness: Uint8Array): boolean;
+/**
+ * Creates a CKBFS v3 witness with structured format
+ * @param options Witness options including backlink data and content
+ * @returns Uint8Array containing the v3 witness data
+ */
+export declare function createCKBFSV3Witness(options: CKBFSV3WitnessOptions): Uint8Array;
+/**
+ * Creates an array of v3 witnesses for chunked content
+ * @param contentChunks Array of content chunks
+ * @param options Backlink options for head witness and start index
+ * @returns Array of Uint8Array witnesses
+ */
+export declare function createChunkedCKBFSV3Witnesses(contentChunks: Uint8Array[], options?: Omit<CKBFSV3WitnessOptions, 'content' | 'nextIndex'> & {
+    startIndex?: number;
+}): Uint8Array[];
+/**
+ * Extracts content from a CKBFS v3 witness
+ * @param witness The CKBFS v3 witness data
+ * @param isHeadWitness Whether this is the head witness or a continuation witness
+ * @returns Object containing the extracted data
+ */
+export declare function extractCKBFSV3WitnessContent(witness: Uint8Array, isHeadWitness?: boolean): {
+    version?: number;
+    previousTxHash?: string;
+    previousWitnessIndex?: number;
+    previousChecksum?: number;
+    nextIndex: number;
+    content: Uint8Array;
+};
+/**
+ * Checks if a witness is a valid CKBFS v3 witness
+ * @param witness The witness data to check
+ * @returns Boolean indicating whether the witness is a valid CKBFS v3 witness
+ */
+export declare function isCKBFSV3Witness(witness: Uint8Array): boolean;
 /**
  * Creates an array of witnesses for a CKBFS transaction from content chunks
  * @param contentChunks Array of content chunks