@ckbfs/api 1.5.0 → 2.0.0

package/src/index.ts

@@ -11,6 +11,8 @@ import {
   verifyChecksum,
   updateChecksum,
   verifyWitnessChecksum,
+  verifyV3WitnessChecksum,
+  verifyV3WitnessChain,
 } from "./utils/checksum";
 import {
   createCKBFSCell,
@@ -24,6 +26,16 @@ import {
   CKBFSCellOptions,
   PublishOptions,
   AppendOptions,
+  // V3 functions
+  PublishV3Options,
+  AppendV3Options,
+  TransferV3Options,
+  publishCKBFSV3,
+  appendCKBFSV3,
+  transferCKBFSV3,
+  createPublishV3Transaction,
+  createAppendV3Transaction,
+  createTransferV3Transaction,
 } from "./utils/transaction";
 import {
   readFile,
@@ -48,6 +60,10 @@ import {
   extractFileFromWitnesses,
   decodeFileFromWitnessData,
   saveFileFromWitnessData,
+  // V3 file retrieval functions
+  getFileContentFromChainV3,
+  getFileContentFromChainByIdentifierV3,
+  saveFileFromChainByIdentifierV3,
 } from "./utils/file";
 import {
   createCKBFSWitness,
@@ -55,6 +71,11 @@ import {
   extractCKBFSWitnessContent,
   isCKBFSWitness,
   createChunkedCKBFSWitnesses,
+  createCKBFSV3Witness,
+  createChunkedCKBFSV3Witnesses,
+  extractCKBFSV3WitnessContent,
+  isCKBFSV3Witness,
+  CKBFSV3WitnessOptions,
 } from "./utils/witness";
 import {
   CKBFSData,
@@ -115,7 +136,13 @@ export type PublishContentOptions = Omit<
 export type AppendContentOptions = Omit<
   FileOptions,
   "contentType" | "filename" | "capacity"
-> & { capacity?: bigint };
+> & { 
+  capacity?: bigint;
+  // V3 backlink parameters (optional for backward compatibility)
+  previousTxHash?: string;
+  previousWitnessIndex?: number;
+  previousChecksum?: number;
+};
 
 /**
  * Configuration options for the CKBFS SDK
@@ -242,26 +269,52 @@ export class CKBFS {
     const pathParts = filePath.split(/[\\\/]/);
     const filename = options.filename || pathParts[pathParts.length - 1];
 
-    // Create and sign the transaction using the utility function
-    const tx = await utilPublishCKBFS(this.signer, {
-      contentChunks,
-      contentType,
-      filename,
-      lock,
-      capacity: options.capacity,
-      feeRate: options.feeRate,
-      network: options.network || this.network,
-      version: options.version || this.version,
-      useTypeID:
-        options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
-    });
+    // Determine version - default to V3, allow override
+    const version = options.version || this.version;
 
-    console.log("Publish file tx:", tx.stringify());
+    // Use V3 by default, fallback to legacy for older versions
+    if (version === ProtocolVersion.V3) {
+      const tx = await publishCKBFSV3(this.signer, {
+        contentChunks,
+        contentType,
+        filename,
+        lock,
+        capacity: options.capacity,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        useTypeID:
+          options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+        version: ProtocolVersion.V3,
+      });
 
-    // Send the transaction
-    const txHash = await this.signer.sendTransaction(tx);
+      console.log("Publish file tx:", tx.stringify());
 
-    return ensureHexPrefix(txHash);
+      // Send the transaction
+      const txHash = await this.signer.sendTransaction(tx);
+
+      return ensureHexPrefix(txHash);
+    } else {
+      // Legacy V1/V2 behavior
+      const tx = await utilPublishCKBFS(this.signer, {
+        contentChunks,
+        contentType,
+        filename,
+        lock,
+        capacity: options.capacity,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version,
+        useTypeID:
+          options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      });
+
+      console.log("Publish file tx:", tx.stringify());
+
+      // Send the transaction
+      const txHash = await this.signer.sendTransaction(tx);
+
+      return ensureHexPrefix(txHash);
+    }
   }
 
   /**
@@ -287,23 +340,44 @@ export class CKBFS {
     // Use provided contentType and filename (required)
     const { contentType, filename } = options;
 
-    const tx = await utilPublishCKBFS(this.signer, {
-      contentChunks,
-      contentType,
-      filename,
-      lock,
-      capacity: options.capacity,
-      feeRate: options.feeRate,
-      network: options.network || this.network,
-      version: options.version || this.version,
-      useTypeID:
-        options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
-    });
+    // Determine version - default to V3, allow override
+    const version = options.version || this.version;
 
-    console.log("Publish content tx:", tx.stringify());
+    // Use V3 by default, fallback to legacy for older versions
+    if (version === ProtocolVersion.V3) {
+      const tx = await publishCKBFSV3(this.signer, {
+        contentChunks,
+        contentType,
+        filename,
+        lock,
+        capacity: options.capacity,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        useTypeID:
+          options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+        version: ProtocolVersion.V3,
+      });
 
-    const txHash = await this.signer.sendTransaction(tx);
-    return ensureHexPrefix(txHash);
+      const txHash = await this.signer.sendTransaction(tx);
+      return ensureHexPrefix(txHash);
+    } else {
+      // Legacy V1/V2 behavior
+      const tx = await utilPublishCKBFS(this.signer, {
+        contentChunks,
+        contentType,
+        filename,
+        lock,
+        capacity: options.capacity,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version,
+        useTypeID:
+          options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      });
+
+      const txHash = await this.signer.sendTransaction(tx);
+      return ensureHexPrefix(txHash);
+    }
   }
 
   /**
@@ -316,7 +390,12 @@ export class CKBFS {
   async appendFile(
     filePath: string,
     ckbfsCell: AppendOptions["ckbfsCell"],
-    options: Omit<FileOptions, "contentType" | "filename"> = {},
+    options: Omit<FileOptions, "contentType" | "filename"> & {
+      // V3 backlink parameters (optional for backward compatibility)
+      previousTxHash?: string;
+      previousWitnessIndex?: number;
+      previousChecksum?: number;
+    } = {},
   ): Promise<string> {
     // Read the file and split into chunks
     const fileContent = readFileAsUint8Array(filePath);
@@ -326,21 +405,45 @@ export class CKBFS {
       contentChunks.push(fileContent.slice(i, i + this.chunkSize));
     }
 
-    // Create and sign the transaction using the utility function
-    const tx = await utilAppendCKBFS(this.signer, {
-      ckbfsCell,
-      contentChunks,
-      feeRate: options.feeRate,
-      network: options.network || this.network,
-      version: options.version || this.version,
-    });
+    // Determine version - default to V3, allow override
+    const version = options.version || this.version;
 
-    console.log("Append file tx:", tx.stringify());
+    // Use V3 when backlink parameters are provided or version is V3
+    if (version === ProtocolVersion.V3 && 
+        options.previousTxHash && 
+        options.previousWitnessIndex !== undefined && 
+        options.previousChecksum !== undefined) {
+      
+      const tx = await appendCKBFSV3(this.signer, {
+        ckbfsCell,
+        contentChunks,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version: ProtocolVersion.V3,
+        previousTxHash: options.previousTxHash,
+        previousWitnessIndex: options.previousWitnessIndex,
+        previousChecksum: options.previousChecksum,
+      });
 
-    // Send the transaction
-    const txHash = await this.signer.sendTransaction(tx);
+      console.log("Append file v3 tx:", tx.stringify());
 
-    return ensureHexPrefix(txHash);
+      const txHash = await this.signer.sendTransaction(tx);
+      return ensureHexPrefix(txHash);
+    } else {
+      // Legacy V1/V2 behavior or when V3 backlink params are missing
+      const tx = await utilAppendCKBFS(this.signer, {
+        ckbfsCell,
+        contentChunks,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version: version === ProtocolVersion.V3 ? ProtocolVersion.V2 : version, // Fallback to V2 if V3 but missing backlink params
+      });
+
+      console.log("Append file tx:", tx.stringify());
+
+      const txHash = await this.signer.sendTransaction(tx);
+      return ensureHexPrefix(txHash);
+    }
   }
 
   /**
@@ -363,19 +466,42 @@ export class CKBFS {
       contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
     }
 
-    const tx = await utilAppendCKBFS(this.signer, {
-      ckbfsCell,
-      contentChunks,
-      feeRate: options.feeRate,
-      network: options.network || this.network,
-      version: options.version || this.version,
-      // No useTypeID option for append
-    });
+    // Determine version - default to V3, allow override
+    const version = options.version || this.version;
 
-    console.log("Append content tx:", tx.stringify());
+    // Use V3 when backlink parameters are provided or version is V3
+    if (version === ProtocolVersion.V3 && 
+        options.previousTxHash && 
+        options.previousWitnessIndex !== undefined && 
+        options.previousChecksum !== undefined) {
+      
+      const tx = await appendCKBFSV3(this.signer, {
+        ckbfsCell,
+        contentChunks,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version: ProtocolVersion.V3,
+        previousTxHash: options.previousTxHash,
+        previousWitnessIndex: options.previousWitnessIndex,
+        previousChecksum: options.previousChecksum,
+      });
 
-    const txHash = await this.signer.sendTransaction(tx);
-    return ensureHexPrefix(txHash);
+      const txHash = await this.signer.sendTransaction(tx);
+      return ensureHexPrefix(txHash);
+    } else {
+      // Legacy V1/V2 behavior or when V3 backlink params are missing
+      const tx = await utilAppendCKBFS(this.signer, {
+        ckbfsCell,
+        contentChunks,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version: version === ProtocolVersion.V3 ? ProtocolVersion.V2 : version, // Fallback to V2 if V3 but missing backlink params
+        // No useTypeID option for append
+      });
+
+      const txHash = await this.signer.sendTransaction(tx);
+      return ensureHexPrefix(txHash);
+    }
   }
 
   /**
@@ -406,8 +532,237 @@ export class CKBFS {
     const pathParts = filePath.split(/[\\\/]/);
     const filename = options.filename || pathParts[pathParts.length - 1];
 
-    // Create the transaction using the utility function
-    return utilCreatePublishTransaction(this.signer, {
+    // Determine version - default to V3, allow override
+    const version = options.version || this.version;
+
+    // Use V3 by default, fallback to legacy for older versions
+    if (version === ProtocolVersion.V3) {
+      return createPublishV3Transaction(this.signer, {
+        contentChunks,
+        contentType,
+        filename,
+        lock,
+        capacity: options.capacity,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        useTypeID:
+          options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+        version: ProtocolVersion.V3,
+      });
+    } else {
+      // Legacy V1/V2 behavior
+      return utilCreatePublishTransaction(this.signer, {
+        contentChunks,
+        contentType,
+        filename,
+        lock,
+        capacity: options.capacity,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version,
+        useTypeID:
+          options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      });
+    }
+  }
+
+  /**
+   * Creates a new transaction for publishing content (string or Uint8Array) directly, but doesn't sign or send it
+   * @param content The content string or byte array to publish
+   * @param options Options for publishing the content (contentType and filename are required)
+   * @returns Promise resolving to the unsigned transaction
+   */
+  async createPublishContentTransaction(
+    content: string | Uint8Array,
+    options: PublishContentOptions,
+  ): Promise<Transaction> {
+    const contentBytes =
+      typeof content === "string" ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    const lock = await this.getLock();
+
+    // Use provided contentType and filename (required)
+    const { contentType, filename } = options;
+
+    // Determine version - default to V3, allow override
+    const version = options.version || this.version;
+
+    // Use V3 by default, fallback to legacy for older versions
+    if (version === ProtocolVersion.V3) {
+      return createPublishV3Transaction(this.signer, {
+        contentChunks,
+        contentType,
+        filename,
+        lock,
+        capacity: options.capacity,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        useTypeID:
+          options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+        version: ProtocolVersion.V3,
+      });
+    } else {
+      // Legacy V1/V2 behavior
+      return utilCreatePublishTransaction(this.signer, {
+        contentChunks,
+        contentType,
+        filename,
+        lock,
+        capacity: options.capacity,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version,
+        useTypeID:
+          options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      });
+    }
+  }
+
+  /**
+   * Creates a new transaction for appending content from a file but doesn't sign or send it
+   * @param filePath The path to the file containing the content to append
+   * @param ckbfsCell The CKBFS cell to append to
+   * @param options Additional options for the append operation
+   * @returns Promise resolving to the unsigned transaction
+   */
+  async createAppendTransaction(
+    filePath: string,
+    ckbfsCell: AppendOptions["ckbfsCell"],
+    options: Omit<FileOptions, "contentType" | "filename"> & {
+      // V3 backlink parameters (optional for backward compatibility)
+      previousTxHash?: string;
+      previousWitnessIndex?: number;
+      previousChecksum?: number;
+    } = {},
+  ): Promise<Transaction> {
+    // Read the file and split into chunks
+    const fileContent = readFileAsUint8Array(filePath);
+    const contentChunks = [];
+
+    for (let i = 0; i < fileContent.length; i += this.chunkSize) {
+      contentChunks.push(fileContent.slice(i, i + this.chunkSize));
+    }
+
+    // Determine version - default to V3, allow override
+    const version = options.version || this.version;
+
+    // Use V3 when backlink parameters are provided or version is V3
+    if (version === ProtocolVersion.V3 && 
+        options.previousTxHash && 
+        options.previousWitnessIndex !== undefined && 
+        options.previousChecksum !== undefined) {
+      
+      return createAppendV3Transaction(this.signer, {
+        ckbfsCell,
+        contentChunks,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version: ProtocolVersion.V3,
+        previousTxHash: options.previousTxHash,
+        previousWitnessIndex: options.previousWitnessIndex,
+        previousChecksum: options.previousChecksum,
+      });
+    } else {
+      // Legacy V1/V2 behavior or when V3 backlink params are missing
+      return utilCreateAppendTransaction(this.signer, {
+        ckbfsCell,
+        contentChunks,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version: version === ProtocolVersion.V3 ? ProtocolVersion.V2 : version, // Fallback to V2 if V3 but missing backlink params
+      });
+    }
+  }
+
+  /**
+   * Creates a new transaction for appending content (string or Uint8Array) directly, but doesn't sign or send it
+   * @param content The content string or byte array to append
+   * @param ckbfsCell The CKBFS cell to append to
+   * @param options Additional options for the append operation
+   * @returns Promise resolving to the unsigned transaction
+   */
+  async createAppendContentTransaction(
+    content: string | Uint8Array,
+    ckbfsCell: AppendOptions["ckbfsCell"],
+    options: AppendContentOptions = {},
+  ): Promise<Transaction> {
+    const contentBytes =
+      typeof content === "string" ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    // Determine version - default to V3, allow override
+    const version = options.version || this.version;
+
+    // Use V3 when backlink parameters are provided or version is V3
+    if (version === ProtocolVersion.V3 && 
+        options.previousTxHash && 
+        options.previousWitnessIndex !== undefined && 
+        options.previousChecksum !== undefined) {
+      
+      return createAppendV3Transaction(this.signer, {
+        ckbfsCell,
+        contentChunks,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version: ProtocolVersion.V3,
+        previousTxHash: options.previousTxHash,
+        previousWitnessIndex: options.previousWitnessIndex,
+        previousChecksum: options.previousChecksum,
+      });
+    } else {
+      // Legacy V1/V2 behavior or when V3 backlink params are missing
+      return utilCreateAppendTransaction(this.signer, {
+        ckbfsCell,
+        contentChunks,
+        feeRate: options.feeRate,
+        network: options.network || this.network,
+        version: version === ProtocolVersion.V3 ? ProtocolVersion.V2 : version, // Fallback to V2 if V3 but missing backlink params
+        // No useTypeID option for append
+      });
+    }
+  }
+
+  // V3 Methods
+
+  /**
+   * Publishes a file to CKBFS v3
+   * @param filePath The path to the file to publish
+   * @param options Options for publishing the file
+   * @returns Promise resolving to the transaction hash
+   */
+  async publishFileV3(
+    filePath: string,
+    options: Omit<FileOptions, 'version'> = {},
+  ): Promise<string> {
+    // Read the file and split into chunks
+    const fileContent = readFileAsUint8Array(filePath);
+    const contentChunks = [];
+
+    for (let i = 0; i < fileContent.length; i += this.chunkSize) {
+      contentChunks.push(fileContent.slice(i, i + this.chunkSize));
+    }
+
+    // Get the lock script
+    const lock = await this.getLock();
+
+    // Determine content type if not provided
+    const contentType = options.contentType || getContentType(filePath);
+
+    // Use the filename from the path if not provided
+    const pathParts = filePath.split(/[\\\/]/);
+    const filename = options.filename || pathParts[pathParts.length - 1];
+
+    // Create and sign the transaction using the v3 utility function
+    const tx = await publishCKBFSV3(this.signer, {
       contentChunks,
       contentType,
       filename,
@@ -415,22 +770,28 @@ export class CKBFS {
       capacity: options.capacity,
       feeRate: options.feeRate,
       network: options.network || this.network,
-      version: options.version || this.version,
-      useTypeID:
-        options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      useTypeID: options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      version: ProtocolVersion.V3,
     });
+
+    console.log("Publish file v3 tx:", tx.stringify());
+
+    // Send the transaction
+    const txHash = await this.signer.sendTransaction(tx);
+
+    return ensureHexPrefix(txHash);
   }
 
   /**
-   * Creates a new transaction for publishing content (string or Uint8Array) directly, but doesn't sign or send it
+   * Publishes content (string or Uint8Array) directly to CKBFS v3
    * @param content The content string or byte array to publish
    * @param options Options for publishing the content (contentType and filename are required)
-   * @returns Promise resolving to the unsigned transaction
+   * @returns Promise resolving to the transaction hash
    */
-  async createPublishContentTransaction(
+  async publishContentV3(
     content: string | Uint8Array,
     options: PublishContentOptions,
-  ): Promise<Transaction> {
+  ): Promise<string> {
     const contentBytes =
       typeof content === "string" ? textEncoder.encode(content) : content;
     const contentChunks = [];
@@ -444,7 +805,7 @@ export class CKBFS {
     // Use provided contentType and filename (required)
     const { contentType, filename } = options;
 
-    return utilCreatePublishTransaction(this.signer, {
+    const tx = await publishCKBFSV3(this.signer, {
       contentChunks,
       contentType,
       filename,
@@ -452,24 +813,32 @@ export class CKBFS {
       capacity: options.capacity,
       feeRate: options.feeRate,
       network: options.network || this.network,
-      version: options.version || this.version,
-      useTypeID:
-        options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      useTypeID: options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      version: ProtocolVersion.V3,
     });
+
+    const txHash = await this.signer.sendTransaction(tx);
+    return ensureHexPrefix(txHash);
   }
 
   /**
-   * Creates a new transaction for appending content from a file but doesn't sign or send it
+   * Appends content from a file to an existing CKBFS v3 file
    * @param filePath The path to the file containing the content to append
    * @param ckbfsCell The CKBFS cell to append to
+   * @param previousTxHash The previous transaction hash for backlink
+   * @param previousWitnessIndex The previous witness index for backlink
+   * @param previousChecksum The previous checksum for backlink
    * @param options Additional options for the append operation
-   * @returns Promise resolving to the unsigned transaction
+   * @returns Promise resolving to the transaction hash
    */
-  async createAppendTransaction(
+  async appendFileV3(
     filePath: string,
-    ckbfsCell: AppendOptions["ckbfsCell"],
-    options: Omit<FileOptions, "contentType" | "filename"> = {},
-  ): Promise<Transaction> {
+    ckbfsCell: AppendV3Options["ckbfsCell"],
+    previousTxHash: string,
+    previousWitnessIndex: number,
+    previousChecksum: number,
+    options: Omit<FileOptions, "contentType" | "filename" | "version"> = {},
+  ): Promise<string> {
     // Read the file and split into chunks
     const fileContent = readFileAsUint8Array(filePath);
     const contentChunks = [];
@@ -478,28 +847,44 @@ export class CKBFS {
       contentChunks.push(fileContent.slice(i, i + this.chunkSize));
     }
 
-    // Create the transaction using the utility function
-    return utilCreateAppendTransaction(this.signer, {
+    // Create and sign the transaction using the v3 utility function
+    const tx = await appendCKBFSV3(this.signer, {
       ckbfsCell,
       contentChunks,
       feeRate: options.feeRate,
       network: options.network || this.network,
-      version: options.version || this.version,
+      version: ProtocolVersion.V3,
+      previousTxHash,
+      previousWitnessIndex,
+      previousChecksum,
     });
+
+    console.log("Append file v3 tx:", tx.stringify());
+
+    // Send the transaction
+    const txHash = await this.signer.sendTransaction(tx);
+
+    return ensureHexPrefix(txHash);
   }
 
   /**
-   * Creates a new transaction for appending content (string or Uint8Array) directly, but doesn't sign or send it
+   * Appends content (string or Uint8Array) directly to an existing CKBFS v3 file
    * @param content The content string or byte array to append
    * @param ckbfsCell The CKBFS cell to append to
+   * @param previousTxHash The previous transaction hash for backlink
+   * @param previousWitnessIndex The previous witness index for backlink
+   * @param previousChecksum The previous checksum for backlink
    * @param options Additional options for the append operation
-   * @returns Promise resolving to the unsigned transaction
+   * @returns Promise resolving to the transaction hash
    */
-  async createAppendContentTransaction(
+  async appendContentV3(
     content: string | Uint8Array,
-    ckbfsCell: AppendOptions["ckbfsCell"],
+    ckbfsCell: AppendV3Options["ckbfsCell"],
+    previousTxHash: string,
+    previousWitnessIndex: number,
+    previousChecksum: number,
     options: AppendContentOptions = {},
-  ): Promise<Transaction> {
+  ): Promise<string> {
     const contentBytes =
       typeof content === "string" ? textEncoder.encode(content) : content;
     const contentChunks = [];
@@ -508,13 +893,95 @@ export class CKBFS {
       contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
     }
 
-    return utilCreateAppendTransaction(this.signer, {
+    const tx = await appendCKBFSV3(this.signer, {
       ckbfsCell,
       contentChunks,
       feeRate: options.feeRate,
       network: options.network || this.network,
-      version: options.version || this.version,
-      // No useTypeID option for append
+      version: ProtocolVersion.V3,
+      previousTxHash,
+      previousWitnessIndex,
+      previousChecksum,
+    });
+
+    const txHash = await this.signer.sendTransaction(tx);
+    return ensureHexPrefix(txHash);
+  }
+
+  /**
+   * Transfers ownership of a CKBFS v3 file to a new lock script
+   * @param ckbfsCell The CKBFS cell to transfer
+   * @param newLock The new lock script for the transferred file
+   * @param previousTxHash The previous transaction hash for backlink
+   * @param previousWitnessIndex The previous witness index for backlink
+   * @param previousChecksum The previous checksum for backlink
+   * @param options Additional options for the transfer operation
+   * @returns Promise resolving to the transaction hash
+   */
+  async transferFileV3(
+    ckbfsCell: TransferV3Options["ckbfsCell"],
+    newLock: Script,
+    previousTxHash: string,
+    previousWitnessIndex: number,
+    previousChecksum: number,
+    options: Omit<FileOptions, "contentType" | "filename" | "version"> = {},
+  ): Promise<string> {
+    const tx = await transferCKBFSV3(this.signer, {
+      ckbfsCell,
+      newLock,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: ProtocolVersion.V3,
+      previousTxHash,
+      previousWitnessIndex,
+      previousChecksum,
+    });
+
+    console.log("Transfer file v3 tx:", tx.stringify());
+
+    const txHash = await this.signer.sendTransaction(tx);
+    return ensureHexPrefix(txHash);
+  }
+
+  /**
+   * Creates a new transaction for publishing a file to CKBFS v3 but doesn't sign or send it
+   * @param filePath The path to the file to publish
+   * @param options Options for publishing the file
+   * @returns Promise resolving to the unsigned transaction
+   */
+  async createPublishV3Transaction(
+    filePath: string,
+    options: Omit<FileOptions, 'version'> = {},
+  ): Promise<Transaction> {
+    // Read the file and split into chunks
+    const fileContent = readFileAsUint8Array(filePath);
+    const contentChunks = [];
+
+    for (let i = 0; i < fileContent.length; i += this.chunkSize) {
+      contentChunks.push(fileContent.slice(i, i + this.chunkSize));
+    }
+
+    // Get the lock script
+    const lock = await this.getLock();
+
+    // Determine content type if not provided
+    const contentType = options.contentType || getContentType(filePath);
+
+    // Use the filename from the path if not provided
+    const pathParts = filePath.split(/[\\\/]/);
+    const filename = options.filename || pathParts[pathParts.length - 1];
+
+    // Create the transaction using the utility function
+    return createPublishV3Transaction(this.signer, {
+      contentChunks,
+      contentType,
+      filename,
+      lock,
+      capacity: options.capacity,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      useTypeID: options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+      version: ProtocolVersion.V3,
     });
   }
 }
@@ -526,6 +993,8 @@ export {
   verifyChecksum,
   updateChecksum,
   verifyWitnessChecksum,
+  verifyV3WitnessChecksum,
+  verifyV3WitnessChain,
 
   // Transaction utilities (Exporting original names from transaction.ts)
   createCKBFSCell,
@@ -559,6 +1028,11 @@ export {
   extractFileFromWitnesses,
   decodeFileFromWitnessData,
   saveFileFromWitnessData,
+  
+  // V3 File utilities
+  getFileContentFromChainV3,
+  getFileContentFromChainByIdentifierV3,
+  saveFileFromChainByIdentifierV3,
 
   // Witness utilities
   createCKBFSWitness,
@@ -566,6 +1040,13 @@ export {
   extractCKBFSWitnessContent,
   isCKBFSWitness,
   createChunkedCKBFSWitnesses,
+  
+  // V3 Witness utilities
+  createCKBFSV3Witness,
+  createChunkedCKBFSV3Witnesses,
+  extractCKBFSV3WitnessContent,
+  isCKBFSV3Witness,
+  CKBFSV3WitnessOptions,
 
   // Molecule definitions
   CKBFSData,