@ckbfs/api 1.5.0 → 2.0.0

package/src/utils/checksum.ts

@@ -43,15 +43,9 @@ export async function updateChecksum(previousChecksum: number, newData: Uint8Arr
     adlerB = (adlerB + adlerA) % MOD_ADLER;
   }
   
-  // Combine a and b to get the final checksum
-  // Use a Uint32Array to ensure we get a proper unsigned 32-bit integer
-  const buffer = new ArrayBuffer(4);
-  const view = new DataView(buffer);
-  view.setUint16(0, adlerA, true); // Set lower 16 bits (little endian)
-  view.setUint16(2, adlerB, true); // Set upper 16 bits (little endian)
-  
-  // Read as an unsigned 32-bit integer
-  const updatedChecksum = view.getUint32(0, true);
+  // Combine a and b to get the final checksum using standard Adler32 format
+  // In Adler32, checksum = (b << 16) | a
+  const updatedChecksum = ((adlerB << 16) | adlerA) >>> 0; // Use unsigned right shift to ensure uint32
   
   console.log(`Updated checksum from ${previousChecksum} to ${updatedChecksum} for appended content`);
   
@@ -93,4 +87,91 @@ export async function verifyWitnessChecksum(
   
   // Otherwise, calculate checksum from scratch
   return verifyChecksum(contentBytes, expectedChecksum);
+}
+
+/**
+ * Verifies the checksum of a CKBFS v3 witness
+ * @param witness The v3 witness bytes
+ * @param expectedChecksum The expected checksum
+ * @param previousChecksum Optional previous checksum for chained verification
+ * @returns Promise resolving to a boolean indicating whether the checksum is valid
+ */
+export async function verifyV3WitnessChecksum(
+  witness: Uint8Array,
+  expectedChecksum: number,
+  previousChecksum?: number
+): Promise<boolean> {
+  // Check if this is a head witness (contains CKBFS header)
+  const isHeadWitness = witness.length >= 50 && 
+    new TextDecoder().decode(witness.slice(0, 5)) === 'CKBFS' &&
+    witness[5] === 0x03;
+  
+  let contentBytes: Uint8Array;
+  let extractedPreviousChecksum: number | undefined = previousChecksum;
+  
+  if (isHeadWitness) {
+    // Head witness: extract content after backlink structure
+    // Format: CKBFS(5) + version(1) + prevTxHash(32) + prevWitnessIndex(4) + prevChecksum(4) + nextIndex(4) + content
+    contentBytes = witness.slice(50);
+    
+    // Extract previous checksum from head witness if not provided externally
+    if (previousChecksum === undefined) {
+      const prevChecksumBytes = witness.slice(42, 46);
+      extractedPreviousChecksum = new DataView(prevChecksumBytes.buffer).getUint32(0, true); // little-endian
+    }
+  } else {
+    // Continuation witness: extract content after next index
+    // Format: nextIndex(4) + content
+    contentBytes = witness.slice(4);
+  }
+  
+  // If previous checksum is available (either provided or extracted), use it for rolling calculation
+  if (extractedPreviousChecksum !== undefined && extractedPreviousChecksum !== 0) {
+    const updatedChecksum = await updateChecksum(extractedPreviousChecksum, contentBytes);
+    return updatedChecksum === expectedChecksum;
+  }
+  
+  // Otherwise, calculate checksum from scratch
+  return verifyChecksum(contentBytes, expectedChecksum);
+}
+
+/**
+ * Verifies the checksum chain for multiple v3 witnesses
+ * @param witnesses Array of v3 witness bytes
+ * @param finalExpectedChecksum The expected final checksum
+ * @param initialChecksum Optional initial checksum (for append operations)
+ * @returns Promise resolving to a boolean indicating whether the checksum chain is valid
+ */
+export async function verifyV3WitnessChain(
+  witnesses: Uint8Array[],
+  finalExpectedChecksum: number,
+  initialChecksum: number = 1 // Adler32 starts with 1
+): Promise<boolean> {
+  if (witnesses.length === 0) {
+    return finalExpectedChecksum === initialChecksum;
+  }
+  
+  let currentChecksum = initialChecksum;
+  
+  // Process each witness in the chain
+  for (const witness of witnesses) {
+    const isHeadWitness = witness.length >= 50 && 
+      new TextDecoder().decode(witness.slice(0, 5)) === 'CKBFS' &&
+      witness[5] === 0x03;
+    
+    let contentBytes: Uint8Array;
+    
+    if (isHeadWitness) {
+      // Head witness: extract content after backlink structure
+      contentBytes = witness.slice(50);
+    } else {
+      // Continuation witness: extract content after next index
+      contentBytes = witness.slice(4);
+    }
+    
+    // Update checksum with this witness's content
+    currentChecksum = await updateChecksum(currentChecksum, contentBytes);
+  }
+  
+  return currentChecksum === finalExpectedChecksum;
 } 

