@ckbfs/api 1.5.1 → 2.0.0

package/dist/utils/checksum.js

@@ -4,6 +4,8 @@ exports.calculateChecksum = calculateChecksum;
 exports.updateChecksum = updateChecksum;
 exports.verifyChecksum = verifyChecksum;
 exports.verifyWitnessChecksum = verifyWitnessChecksum;
+exports.verifyV3WitnessChecksum = verifyV3WitnessChecksum;
+exports.verifyV3WitnessChain = verifyV3WitnessChain;
 const hash_wasm_1 = require("hash-wasm");
 /**
  * Utility functions for Adler32 checksum generation and verification
@@ -41,14 +43,9 @@ async function updateChecksum(previousChecksum, newData) {
         adlerA = (adlerA + newData[i]) % MOD_ADLER;
         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`);
     return updatedChecksum;
 }
@@ -81,3 +78,72 @@ async function verifyWitnessChecksum(witness, expectedChecksum, backlinks = [])
     // 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
+ */
+async function verifyV3WitnessChecksum(witness, expectedChecksum, previousChecksum) {
+    // 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;
+    let extractedPreviousChecksum = 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
+ */
+async function verifyV3WitnessChain(witnesses, finalExpectedChecksum, initialChecksum = 1 // Adler32 starts with 1
+) {
+    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;
+        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/dist/utils/constants.d.ts

@@ -8,6 +8,7 @@ export declare enum NetworkType {
 export declare const ProtocolVersion: {
     readonly V1: "20240906.ce6724722cf6";
     readonly V2: "20241025.db973a8e8032";
+    readonly V3: "20250821.4ee6689bf7ec";
 };
 export type ProtocolVersionType = (typeof ProtocolVersion)[keyof typeof ProtocolVersion] | string;
 export declare const CKBFS_CODE_HASH: Record<NetworkType, Record<string, string>>;
@@ -19,7 +20,7 @@ export declare const DEPLOY_TX_HASH: Record<NetworkType, Record<string, {
     ckbfs: string;
     adler32: string;
 }>>;
-export declare const DEFAULT_VERSION: "20241025.db973a8e8032";
+export declare const DEFAULT_VERSION: "20250821.4ee6689bf7ec";
 export declare const DEFAULT_NETWORK = NetworkType.Testnet;
 export interface CKBFSScriptConfig {
     codeHash: string;

package/dist/utils/constants.js

@@ -14,6 +14,7 @@ var NetworkType;
 exports.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
 };
 // CKBFS Type Script Constants
 exports.CKBFS_CODE_HASH = {
@@ -23,6 +24,7 @@ exports.CKBFS_CODE_HASH = {
     [NetworkType.Testnet]: {
         [exports.ProtocolVersion.V1]: "0xe8905ad29a02cf8befa9c258f4f941773839a618d75a64afc22059de9413f712",
         [exports.ProtocolVersion.V2]: "0x31e6376287d223b8c0410d562fb422f04d1d617b2947596a14c3d2efb7218d3a",
+        [exports.ProtocolVersion.V3]: "0xb5d13ffe0547c78021c01fe24dce2e959a1ed8edbca3cb93dd2e9f57fb56d695",
     },
 };
 exports.CKBFS_TYPE_ID = {
@@ -32,6 +34,7 @@ exports.CKBFS_TYPE_ID = {
     [NetworkType.Testnet]: {
         [exports.ProtocolVersion.V1]: "0x88ef4d436af35684a27edda0d44dd8771318330285f90f02d13606e095aea86f",
         [exports.ProtocolVersion.V2]: "0x7c6dcab8268201f064dc8676b5eafa60ca2569e5c6209dcbab0eb64a9cb3aaa3",
+        [exports.ProtocolVersion.V3]: "0xaebf5a7b541da9603c2066a9768d3d18fea2e7f3c1943821611545155fecc671",
     },
 };
 // Adler32 Hasher Constants
@@ -42,6 +45,7 @@ exports.ADLER32_CODE_HASH = {
     [NetworkType.Testnet]: {
         [exports.ProtocolVersion.V1]: "0x8af42cd329cf1bcffb4c73b48252e99cb32346fdbc1cdaa5ae1d000232d47e84",
         [exports.ProtocolVersion.V2]: "0x2138683f76944437c0c643664120d620bdb5858dd6c9d1d156805e279c2c536f",
+        [exports.ProtocolVersion.V3]: "0xbd944c8c5aa127270b591d50ab899c9a2a3e4429300db4ea3d7523aa592c1db1",
     },
 };
 exports.ADLER32_TYPE_ID = {
@@ -51,6 +55,7 @@ exports.ADLER32_TYPE_ID = {
     [NetworkType.Testnet]: {
         [exports.ProtocolVersion.V1]: "0xccf29a0d8e860044a3d2f6a6e709f6572f77e4fe245fadd212fc342337048d60",
         [exports.ProtocolVersion.V2]: "0x5f73f128be76e397f5a3b56c94ca16883a8ee91b498bc0ee80473818318c05ac",
+        [exports.ProtocolVersion.V3]: "0x552e2a5e679f45bca7834b03a1f8613f2a910b64a7bafb51986cfc6f1b6cb31c",
     },
 };
 // Dep Group Transaction Constants
@@ -61,6 +66,7 @@ exports.DEP_GROUP_TX_HASH = {
     [NetworkType.Testnet]: {
         [exports.ProtocolVersion.V1]: "0xc8fd44aba36f0c4b37536b6c7ea3b88df65fa97e02f77cd33b9bf20bf241a09b",
         [exports.ProtocolVersion.V2]: "0x469af0d961dcaaedd872968a9388b546717a6ccfa47b3165b3f9c981e9d66aaa",
+        [exports.ProtocolVersion.V3]: "0x47cfa8d554cccffe7796f93b58437269de1f98f029d0a52b6b146381f3e95e61",
     },
 };
 // Deploy Transaction Constants
@@ -80,10 +86,14 @@ exports.DEPLOY_TX_HASH = {
             ckbfs: "0x2c8c9ad3134743368b5a79977648f96c5bd0aba187021a72fb624301064d3616",
             adler32: "0x2c8c9ad3134743368b5a79977648f96c5bd0aba187021a72fb624301064d3616",
         },
+        [exports.ProtocolVersion.V3]: {
+            ckbfs: "0x1488b592b0946589730c906c6d9a46fb82c1181156fc1a4251adce14002a9cfb",
+            adler32: "0x8d6bd7ea704f9b19af5b83b81544c34982515a825e6185d88faf47583a542671",
+        },
     },
 };
-// Default values - V2 is now the default
-exports.DEFAULT_VERSION = exports.ProtocolVersion.V2;
+// Default values - V3 is now the default
+exports.DEFAULT_VERSION = exports.ProtocolVersion.V3;
 exports.DEFAULT_NETWORK = NetworkType.Testnet;
 /**
  * Get CKBFS script configuration for a specific network and version

package/dist/utils/file.d.ts

@@ -242,3 +242,47 @@ export declare function decodeFileFromChainByTypeId(client: any, typeId: string,
     size: number;
     backLinks: any[];
 } | 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 declare function getFileContentFromChainV3(client: any, outPoint: {
+    txHash: string;
+    index: number;
+}, ckbfsData: any): Promise<Uint8Array>;
+/**
+ * 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 declare 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>;
+/**
+ * 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 declare function saveFileFromChainByIdentifierV3(client: any, identifier: string, outputPath?: string, options?: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+}): Promise<string | null>;

package/dist/utils/file.js

@@ -58,8 +58,13 @@ exports.saveFileFromChainByIdentifier = saveFileFromChainByIdentifier;
 exports.saveFileFromChainByTypeId = saveFileFromChainByTypeId;
 exports.decodeFileFromChainByIdentifier = decodeFileFromChainByIdentifier;
 exports.decodeFileFromChainByTypeId = decodeFileFromChainByTypeId;
+exports.getFileContentFromChainV3 = getFileContentFromChainV3;
+exports.getFileContentFromChainByIdentifierV3 = getFileContentFromChainByIdentifierV3;
+exports.saveFileFromChainByIdentifierV3 = saveFileFromChainByIdentifierV3;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const constants_1 = require("./constants");
+const witness_1 = require("./witness");
 /**
  * Utility functions for file operations
  */
@@ -458,7 +463,7 @@ function parseIdentifier(identifier) {
  * @returns Promise resolving to the found cell and transaction info, or null if not found
  */
 async function resolveCKBFSCell(client, identifier, options = {}) {
-    const { network = "testnet", version = "20241025.db973a8e8032", useTypeID = false, } = options;
+    const { network = "testnet", version = constants_1.ProtocolVersion.V3, useTypeID = false, } = options;
     const parsedId = parseIdentifier(identifier);
     try {
         if (parsedId.type === IdentifierType.TypeID && parsedId.typeId) {
@@ -529,15 +534,27 @@ async function resolveCKBFSCell(client, identifier, options = {}) {
  * @param useTypeID Whether to use type ID instead of code hash for script matching
  * @returns Promise resolving to the found cell and transaction info, or null if not found
  */
-async function findCKBFSCellByTypeId(client, typeId, network = "testnet", version = "20241025.db973a8e8032", useTypeID = false) {
+async function findCKBFSCellByTypeId(client, typeId, network = "testnet", version = constants_1.ProtocolVersion.V3, useTypeID = false) {
     try {
         // Import constants dynamically to avoid circular dependencies
         const { getCKBFSScriptConfig, NetworkType, ProtocolVersion } = await Promise.resolve().then(() => __importStar(require("./constants")));
         // 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;
+        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, useTypeID);
         // Create the script to search for
         const script = {
@@ -578,7 +595,7 @@ async function findCKBFSCellByTypeId(client, typeId, network = "testnet", versio
  * @returns Promise resolving to the complete file content and metadata
  */
 async function getFileContentFromChainByIdentifier(client, identifier, options = {}) {
-    const { network = "testnet", version = "20241025.db973a8e8032", useTypeID = false, } = options;
+    const { network = "testnet", version = constants_1.ProtocolVersion.V3, useTypeID = false, } = options;
     try {
         // Resolve the CKBFS cell using any supported identifier format
         const cellInfo = await resolveCKBFSCell(client, identifier, {
@@ -608,26 +625,44 @@ async function getFileContentFromChainByIdentifier(client, identifier, options =
         const rawData = outputData.startsWith("0x")
             ? 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;
         let protocolVersion = version;
         try {
-            ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+            // 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 (error) {
+        catch (v3Error) {
             try {
-                ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
-                protocolVersion = "20240906.ce6724722cf6";
+                ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+                protocolVersion = ProtocolVersion.V2;
             }
-            catch (v1Error) {
-                throw new Error(`Failed to unpack CKBFS data with both versions: V2(${error}), V1(${v1Error})`);
+            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})`);
+                }
             }
         }
         console.log(`Found CKBFS file: ${ckbfsData.filename}`);
         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;
+        if (protocolVersion === ProtocolVersion.V3) {
+            content = await getFileContentFromChainV3(client, outPoint, ckbfsData);
+        }
+        else {
+            content = await getFileContentFromChain(client, outPoint, ckbfsData);
+        }
         return {
             content,
             filename: ckbfsData.filename,
@@ -713,7 +748,7 @@ async function saveFileFromChainByTypeId(client, typeId, outputPath, options = {
  * @returns Promise resolving to the decoded file content and metadata, or null if not found
  */
 async function decodeFileFromChainByIdentifier(client, identifier, options = {}) {
-    const { network = "testnet", version = "20241025.db973a8e8032", useTypeID = false, } = options;
+    const { network = "testnet", version = constants_1.ProtocolVersion.V3, useTypeID = false, } = options;
     try {
         // Resolve the CKBFS cell using any supported identifier format
         const cellInfo = await resolveCKBFSCell(client, identifier, {
@@ -741,19 +776,31 @@ async function decodeFileFromChainByIdentifier(client, identifier, options = {})
         const rawData = outputData.startsWith("0x")
             ? 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;
         let protocolVersion = version;
         try {
-            ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+            // 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 (error) {
+        catch (v3Error) {
             try {
-                ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
-                protocolVersion = "20240906.ce6724722cf6";
+                ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+                protocolVersion = ProtocolVersion.V2;
             }
-            catch (v1Error) {
-                throw new Error(`Failed to unpack CKBFS data with both versions: V2(${error}), V1(${v1Error})`);
+            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})`);
+                }
             }
         }
         console.log(`Found CKBFS file: ${ckbfsData.filename}`);
@@ -762,13 +809,25 @@ async function decodeFileFromChainByIdentifier(client, identifier, options = {})
         // Get witness indexes from CKBFS data
         const indexes = 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;
+        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,
             filename: ckbfsData.filename,
@@ -799,3 +858,217 @@ async function decodeFileFromChainByTypeId(client, typeId, options = {}) {
     }
     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
+ */
+async function getFileContentFromChainV3(client, outPoint, ckbfsData) {
+    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 = [];
+    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 ((0, witness_1.isCKBFSV3Witness)(witness)) {
+            const witnessData = (0, witness_1.extractCKBFSV3WitnessContent)(witness, true);
+            // Collect content from this transaction (head + continuation witnesses)
+            const txContentPieces = [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 = (0, witness_1.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 Promise.resolve().then(() => __importStar(require("@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 = 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 Promise.resolve().then(() => __importStar(require("@ckb-ccc/core")));
+                        const { CKBFSData } = await Promise.resolve().then(() => __importStar(require("./molecule")));
+                        const { ProtocolVersion } = await Promise.resolve().then(() => __importStar(require("./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 = [];
+    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
+ */
+async function getFileContentFromChainByIdentifierV3(client, identifier, options = {}) {
+    const { network = "testnet", version = constants_1.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 Promise.resolve().then(() => __importStar(require("@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 Promise.resolve().then(() => __importStar(require("@ckb-ccc/core")));
+        const { CKBFSData } = await Promise.resolve().then(() => __importStar(require("./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, constants_1.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
+ */
+async function saveFileFromChainByIdentifierV3(client, identifier, outputPath, options = {}) {
+    try {
+        // Get file content by identifier using v3 method
+        const fileData = await getFileContentFromChainByIdentifierV3(client, identifier, { ...options, version: constants_1.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_1.default.dirname(filePath);
+        if (!fs_1.default.existsSync(directory)) {
+            fs_1.default.mkdirSync(directory, { recursive: true });
+        }
+        // Write file
+        fs_1.default.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;
+    }
+}