package/src/utils/constants.ts

@@ -11,6 +11,7 @@ export enum NetworkType {
 export const ProtocolVersion = {
   V1: "20240906.ce6724722cf6", // Original version, compact and simple, suitable for small files
   V2: "20241025.db973a8e8032", // New version, more features and can do complex operations
+  V3: "20250821.4ee6689bf7ec", // Witnesses-based storage, no backlinks in cell data, more affordable
 } as const;
 
 export type ProtocolVersionType =
@@ -28,6 +29,8 @@ export const CKBFS_CODE_HASH: Record<NetworkType, Record<string, string>> = {
       "0xe8905ad29a02cf8befa9c258f4f941773839a618d75a64afc22059de9413f712",
     [ProtocolVersion.V2]:
       "0x31e6376287d223b8c0410d562fb422f04d1d617b2947596a14c3d2efb7218d3a",
+    [ProtocolVersion.V3]:
+      "0xb5d13ffe0547c78021c01fe24dce2e959a1ed8edbca3cb93dd2e9f57fb56d695",
   },
 };
 
@@ -41,6 +44,8 @@ export const CKBFS_TYPE_ID: Record<NetworkType, Record<string, string>> = {
       "0x88ef4d436af35684a27edda0d44dd8771318330285f90f02d13606e095aea86f",
     [ProtocolVersion.V2]:
       "0x7c6dcab8268201f064dc8676b5eafa60ca2569e5c6209dcbab0eb64a9cb3aaa3",
+    [ProtocolVersion.V3]:
+      "0xaebf5a7b541da9603c2066a9768d3d18fea2e7f3c1943821611545155fecc671",
   },
 };
 
@@ -55,6 +60,8 @@ export const ADLER32_CODE_HASH: Record<NetworkType, Record<string, string>> = {
       "0x8af42cd329cf1bcffb4c73b48252e99cb32346fdbc1cdaa5ae1d000232d47e84",
     [ProtocolVersion.V2]:
       "0x2138683f76944437c0c643664120d620bdb5858dd6c9d1d156805e279c2c536f",
+    [ProtocolVersion.V3]:
+      "0xbd944c8c5aa127270b591d50ab899c9a2a3e4429300db4ea3d7523aa592c1db1",
   },
 };
 
@@ -68,6 +75,8 @@ export const ADLER32_TYPE_ID: Record<NetworkType, Record<string, string>> = {
       "0xccf29a0d8e860044a3d2f6a6e709f6572f77e4fe245fadd212fc342337048d60",
     [ProtocolVersion.V2]:
       "0x5f73f128be76e397f5a3b56c94ca16883a8ee91b498bc0ee80473818318c05ac",
+    [ProtocolVersion.V3]:
+      "0x552e2a5e679f45bca7834b03a1f8613f2a910b64a7bafb51986cfc6f1b6cb31c",
   },
 };
 
@@ -82,6 +91,8 @@ export const DEP_GROUP_TX_HASH: Record<NetworkType, Record<string, string>> = {
       "0xc8fd44aba36f0c4b37536b6c7ea3b88df65fa97e02f77cd33b9bf20bf241a09b",
     [ProtocolVersion.V2]:
       "0x469af0d961dcaaedd872968a9388b546717a6ccfa47b3165b3f9c981e9d66aaa",
+    [ProtocolVersion.V3]:
+      "0x47cfa8d554cccffe7796f93b58437269de1f98f029d0a52b6b146381f3e95e61",
   },
 };
 
@@ -111,11 +122,17 @@ export const DEPLOY_TX_HASH: Record<
       adler32:
         "0x2c8c9ad3134743368b5a79977648f96c5bd0aba187021a72fb624301064d3616",
     },
+    [ProtocolVersion.V3]: {
+      ckbfs:
+        "0x1488b592b0946589730c906c6d9a46fb82c1181156fc1a4251adce14002a9cfb",
+      adler32:
+        "0x8d6bd7ea704f9b19af5b83b81544c34982515a825e6185d88faf47583a542671",
+    },
   },
 };
 
-// Default values - V2 is now the default
-export const DEFAULT_VERSION = ProtocolVersion.V2;
+// Default values - V3 is now the default
+export const DEFAULT_VERSION = ProtocolVersion.V3;
 export const DEFAULT_NETWORK = NetworkType.Testnet;
 
 // Helper function to get CKBFS script configuration

package/src/utils/file.ts

@@ -1,5 +1,7 @@
 import fs from "fs";
 import path from "path";
+import { ProtocolVersion } from "./constants";
+import { extractCKBFSV3WitnessContent, isCKBFSV3Witness } from "./witness";
 
 /**
  * Utility functions for file operations
@@ -524,7 +526,7 @@ async function resolveCKBFSCell(
 } | null> {
   const {
     network = "testnet",
-    version = "20241025.db973a8e8032",
+    version = ProtocolVersion.V3,
     useTypeID = false,
   } = options;
 
@@ -628,7 +630,7 @@ async function findCKBFSCellByTypeId(
   client: any,
   typeId: string,
   network: string = "testnet",
-  version: string = "20241025.db973a8e8032",
+  version: string = ProtocolVersion.V3,
   useTypeID: boolean = false,
 ): Promise<{
   cell: any;
@@ -644,10 +646,20 @@ async function findCKBFSCellByTypeId(
     // Get CKBFS script config
     const networkType =
       network === "mainnet" ? NetworkType.Mainnet : NetworkType.Testnet;
-    const protocolVersion =
-      version === "20240906.ce6724722cf6"
-        ? ProtocolVersion.V1
-        : ProtocolVersion.V2;
+    
+    // Map version strings to protocol versions
+    let protocolVersion: string;
+    if (version === "20240906.ce6724722cf6") {
+      protocolVersion = ProtocolVersion.V1;
+    } else if (version === "20241025.db973a8e8032") {
+      protocolVersion = ProtocolVersion.V2;
+    } else if (version === "20250821.4ee6689bf7ec" || version === ProtocolVersion.V3) {
+      protocolVersion = ProtocolVersion.V3;
+    } else {
+      // Default to the version passed in if it doesn't match known patterns
+      protocolVersion = version;
+    }
+
     const config = getCKBFSScriptConfig(
       networkType,
       protocolVersion,
@@ -716,7 +728,7 @@ export async function getFileContentFromChainByIdentifier(
 } | null> {
   const {
     network = "testnet",
-    version = "20241025.db973a8e8032",
+    version = ProtocolVersion.V3,
     useTypeID = false,
   } = options;
 
@@ -757,20 +769,30 @@ export async function getFileContentFromChainByIdentifier(
       ? ccc.bytesFrom(outputData.slice(2), "hex")
       : Buffer.from(outputData, "hex");
 
-    // Try to unpack CKBFS data with both protocol versions
+    // Try to unpack CKBFS data with all protocol versions (V3, V2, V1)
     let ckbfsData: any;
     let protocolVersion = version;
 
     try {
-      ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
-    } catch (error) {
+      // Try V3 first if the version suggests it
+      if (version === ProtocolVersion.V3 || version === "20250821.4ee6689bf7ec") {
+        ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V3);
+      } else {
+        throw new Error("Not V3 version");
+      }
+    } catch (v3Error) {
       try {
-        ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
-        protocolVersion = "20240906.ce6724722cf6";
-      } catch (v1Error) {
-        throw new Error(
-          `Failed to unpack CKBFS data with both versions: V2(${error}), V1(${v1Error})`,
-        );
+        ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+        protocolVersion = ProtocolVersion.V2;
+      } catch (v2Error) {
+        try {
+          ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
+          protocolVersion = ProtocolVersion.V1;
+        } catch (v1Error) {
+          throw new Error(
+            `Failed to unpack CKBFS data with all versions: V3(${v3Error}), V2(${v2Error}), V1(${v1Error})`,
+          );
+        }
       }
     }
 
@@ -778,8 +800,13 @@ export async function getFileContentFromChainByIdentifier(
     console.log(`Content type: ${ckbfsData.contentType}`);
     console.log(`Protocol version: ${protocolVersion}`);
 
-    // Use existing function to get complete file content
-    const content = await getFileContentFromChain(client, outPoint, ckbfsData);
+    // Use appropriate function to get complete file content based on protocol version
+    let content: Uint8Array;
+    if (protocolVersion === ProtocolVersion.V3) {
+      content = await getFileContentFromChainV3(client, outPoint, ckbfsData);
+    } else {
+      content = await getFileContentFromChain(client, outPoint, ckbfsData);
+    }
 
     return {
       content,
@@ -937,7 +964,7 @@ export async function decodeFileFromChainByIdentifier(
 } | null> {
   const {
     network = "testnet",
-    version = "20241025.db973a8e8032",
+    version = ProtocolVersion.V3,
     useTypeID = false,
   } = options;
 
@@ -976,20 +1003,30 @@ export async function decodeFileFromChainByIdentifier(
       ? ccc.bytesFrom(outputData.slice(2), "hex")
       : Buffer.from(outputData, "hex");
 
-    // Try to unpack CKBFS data with both protocol versions
+    // Try to unpack CKBFS data with all protocol versions (V3, V2, V1)
     let ckbfsData: any;
     let protocolVersion = version;
 
     try {
-      ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
-    } catch (error) {
+      // Try V3 first if the version suggests it
+      if (version === ProtocolVersion.V3 || version === "20250821.4ee6689bf7ec") {
+        ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V3);
+      } else {
+        throw new Error("Not V3 version");
+      }
+    } catch (v3Error) {
       try {
-        ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
-        protocolVersion = "20240906.ce6724722cf6";
-      } catch (v1Error) {
-        throw new Error(
-          `Failed to unpack CKBFS data with both versions: V2(${error}), V1(${v1Error})`,
-        );
+        ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+        protocolVersion = ProtocolVersion.V2;
+      } catch (v2Error) {
+        try {
+          ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
+          protocolVersion = ProtocolVersion.V1;
+        } catch (v1Error) {
+          throw new Error(
+            `Failed to unpack CKBFS data with all versions: V3(${v3Error}), V2(${v2Error}), V1(${v1Error})`,
+          );
+        }
       }
     }
 
@@ -1002,13 +1039,24 @@ export async function decodeFileFromChainByIdentifier(
       ckbfsData.indexes ||
       (ckbfsData.index !== undefined ? [ckbfsData.index] : []);
 
-    // Use direct witness decoding method
-    const content = decodeFileFromWitnessData({
-      witnesses: tx.witnesses,
-      indexes: indexes,
-      filename: ckbfsData.filename,
-      contentType: ckbfsData.contentType,
-    });
+    // Use direct witness decoding method for V1/V2, or appropriate method for V3
+    let content: any;
+    if (protocolVersion === ProtocolVersion.V3) {
+      // For V3, we should use the V3-specific content retrieval which handles witness chains
+      const fullContent = await getFileContentFromChainV3(client, outPoint, ckbfsData);
+      content = {
+        content: fullContent,
+        size: fullContent.length,
+      };
+    } else {
+      // For V1/V2, use the direct witness decoding method
+      content = decodeFileFromWitnessData({
+        witnesses: tx.witnesses,
+        indexes: indexes,
+        filename: ckbfsData.filename,
+        contentType: ckbfsData.contentType,
+      });
+    }
 
     return {
       content: content.content,
@@ -1055,3 +1103,306 @@ export async function decodeFileFromChainByTypeId(
   }
   return null;
 }
+
+/**
+ * Retrieves complete file content from the blockchain for CKBFS v3
+ * V3 stores backlinks in witnesses instead of cell data
+ * @param client The CKB client to use for blockchain queries
+ * @param outPoint The output point of the latest CKBFS v3 cell
+ * @param ckbfsData The data from the latest CKBFS v3 cell
+ * @returns Promise resolving to the complete file content
+ */
+export async function getFileContentFromChainV3(
+  client: any,
+  outPoint: { txHash: string; index: number },
+  ckbfsData: any,
+): Promise<Uint8Array> {
+  console.log(`Retrieving v3 file: ${safelyDecode(ckbfsData.filename)}`);
+  console.log(`Content type: ${safelyDecode(ckbfsData.contentType)}`);
+
+  // Follow the CKBFS cell chain backwards to build the complete transaction sequence
+  const transactionChain: Array<{
+    txHash: string;
+    cellIndex: number;
+    witnessIndex: number;
+    content: Uint8Array[];
+    isPublish: boolean;
+  }> = [];
+
+  let currentTxHash = outPoint.txHash;
+  let currentCellIndex = outPoint.index;
+  let currentWitnessIndex = ckbfsData.index;
+
+
+
+  // Follow the chain backwards to build the complete transaction sequence
+  while (currentTxHash && currentWitnessIndex !== undefined) {
+    const tx = await client.getTransaction(currentTxHash);
+    if (!tx || !tx.transaction) {
+      console.warn(`Transaction ${currentTxHash} not found`);
+      break;
+    }
+
+    if (currentWitnessIndex >= tx.transaction.witnesses.length) {
+      console.warn(`Witness index ${currentWitnessIndex} out of range in transaction ${currentTxHash}`);
+      break;
+    }
+
+    const witnessHex = tx.transaction.witnesses[currentWitnessIndex];
+    const witness = new Uint8Array(Buffer.from(witnessHex.slice(2), "hex"));
+
+    // Check if this is a v3 head witness
+    if (isCKBFSV3Witness(witness)) {
+      const witnessData = extractCKBFSV3WitnessContent(witness, true);
+      
+      // Collect content from this transaction (head + continuation witnesses)
+      const txContentPieces: Uint8Array[] = [witnessData.content];
+      
+      // Follow continuation witnesses in this transaction
+      let nextIndex = witnessData.nextIndex;
+      while (nextIndex > 0 && nextIndex < tx.transaction.witnesses.length) {
+        const nextWitnessHex = tx.transaction.witnesses[nextIndex];
+        const nextWitness = new Uint8Array(Buffer.from(nextWitnessHex.slice(2), "hex"));
+
+        const nextWitnessData = extractCKBFSV3WitnessContent(nextWitness, false);
+        txContentPieces.push(nextWitnessData.content);
+
+        nextIndex = nextWitnessData.nextIndex;
+      }
+
+      // Check if this is a publish operation (all zeros for previous position)
+      const isPublish = witnessData.previousTxHash === '0x' + '00'.repeat(32) && 
+                       witnessData.previousWitnessIndex === 0;
+
+      // Add this transaction's content to the beginning of the chain (since we're going backwards)
+      transactionChain.unshift({
+        txHash: currentTxHash,
+        cellIndex: currentCellIndex,
+        witnessIndex: currentWitnessIndex,
+        content: txContentPieces,
+        isPublish,
+      });
+
+      // If this is the original publish operation, we're done
+      if (isPublish) {
+        break;
+      }
+
+      // For append operations, we need to find the previous CKBFS cell
+      const previousTxHash = witnessData.previousTxHash;
+
+      if (!previousTxHash || previousTxHash === '0x' + '00'.repeat(32)) {
+        break;
+      }
+
+      // Get the previous transaction to find the CKBFS cell and its witness index
+      const prevTx = await client.getTransaction(previousTxHash);
+      if (!prevTx || !prevTx.transaction) {
+        console.warn(`Previous transaction ${previousTxHash} not found`);
+        break;
+      }
+
+      // Import Transaction class to parse the previous transaction
+      const { Transaction } = await import("@ckb-ccc/core");
+      const prevTxObj = Transaction.from(prevTx.transaction);
+      
+      // Find the CKBFS cell in the previous transaction (it should have a type script)
+      let prevCkbfsCellIndex = -1;
+      let prevCkbfsData: any = null;
+      
+      for (let i = 0; i < prevTxObj.outputs.length; i++) {
+        const output = prevTxObj.outputs[i];
+        const outputData = prevTxObj.outputsData[i];
+        
+        // Check if this output has a type script (CKBFS cells have type scripts)
+        if (output.type && outputData && outputData !== '0x') {
+          try {
+            // Try to parse as CKBFS data
+            const { ccc } = await import("@ckb-ccc/core");
+            const { CKBFSData } = await import("./molecule");
+            const { ProtocolVersion } = await import("./constants");
+
+            const rawData = outputData.startsWith("0x")
+              ? ccc.bytesFrom(outputData.slice(2), "hex")
+              : Buffer.from(outputData, "hex");
+
+            const ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V3);
+            
+            prevCkbfsCellIndex = i;
+            prevCkbfsData = ckbfsData;
+            break;
+          } catch (error) {
+            // Not a CKBFS cell, continue searching
+          }
+        }
+      }
+
+      if (prevCkbfsCellIndex === -1 || !prevCkbfsData) {
+        console.warn(`No CKBFS cell found in previous transaction ${previousTxHash}`);
+        break;
+      }
+
+      const previousWitnessIndex = prevCkbfsData.index;
+
+      // Move to the previous CKBFS cell
+      currentTxHash = previousTxHash;
+      currentCellIndex = prevCkbfsCellIndex;
+      currentWitnessIndex = previousWitnessIndex;
+    } else {
+      console.warn(`Witness at index ${currentWitnessIndex} in transaction ${currentTxHash} is not a valid CKBFS v3 witness`);
+      break;
+    }
+  }
+
+  // Now assemble all content pieces in chronological order (first creation to latest)
+  const allContentPieces: Uint8Array[] = [];
+  
+  for (const txEntry of transactionChain) {
+    allContentPieces.push(...txEntry.content);
+  }
+
+  // Combine all content pieces
+  return Buffer.concat(allContentPieces);
+}
+
+/**
+ * Retrieves complete file content from the blockchain using identifier for CKBFS v3
+ * @param client The CKB client to use for blockchain queries
+ * @param identifier The identifier (TypeID hex, CKBFS TypeID URI, or CKBFS outPoint URI)
+ * @param options Optional configuration for network, version, and useTypeID
+ * @returns Promise resolving to the complete file content and metadata
+ */
+export async function getFileContentFromChainByIdentifierV3(
+  client: any,
+  identifier: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<{
+  content: Uint8Array;
+  filename: string;
+  contentType: string;
+  checksum: number;
+  size: number;
+  parsedId: ParsedIdentifier;
+} | null> {
+  const {
+    network = "testnet",
+    version = ProtocolVersion.V3,
+    useTypeID = false,
+  } = options;
+
+  try {
+    // Resolve the CKBFS cell using any supported identifier format
+    const cellInfo = await resolveCKBFSCell(client, identifier, {
+      network,
+      version,
+      useTypeID,
+    });
+
+    if (!cellInfo) {
+      console.warn(`CKBFS v3 cell with identifier ${identifier} not found`);
+      return null;
+    }
+
+    const { cell, transaction, outPoint, parsedId } = cellInfo;
+
+    // Import Transaction class dynamically
+    const { Transaction } = await import("@ckb-ccc/core");
+    const tx = Transaction.from(transaction);
+
+    // Get output data from the cell
+    const outputIndex = outPoint.index;
+    const outputData = tx.outputsData[outputIndex];
+
+    if (!outputData) {
+      throw new Error(`Output data not found for cell at index ${outputIndex}`);
+    }
+
+    // Import required modules dynamically
+    const { ccc } = await import("@ckb-ccc/core");
+    const { CKBFSData } = await import("./molecule");
+
+    // Parse the output data
+    const rawData = outputData.startsWith("0x")
+      ? ccc.bytesFrom(outputData.slice(2), "hex")
+      : Buffer.from(outputData, "hex");
+
+    // Unpack CKBFS v3 data
+    const ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V3);
+
+    console.log(`Found CKBFS v3 file: ${ckbfsData.filename}`);
+    console.log(`Content type: ${ckbfsData.contentType}`);
+
+    // Use v3-specific function to get complete file content
+    const content = await getFileContentFromChainV3(client, outPoint, ckbfsData);
+
+    return {
+      content,
+      filename: ckbfsData.filename,
+      contentType: ckbfsData.contentType,
+      checksum: ckbfsData.checksum,
+      size: content.length,
+      parsedId,
+    };
+  } catch (error) {
+    console.error(`Error retrieving v3 file by identifier ${identifier}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Saves CKBFS v3 file content retrieved from blockchain by identifier to disk
+ * @param client The CKB client to use for blockchain queries
+ * @param identifier The identifier (TypeID hex, CKBFS TypeID URI, or CKBFS outPoint URI)
+ * @param outputPath Optional path to save the file (defaults to filename from CKBFS data)
+ * @param options Optional configuration for network, version, and useTypeID
+ * @returns Promise resolving to the path where the file was saved, or null if file not found
+ */
+export async function saveFileFromChainByIdentifierV3(
+  client: any,
+  identifier: string,
+  outputPath?: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<string | null> {
+  try {
+    // Get file content by identifier using v3 method
+    const fileData = await getFileContentFromChainByIdentifierV3(
+      client,
+      identifier,
+      { ...options, version: ProtocolVersion.V3 },
+    );
+
+    if (!fileData) {
+      console.warn(`CKBFS v3 file with identifier ${identifier} not found`);
+      return null;
+    }
+
+    // Determine output path
+    const filePath = outputPath || fileData.filename;
+
+    // Ensure directory exists
+    const directory = path.dirname(filePath);
+    if (!fs.existsSync(directory)) {
+      fs.mkdirSync(directory, { recursive: true });
+    }
+
+    // Write file
+    fs.writeFileSync(filePath, fileData.content);
+    console.log(`CKBFS v3 file saved to: ${filePath}`);
+    console.log(`Size: ${fileData.size} bytes`);
+    console.log(`Content type: ${fileData.contentType}`);
+    console.log(`Checksum: ${fileData.checksum}`);
+
+    return filePath;
+  } catch (error) {
+    console.error(`Error saving v3 file by identifier ${identifier}:`, error);
+    throw error;
+  }
+}