@ckbfs/api 1.1.0 → 1.2.1

package/README.md

@@ -108,12 +108,18 @@ npm run example:publish
 npm run example:append -- --txhash=0x123456...
 # OR
 PUBLISH_TX_HASH=0x123456... npm run example:append
+
+# Run the retrieve file example (download a file from blockchain)
+npm run example:retrieve -- --txhash=0x123456... --output=./downloaded-file.txt
+# OR
+CKBFS_TX_HASH=0x123456... npm run example:retrieve
 ```
 
 ### Example Files
 
 - `examples/publish.ts` - Shows how to publish a file to CKBFS
 - `examples/append.ts` - Shows how to append to a previously published file
+- `examples/retrieve.ts` - Shows how to retrieve a complete file from the blockchain
 
 To run the examples, first set your CKB private key:
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Script, Signer, Transaction } from "@ckb-ccc/core";
 import { calculateChecksum, verifyChecksum, updateChecksum, verifyWitnessChecksum } from './utils/checksum';
 import { createCKBFSCell, createPublishTransaction, createAppendTransaction, publishCKBFS, appendCKBFS, CKBFSCellOptions, PublishOptions, AppendOptions } from './utils/transaction';
-import { readFile, readFileAsText, readFileAsUint8Array, writeFile, getContentType, splitFileIntoChunks, combineChunksToFile } from './utils/file';
+import { readFile, readFileAsText, readFileAsUint8Array, writeFile, getContentType, splitFileIntoChunks, combineChunksToFile, getFileContentFromChain, saveFileFromChain } from './utils/file';
 import { createCKBFSWitness, createTextCKBFSWitness, extractCKBFSWitnessContent, isCKBFSWitness, createChunkedCKBFSWitnesses } from './utils/witness';
 import { CKBFSData, BackLinkV1, BackLinkV2, CKBFSDataType, BackLinkType, CKBFS_HEADER, CKBFS_HEADER_STRING } from './utils/molecule';
 import { NetworkType, ProtocolVersion, DEFAULT_NETWORK, DEFAULT_VERSION, CKBFS_CODE_HASH, CKBFS_TYPE_ID, ADLER32_CODE_HASH, ADLER32_TYPE_ID, DEP_GROUP_TX_HASH, DEPLOY_TX_HASH, getCKBFSScriptConfig, CKBFSScriptConfig } from './utils/constants';
@@ -88,4 +88,4 @@ export declare class CKBFS {
      */
     createAppendTransaction(filePath: string, ckbfsCell: AppendOptions['ckbfsCell'], options?: Omit<FileOptions, 'contentType' | 'filename'>): Promise<Transaction>;
 }
-export { calculateChecksum, verifyChecksum, updateChecksum, verifyWitnessChecksum, createCKBFSCell, createPublishTransaction, createAppendTransaction, publishCKBFS, appendCKBFS, readFile, readFileAsText, readFileAsUint8Array, writeFile, getContentType, splitFileIntoChunks, combineChunksToFile, createCKBFSWitness, createTextCKBFSWitness, extractCKBFSWitnessContent, isCKBFSWitness, createChunkedCKBFSWitnesses, CKBFSData, BackLinkV1, BackLinkV2, CKBFSDataType, BackLinkType, CKBFSCellOptions, PublishOptions, AppendOptions, CKBFS_HEADER, CKBFS_HEADER_STRING, NetworkType, ProtocolVersion, DEFAULT_NETWORK, DEFAULT_VERSION, CKBFS_CODE_HASH, CKBFS_TYPE_ID, ADLER32_CODE_HASH, ADLER32_TYPE_ID, DEP_GROUP_TX_HASH, DEPLOY_TX_HASH, getCKBFSScriptConfig, CKBFSScriptConfig };
+export { calculateChecksum, verifyChecksum, updateChecksum, verifyWitnessChecksum, createCKBFSCell, createPublishTransaction, createAppendTransaction, publishCKBFS, appendCKBFS, readFile, readFileAsText, readFileAsUint8Array, writeFile, getContentType, splitFileIntoChunks, combineChunksToFile, getFileContentFromChain, saveFileFromChain, createCKBFSWitness, createTextCKBFSWitness, extractCKBFSWitnessContent, isCKBFSWitness, createChunkedCKBFSWitnesses, CKBFSData, BackLinkV1, BackLinkV2, CKBFSDataType, BackLinkType, CKBFSCellOptions, PublishOptions, AppendOptions, CKBFS_HEADER, CKBFS_HEADER_STRING, NetworkType, ProtocolVersion, DEFAULT_NETWORK, DEFAULT_VERSION, CKBFS_CODE_HASH, CKBFS_TYPE_ID, ADLER32_CODE_HASH, ADLER32_TYPE_ID, DEP_GROUP_TX_HASH, DEPLOY_TX_HASH, getCKBFSScriptConfig, CKBFSScriptConfig };

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCKBFSScriptConfig = exports.DEPLOY_TX_HASH = exports.DEP_GROUP_TX_HASH = exports.ADLER32_TYPE_ID = exports.ADLER32_CODE_HASH = exports.CKBFS_TYPE_ID = exports.CKBFS_CODE_HASH = exports.DEFAULT_VERSION = exports.DEFAULT_NETWORK = exports.ProtocolVersion = exports.NetworkType = exports.CKBFS_HEADER_STRING = exports.CKBFS_HEADER = exports.BackLinkV2 = exports.BackLinkV1 = exports.CKBFSData = exports.createChunkedCKBFSWitnesses = exports.isCKBFSWitness = exports.extractCKBFSWitnessContent = exports.createTextCKBFSWitness = exports.createCKBFSWitness = exports.combineChunksToFile = exports.splitFileIntoChunks = exports.getContentType = exports.writeFile = exports.readFileAsUint8Array = exports.readFileAsText = exports.readFile = exports.appendCKBFS = exports.publishCKBFS = exports.createAppendTransaction = exports.createPublishTransaction = exports.createCKBFSCell = exports.verifyWitnessChecksum = exports.updateChecksum = exports.verifyChecksum = exports.calculateChecksum = exports.CKBFS = void 0;
+exports.getCKBFSScriptConfig = exports.DEPLOY_TX_HASH = exports.DEP_GROUP_TX_HASH = exports.ADLER32_TYPE_ID = exports.ADLER32_CODE_HASH = exports.CKBFS_TYPE_ID = exports.CKBFS_CODE_HASH = exports.DEFAULT_VERSION = exports.DEFAULT_NETWORK = exports.ProtocolVersion = exports.NetworkType = exports.CKBFS_HEADER_STRING = exports.CKBFS_HEADER = exports.BackLinkV2 = exports.BackLinkV1 = exports.CKBFSData = exports.createChunkedCKBFSWitnesses = exports.isCKBFSWitness = exports.extractCKBFSWitnessContent = exports.createTextCKBFSWitness = exports.createCKBFSWitness = exports.saveFileFromChain = exports.getFileContentFromChain = exports.combineChunksToFile = exports.splitFileIntoChunks = exports.getContentType = exports.writeFile = exports.readFileAsUint8Array = exports.readFileAsText = exports.readFile = exports.appendCKBFS = exports.publishCKBFS = exports.createAppendTransaction = exports.createPublishTransaction = exports.createCKBFSCell = exports.verifyWitnessChecksum = exports.updateChecksum = exports.verifyChecksum = exports.calculateChecksum = exports.CKBFS = void 0;
 const core_1 = require("@ckb-ccc/core");
 const checksum_1 = require("./utils/checksum");
 Object.defineProperty(exports, "calculateChecksum", { enumerable: true, get: function () { return checksum_1.calculateChecksum; } });
@@ -21,6 +21,8 @@ Object.defineProperty(exports, "writeFile", { enumerable: true, get: function ()
 Object.defineProperty(exports, "getContentType", { enumerable: true, get: function () { return file_1.getContentType; } });
 Object.defineProperty(exports, "splitFileIntoChunks", { enumerable: true, get: function () { return file_1.splitFileIntoChunks; } });
 Object.defineProperty(exports, "combineChunksToFile", { enumerable: true, get: function () { return file_1.combineChunksToFile; } });
+Object.defineProperty(exports, "getFileContentFromChain", { enumerable: true, get: function () { return file_1.getFileContentFromChain; } });
+Object.defineProperty(exports, "saveFileFromChain", { enumerable: true, get: function () { return file_1.saveFileFromChain; } });
 const witness_1 = require("./utils/witness");
 Object.defineProperty(exports, "createCKBFSWitness", { enumerable: true, get: function () { return witness_1.createCKBFSWitness; } });
 Object.defineProperty(exports, "createTextCKBFSWitness", { enumerable: true, get: function () { return witness_1.createTextCKBFSWitness; } });

package/dist/utils/checksum.d.ts

@@ -8,7 +8,7 @@
  */
 export declare function calculateChecksum(data: Uint8Array): Promise<number>;
 /**
- * Updates an existing checksum with new data
+ * Updates an existing checksum with new data using proper rolling Adler-32 calculation
  * @param previousChecksum The existing checksum to update
  * @param newData The new data to add to the checksum
  * @returns Promise resolving to the updated checksum as a number

package/dist/utils/checksum.js

@@ -19,21 +19,38 @@ async function calculateChecksum(data) {
     return checksumBuffer.readUInt32BE();
 }
 /**
- * Updates an existing checksum with new data
+ * Updates an existing checksum with new data using proper rolling Adler-32 calculation
  * @param previousChecksum The existing checksum to update
  * @param newData The new data to add to the checksum
  * @returns Promise resolving to the updated checksum as a number
  */
 async function updateChecksum(previousChecksum, newData) {
-    // In a real implementation, this would require the actual Adler32 state recovery
-    // For now, we're simply concatenating the previousChecksum as a hex string with the new data
-    // and calculating a new checksum
-    const checksumBytes = Buffer.alloc(4);
-    checksumBytes.writeUInt32BE(previousChecksum);
-    // Concatenate the previous checksum bytes with the new data
-    const combinedData = Buffer.concat([checksumBytes, Buffer.from(newData)]);
-    // Calculate the new checksum
-    return calculateChecksum(combinedData);
+    // Extract a and b values from the previous checksum
+    // In Adler-32, the checksum is composed of two 16-bit integers: a and b
+    // The final checksum is (b << 16) | a
+    const a = previousChecksum & 0xFFFF;
+    const b = (previousChecksum >>> 16) & 0xFFFF;
+    // Use the adler-32 package to calculate a proper rolling checksum
+    // The package doesn't have a "resume" function, so we need to work with the underlying algorithm
+    // Initialize with existing a and b values
+    let adlerA = a;
+    let adlerB = b;
+    const MOD_ADLER = 65521; // Adler-32 modulo value
+    // Process each byte of the new data
+    for (let i = 0; i < newData.length; i++) {
+        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);
+    console.log(`Updated checksum from ${previousChecksum} to ${updatedChecksum} for appended content`);
+    return updatedChecksum;
 }
 /**
  * Verifies if a given checksum matches the expected checksum for the data

package/dist/utils/file.d.ts

@@ -44,3 +44,22 @@ export declare function splitFileIntoChunks(filePath: string, chunkSize: number)
  * @param outputPath The path to write the combined file to
  */
 export declare function combineChunksToFile(chunks: Uint8Array[], outputPath: string): void;
+/**
+ * Retrieves complete file content from the blockchain by following backlinks
+ * @param client The CKB client to use for blockchain queries
+ * @param outPoint The output point of the latest CKBFS cell
+ * @param ckbfsData The data from the latest CKBFS cell
+ * @returns Promise resolving to the complete file content
+ */
+export declare function getFileContentFromChain(client: any, outPoint: {
+    txHash: string;
+    index: number;
+}, ckbfsData: any): Promise<Uint8Array>;
+/**
+ * Saves file content retrieved from blockchain to disk
+ * @param content The file content to save
+ * @param ckbfsData The CKBFS cell data containing file metadata
+ * @param outputPath Optional path to save the file (defaults to filename in current directory)
+ * @returns The path where the file was saved
+ */
+export declare function saveFileFromChain(content: Uint8Array, ckbfsData: any, outputPath?: string): string;

package/dist/utils/file.js

@@ -10,6 +10,8 @@ exports.writeFile = writeFile;
 exports.getContentType = getContentType;
 exports.splitFileIntoChunks = splitFileIntoChunks;
 exports.combineChunksToFile = combineChunksToFile;
+exports.getFileContentFromChain = getFileContentFromChain;
+exports.saveFileFromChain = saveFileFromChain;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 /**
@@ -106,3 +108,126 @@ function combineChunksToFile(chunks, outputPath) {
     const combinedBuffer = Buffer.concat(chunks.map(chunk => Buffer.from(chunk)));
     writeFile(outputPath, combinedBuffer);
 }
+/**
+ * Utility function to safely decode buffer to string
+ * @param buffer The buffer to decode
+ * @returns Decoded string or placeholder on error
+ */
+function safelyDecode(buffer) {
+    if (!buffer)
+        return '[Unknown]';
+    try {
+        if (buffer instanceof Uint8Array) {
+            return new TextDecoder().decode(buffer);
+        }
+        else if (typeof buffer === 'string') {
+            return buffer;
+        }
+        else {
+            return `[Buffer: ${buffer.toString()}]`;
+        }
+    }
+    catch (e) {
+        return '[Decode Error]';
+    }
+}
+/**
+ * Retrieves complete file content from the blockchain by following backlinks
+ * @param client The CKB client to use for blockchain queries
+ * @param outPoint The output point of the latest CKBFS cell
+ * @param ckbfsData The data from the latest CKBFS cell
+ * @returns Promise resolving to the complete file content
+ */
+async function getFileContentFromChain(client, outPoint, ckbfsData) {
+    console.log(`Retrieving file: ${safelyDecode(ckbfsData.filename)}`);
+    console.log(`Content type: ${safelyDecode(ckbfsData.contentType)}`);
+    // Prepare to collect all content pieces
+    const contentPieces = [];
+    let currentData = ckbfsData;
+    let currentOutPoint = outPoint;
+    // Process the current transaction first
+    const tx = await client.getTransaction(currentOutPoint.txHash);
+    if (!tx || !tx.transaction) {
+        throw new Error(`Transaction ${currentOutPoint.txHash} not found`);
+    }
+    // Get content from witnesses
+    const indexes = currentData.indexes || (currentData.index !== undefined ? [currentData.index] : []);
+    if (indexes.length > 0) {
+        // Get content from each witness index
+        for (const idx of indexes) {
+            if (idx >= tx.transaction.witnesses.length) {
+                console.warn(`Witness index ${idx} out of range`);
+                continue;
+            }
+            const witnessHex = tx.transaction.witnesses[idx];
+            const witness = Buffer.from(witnessHex.slice(2), 'hex'); // Remove 0x prefix
+            // Extract content (skip CKBFS header + version byte)
+            if (witness.length >= 6 && witness.slice(0, 5).toString() === 'CKBFS') {
+                const content = witness.slice(6);
+                contentPieces.unshift(content); // Add to beginning of array (we're going backwards)
+            }
+            else {
+                console.warn(`Witness at index ${idx} is not a valid CKBFS witness`);
+            }
+        }
+    }
+    // Follow backlinks recursively
+    if (currentData.backLinks && currentData.backLinks.length > 0) {
+        // Process each backlink, from most recent to oldest
+        for (let i = currentData.backLinks.length - 1; i >= 0; i--) {
+            const backlink = currentData.backLinks[i];
+            // Get the transaction for this backlink
+            const backTx = await client.getTransaction(backlink.txHash);
+            if (!backTx || !backTx.transaction) {
+                console.warn(`Backlink transaction ${backlink.txHash} not found`);
+                continue;
+            }
+            // Get content from backlink witnesses
+            const backIndexes = backlink.indexes || (backlink.index !== undefined ? [backlink.index] : []);
+            if (backIndexes.length > 0) {
+                // Get content from each witness index
+                for (const idx of backIndexes) {
+                    if (idx >= backTx.transaction.witnesses.length) {
+                        console.warn(`Backlink witness index ${idx} out of range`);
+                        continue;
+                    }
+                    const witnessHex = backTx.transaction.witnesses[idx];
+                    const witness = Buffer.from(witnessHex.slice(2), 'hex'); // Remove 0x prefix
+                    // Extract content (skip CKBFS header + version byte)
+                    if (witness.length >= 6 && witness.slice(0, 5).toString() === 'CKBFS') {
+                        const content = witness.slice(6);
+                        contentPieces.unshift(content); // Add to beginning of array (we're going backwards)
+                    }
+                    else {
+                        console.warn(`Backlink witness at index ${idx} is not a valid CKBFS witness`);
+                    }
+                }
+            }
+        }
+    }
+    // Combine all content pieces
+    return Buffer.concat(contentPieces);
+}
+/**
+ * Saves file content retrieved from blockchain to disk
+ * @param content The file content to save
+ * @param ckbfsData The CKBFS cell data containing file metadata
+ * @param outputPath Optional path to save the file (defaults to filename in current directory)
+ * @returns The path where the file was saved
+ */
+function saveFileFromChain(content, ckbfsData, outputPath) {
+    // Get filename from CKBFS data
+    const filename = safelyDecode(ckbfsData.filename);
+    // Determine output path
+    const filePath = outputPath || 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, content);
+    console.log(`File saved to: ${filePath}`);
+    console.log(`Size: ${content.length} bytes`);
+    return filePath;
+}

package/dist/utils/molecule.d.ts

@@ -4,34 +4,34 @@ import { molecule, number } from "@ckb-lumos/codec";
  */
 export declare const Indexes: molecule.ArrayLayoutCodec<import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>>;
 export declare const BackLinkV1: molecule.ObjectLayoutCodec<{
-    txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     index: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
     checksum: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
+    txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
 }>;
 export declare const BackLinkV2: molecule.ObjectLayoutCodec<{
-    txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     indexes: molecule.ArrayLayoutCodec<import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>>;
     checksum: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
+    txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
 }>;
 export declare const BackLinksV1: molecule.ArrayLayoutCodec<molecule.ObjectLayoutCodec<{
-    txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     index: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
     checksum: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
+    txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
 }>>;
 export declare const BackLinksV2: molecule.ArrayLayoutCodec<molecule.ObjectLayoutCodec<{
-    txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     indexes: molecule.ArrayLayoutCodec<import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>>;
     checksum: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
+    txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
 }>>;
 export declare const CKBFSDataV1: molecule.ObjectLayoutCodec<{
-    index: molecule.ArrayLayoutCodec<import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>>;
+    index: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
     checksum: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
     contentType: import("@ckb-lumos/codec/lib/base").BytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     filename: import("@ckb-lumos/codec/lib/base").BytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     backLinks: molecule.ArrayLayoutCodec<molecule.ObjectLayoutCodec<{
-        txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
         index: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
         checksum: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
+        txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     }>>;
 }>;
 export declare const CKBFSDataV2: molecule.ObjectLayoutCodec<{
@@ -40,33 +40,33 @@ export declare const CKBFSDataV2: molecule.ObjectLayoutCodec<{
     contentType: import("@ckb-lumos/codec/lib/base").BytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     filename: import("@ckb-lumos/codec/lib/base").BytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     backLinks: molecule.ArrayLayoutCodec<molecule.ObjectLayoutCodec<{
-        txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
         indexes: molecule.ArrayLayoutCodec<import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>>;
         checksum: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<number, number.BIish>;
+        txHash: import("@ckb-lumos/codec/lib/base").FixedBytesCodec<string, import("@ckb-lumos/codec").BytesLike>;
     }>>;
 }>;
 export type BackLinkTypeV1 = {
-    txHash: string;
     index: number;
     checksum: number;
+    txHash: string;
 };
 export type BackLinkTypeV2 = {
-    txHash: string;
     indexes: number[];
     checksum: number;
+    txHash: string;
 };
 export type BackLinkType = {
-    txHash: string;
     index?: number;
     indexes?: number[];
     checksum: number;
+    txHash: string;
 };
 export type CKBFSDataType = {
-    index?: number[] | number;
+    index?: number;
     indexes?: number[];
     checksum: number;
-    contentType: Uint8Array;
-    filename: Uint8Array;
+    contentType: string;
+    filename: string;
     backLinks: BackLinkType[];
 };
 export declare const CKBFSData: {

package/dist/utils/molecule.js

@@ -4,36 +4,36 @@ exports.CKBFS_HEADER_STRING = exports.CKBFS_HEADER = exports.CKBFSData = exports
 const codec_1 = require("@ckb-lumos/codec");
 const base_1 = require("@ckb-lumos/base");
 const constants_1 = require("./constants");
+const core_1 = require("@ckb-ccc/core");
 /**
  * Molecule definitions for CKBFS data structures.
  */
-// Define the Indexes vector
+// Define the Indexes vector for V2
 exports.Indexes = codec_1.molecule.vector(codec_1.number.Uint32);
-// Define the BackLink table structure for V1
+// V1: BackLink has index as Uint32, and fields are ordered differently
 exports.BackLinkV1 = codec_1.molecule.table({
-    txHash: base_1.blockchain.Byte32,
     index: codec_1.number.Uint32,
     checksum: codec_1.number.Uint32,
-}, ["txHash", "index", "checksum"]);
-// Define the BackLink table structure for V2
-exports.BackLinkV2 = codec_1.molecule.table({
     txHash: base_1.blockchain.Byte32,
+}, ["index", "checksum", "txHash"]);
+// V2: BackLink has indexes as vector of Uint32
+exports.BackLinkV2 = codec_1.molecule.table({
     indexes: exports.Indexes,
     checksum: codec_1.number.Uint32,
-}, ["txHash", "indexes", "checksum"]);
-// Define the BackLinks vector for V1
+    txHash: base_1.blockchain.Byte32,
+}, ["indexes", "checksum", "txHash"]);
+// Define the BackLinks vector for V1 and V2
 exports.BackLinksV1 = codec_1.molecule.vector(exports.BackLinkV1);
-// Define the BackLinks vector for V2
 exports.BackLinksV2 = codec_1.molecule.vector(exports.BackLinkV2);
-// Define the CKBFSData table structure for V1
+// V1: CKBFSData has index as optional Uint32
 exports.CKBFSDataV1 = codec_1.molecule.table({
-    index: exports.Indexes,
+    index: codec_1.number.Uint32,
     checksum: codec_1.number.Uint32,
     contentType: base_1.blockchain.Bytes,
     filename: base_1.blockchain.Bytes,
     backLinks: exports.BackLinksV1,
 }, ["index", "checksum", "contentType", "filename", "backLinks"]);
-// Define the CKBFSData table structure for V2
+// V2: CKBFSData has indexes as vector of Uint32
 exports.CKBFSDataV2 = codec_1.molecule.table({
     indexes: exports.Indexes,
     checksum: codec_1.number.Uint32,
@@ -41,20 +41,23 @@ exports.CKBFSDataV2 = codec_1.molecule.table({
     filename: base_1.blockchain.Bytes,
     backLinks: exports.BackLinksV2,
 }, ["indexes", "checksum", "contentType", "filename", "backLinks"]);
-// Helper function to safely get either index or indexes as array
+// Helper function to get indexes array from data
 function getIndexes(data) {
-    if (Array.isArray(data.indexes)) {
+    if (data.indexes)
         return data.indexes;
-    }
-    if (Array.isArray(data.index)) {
-        return data.index;
-    }
-    if (typeof data.index === 'number') {
+    if (typeof data.index === 'number')
         return [data.index];
-    }
     return [];
 }
-// Helper function to safely get either index or indexes from BackLinkType
+// Helper function to get single index from data
+function getIndex(data) {
+    if (typeof data.index === 'number')
+        return data.index;
+    if (data.indexes && data.indexes.length > 0)
+        return data.indexes[0];
+    return 0;
+}
+// Helper function to safely get either index or indexes from BackLinkType for V1
 function getBackLinkIndex(bl) {
     if (typeof bl.index === 'number') {
         return bl.index;
@@ -64,7 +67,7 @@ function getBackLinkIndex(bl) {
     }
     return 0;
 }
-// Helper function to safely get indexes array from BackLinkType
+// Helper function to safely get indexes array from BackLinkType for V2
 function getBackLinkIndexes(bl) {
     if (Array.isArray(bl.indexes)) {
         return bl.indexes;
@@ -78,78 +81,43 @@ function getBackLinkIndexes(bl) {
 exports.CKBFSData = {
     pack: (data, version = constants_1.ProtocolVersion.V2) => {
         if (version === constants_1.ProtocolVersion.V1) {
-            // For V1, we need a single number index
-            let indexValue = [];
-            // Handle the various ways index might be specified
-            if (typeof data.index === 'number') {
-                // Single number
-                indexValue = [data.index];
-            }
-            else if (Array.isArray(data.index) && data.index.length > 0) {
-                // Array of numbers, use as is
-                indexValue = data.index;
-            }
-            else if (Array.isArray(data.indexes) && data.indexes.length > 0) {
-                // Try using indexes field if index is not available
-                indexValue = data.indexes;
-            }
-            // Map backlinks to V1 format - ensure each one has a single index
-            const v1Backlinks = data.backLinks.map(bl => {
-                let singleIndex = 0;
-                if (typeof bl.index === 'number') {
-                    singleIndex = bl.index;
-                }
-                else if (Array.isArray(bl.indexes) && bl.indexes.length > 0) {
-                    singleIndex = bl.indexes[0];
-                }
-                return {
-                    txHash: bl.txHash,
-                    index: singleIndex,
-                    checksum: bl.checksum
-                };
-            });
+            // V1 formatting - uses single index
             return exports.CKBFSDataV1.pack({
-                index: indexValue,
+                index: getIndex(data),
                 checksum: data.checksum,
-                contentType: data.contentType,
-                filename: data.filename,
-                backLinks: v1Backlinks
+                contentType: core_1.ccc.bytesFrom(data.contentType, 'utf8'),
+                filename: core_1.ccc.bytesFrom(data.filename, 'utf8'),
+                backLinks: data.backLinks.map(bl => {
+                    // Ensure txHash is in proper format for molecule encoding
+                    const txHash = typeof bl.txHash === 'string'
+                        ? core_1.ccc.bytesFrom(bl.txHash)
+                        : bl.txHash;
+                    return {
+                        index: getBackLinkIndex(bl),
+                        checksum: bl.checksum,
+                        txHash,
+                    };
+                }),
             });
         }
         else {
-            // V2 format - use indexes as an array
-            let indexesArray = [];
-            // Handle different index specification formats
-            if (Array.isArray(data.indexes) && data.indexes.length > 0) {
-                indexesArray = data.indexes;
-            }
-            else if (Array.isArray(data.index) && data.index.length > 0) {
-                indexesArray = data.index;
-            }
-            else if (typeof data.index === 'number') {
-                indexesArray = [data.index];
-            }
-            // Map backlinks to V2 format - ensure each one has indexes array
-            const v2Backlinks = data.backLinks.map(bl => {
-                let indexesValue = [];
-                if (Array.isArray(bl.indexes) && bl.indexes.length > 0) {
-                    indexesValue = bl.indexes;
-                }
-                else if (typeof bl.index === 'number') {
-                    indexesValue = [bl.index];
-                }
-                return {
-                    txHash: bl.txHash,
-                    indexes: indexesValue,
-                    checksum: bl.checksum
-                };
-            });
+            // V2 formatting - uses indexes array
             return exports.CKBFSDataV2.pack({
-                indexes: indexesArray,
+                indexes: getIndexes(data),
                 checksum: data.checksum,
-                contentType: data.contentType,
-                filename: data.filename,
-                backLinks: v2Backlinks
+                contentType: core_1.ccc.bytesFrom(data.contentType, 'utf8'),
+                filename: core_1.ccc.bytesFrom(data.filename, 'utf8'),
+                backLinks: data.backLinks.map(bl => {
+                    // Ensure txHash is in proper format for molecule encoding
+                    const txHash = typeof bl.txHash === 'string'
+                        ? bl.txHash
+                        : bl.txHash;
+                    return {
+                        indexes: getBackLinkIndexes(bl),
+                        checksum: bl.checksum,
+                        txHash,
+                    };
+                }),
             });
         }
     },
@@ -160,12 +128,12 @@ exports.CKBFSData = {
                 return {
                     index: unpacked.index,
                     checksum: unpacked.checksum,
-                    contentType: new Uint8Array(Buffer.from(unpacked.contentType)),
-                    filename: new Uint8Array(Buffer.from(unpacked.filename)),
+                    contentType: core_1.ccc.bytesTo(unpacked.contentType, 'utf8'),
+                    filename: core_1.ccc.bytesTo(unpacked.filename, 'utf8'),
                     backLinks: unpacked.backLinks.map(bl => ({
-                        txHash: bl.txHash,
                         index: bl.index,
                         checksum: bl.checksum,
+                        txHash: bl.txHash,
                     })),
                 };
             }
@@ -175,12 +143,12 @@ exports.CKBFSData = {
                 return {
                     indexes: unpacked.indexes,
                     checksum: unpacked.checksum,
-                    contentType: new Uint8Array(Buffer.from(unpacked.contentType)),
-                    filename: new Uint8Array(Buffer.from(unpacked.filename)),
+                    contentType: core_1.ccc.bytesTo(unpacked.contentType, 'utf8'),
+                    filename: core_1.ccc.bytesTo(unpacked.filename, 'utf8'),
                     backLinks: unpacked.backLinks.map(bl => ({
-                        txHash: bl.txHash,
                         indexes: bl.indexes,
                         checksum: bl.checksum,
+                        txHash: bl.txHash,
                     })),
                 };
             }

package/dist/utils/transaction.js

@@ -51,7 +51,9 @@ async function createPublishTransaction(signer, options) {
     const textEncoder = new TextEncoder();
     const combinedContent = Buffer.concat(contentChunks);
     const checksum = await (0, checksum_1.calculateChecksum)(combinedContent);
-    // Create CKBFS witnesses
+    // Create CKBFS witnesses - each chunk already includes the CKBFS header
+    // Pass 0 as version byte - this is the protocol version byte in the witness header
+    // not to be confused with the Protocol Version (V1 vs V2)
     const ckbfsWitnesses = (0, witness_1.createChunkedCKBFSWitnesses)(contentChunks);
     // Calculate the actual witness indices where our content is placed
     // Index 0 is reserved for the secp256k1 witness for signing
@@ -61,24 +63,24 @@ async function createPublishTransaction(signer, options) {
     // Create CKBFS cell output data based on version
     let outputData;
     if (version === constants_1.ProtocolVersion.V1) {
-        // V1 format: Single index field
+        // V1 format: Single index field (a single number, not an array)
         // For V1, use the first index where content is placed
         outputData = molecule_1.CKBFSData.pack({
-            index: [contentStartIndex],
+            index: contentStartIndex,
             checksum,
-            contentType: textEncoder.encode(contentType),
-            filename: textEncoder.encode(filename),
+            contentType: contentType,
+            filename: filename,
             backLinks: [],
         }, version);
     }
     else {
-        // V2 format: Multiple indexes
+        // V2 format: Multiple indexes (array of numbers)
         // For V2, use all the indices where content is placed
         outputData = molecule_1.CKBFSData.pack({
             indexes: witnessIndices,
             checksum,
-            contentType: textEncoder.encode(contentType),
-            filename: textEncoder.encode(filename),
+            contentType,
+            filename,
             backLinks: [],
         }, version);
     }
@@ -156,115 +158,84 @@ async function createAppendTransaction(signer, options) {
     const { outPoint, data, type, lock, capacity } = ckbfsCell;
     // Get CKBFS script config early to use version info
     const config = (0, constants_1.getCKBFSScriptConfig)(network, version);
-    // Create CKBFS witnesses - this may vary between V1 and V2
-    // Pass the version to ensure the correct witness format
-    const ckbfsWitnesses = (0, witness_1.createChunkedCKBFSWitnesses)(contentChunks, 0, version);
-    // Combine the new content chunks
+    // Create CKBFS witnesses - each chunk already includes the CKBFS header
+    // Pass 0 as version byte - this is the protocol version byte in the witness header
+    // not to be confused with the Protocol Version (V1 vs V2)
+    const ckbfsWitnesses = (0, witness_1.createChunkedCKBFSWitnesses)(contentChunks);
+    // Combine the new content chunks for checksum calculation
     const combinedContent = Buffer.concat(contentChunks);
-    // Instead of calculating a new checksum from scratch, update the existing checksum
-    // with the new content - this is more efficient and matches the Adler32 algorithm's
-    // cumulative nature
+    // Update the existing checksum with the new content - this matches Adler32's
+    // cumulative nature as required by Rule 11 in the RFC
     const contentChecksum = await (0, checksum_1.updateChecksum)(data.checksum, combinedContent);
     console.log(`Updated checksum from ${data.checksum} to ${contentChecksum} for appended content`);
+    // Calculate the actual witness indices where our content is placed
+    // Index 0 is reserved for the secp256k1 witness for signing
+    // So our CKBFS data starts at index 1
+    const contentStartIndex = 1;
+    const witnessIndices = Array.from({ length: contentChunks.length }, (_, i) => contentStartIndex + i);
     // Create backlink for the current state based on version
     let newBackLink;
     if (version === constants_1.ProtocolVersion.V1) {
         // V1 format: Use index field (single number)
-        // In V1, BackLink.index should be a single number (not an array)
-        let singleIndex = 0;
-        if (data.index) {
-            if (Array.isArray(data.index) && data.index.length > 0) {
-                singleIndex = data.index[0];
-            }
-            else if (typeof data.index === 'number') {
-                singleIndex = data.index;
-            }
-        }
         newBackLink = {
-            txHash: outPoint.txHash,
-            index: singleIndex,
+            // In V1, field order is index, checksum, txHash
+            // and index is a single number value, not an array
+            index: data.index || (data.indexes && data.indexes.length > 0 ? data.indexes[0] : 0),
             checksum: data.checksum,
+            txHash: outPoint.txHash,
         };
     }
     else {
         // V2 format: Use indexes field (array of numbers)
-        const indices = [];
-        if (data.indexes && Array.isArray(data.indexes)) {
-            indices.push(...data.indexes);
-        }
-        else if (data.index) {
-            if (Array.isArray(data.index)) {
-                indices.push(...data.index);
-            }
-            else if (typeof data.index === 'number') {
-                indices.push(data.index);
-            }
-        }
         newBackLink = {
-            txHash: outPoint.txHash,
-            indexes: indices,
+            // In V2, field order is indexes, checksum, txHash
+            // and indexes is an array of numbers
+            indexes: data.indexes || (data.index ? [data.index] : []),
             checksum: data.checksum,
+            txHash: outPoint.txHash,
         };
     }
-    // Update backlinks - preserve the existing backlinks
+    // Update backlinks - add the new one to the existing backlinks array
     const backLinks = [...(data.backLinks || []), newBackLink];
-    // Calculate the actual witness indices where our content is placed
-    // Index 0 is reserved for the secp256k1 witness for signing
-    // So our CKBFS data starts at index 1
-    const contentStartIndex = 1;
-    const witnessIndices = Array.from({ length: contentChunks.length }, (_, i) => contentStartIndex + i);
-    // Define indices based on version
+    // Define output data based on version
     let outputData;
     if (version === constants_1.ProtocolVersion.V1) {
-        // In V1, index should be a single number (not an array)
-        // Rule 13 for V1: Output CKBFS Cell's index cannot be null
+        // In V1, index is a single number, not an array
+        // The first witness index is used (V1 can only reference one witness)
         outputData = molecule_1.CKBFSData.pack({
-            index: witnessIndices[0], // Use the first witness index as a single number
+            index: witnessIndices[0], // Use only the first index as a number
             checksum: contentChecksum,
             contentType: data.contentType,
             filename: data.filename,
-            backLinks: backLinks.map(bl => {
-                // Ensure V1 format backlinks use a single index number
-                let singleIndex = 0;
-                // Handle existing index field
-                if (typeof bl.index === 'number') {
-                    singleIndex = bl.index;
-                }
-                // Try to extract from indexes array if available
-                else if (bl.indexes && Array.isArray(bl.indexes) && bl.indexes.length > 0) {
-                    singleIndex = bl.indexes[0];
-                }
-                return {
-                    txHash: bl.txHash,
-                    index: singleIndex,
-                    checksum: bl.checksum
-                };
-            }),
-        }, version);
+            backLinks,
+        }, constants_1.ProtocolVersion.V1); // Explicitly use V1 for packing
     }
     else {
-        // In V2, use all the indices where content is placed
-        // Rule 13 for V2: Output CKBFS Cell's indexes cannot be empty
+        // In V2, indexes is an array of witness indices
         outputData = molecule_1.CKBFSData.pack({
             indexes: witnessIndices,
             checksum: contentChecksum,
             contentType: data.contentType,
             filename: data.filename,
             backLinks,
-        }, version);
+        }, constants_1.ProtocolVersion.V2); // Explicitly use V2 for packing
     }
     // Pack the original data to get its size - use the appropriate version
     const originalData = molecule_1.CKBFSData.pack(data, version);
     const originalDataSize = originalData.length;
-    // Get sizes
+    // Get sizes and calculate capacity requirements
     const newDataSize = outputData.length;
-    const dataSizeDiff = newDataSize - originalDataSize;
-    // Calculate the additional capacity needed (in shannons)
-    // CKB requires 1 shannon per byte of data
-    const additionalCapacity = BigInt(Math.max(0, dataSizeDiff)) * 100000000n;
-    // Add the additional capacity to the original cell capacity
-    console.log(`Original capacity: ${capacity}, Additional needed: ${additionalCapacity}, Data size diff: ${dataSizeDiff}, Version: ${version}`);
-    const outputCapacity = capacity + additionalCapacity;
+    // Calculate the required capacity for the output cell
+    // This accounts for: 
+    // 1. The output data size
+    // 2. The type script's occupied size
+    // 3. The lock script's occupied size
+    // 4. A constant of 8 bytes (for header overhead)
+    const ckbfsCellSize = BigInt(outputData.length + type.occupiedSize + lock.occupiedSize + 8) * 100000000n;
+    console.log(`Original capacity: ${capacity}, Calculated size: ${ckbfsCellSize}, Data size: ${outputData.length}`);
+    // Use the maximum value between calculated size and original capacity
+    // to ensure we have enough capacity but don't decrease capacity unnecessarily
+    const outputCapacity = ckbfsCellSize > capacity ? ckbfsCellSize : capacity;
     // Create initial transaction with the CKBFS cell input
     const tx = core_1.Transaction.from({
         inputs: [
@@ -302,7 +273,8 @@ async function createAppendTransaction(signer, options) {
     // Get the recommended address to ensure lock script cell deps are included
     const address = await signer.getRecommendedAddressObj();
     // If we need more capacity than the original cell had, add additional inputs
-    if (additionalCapacity > 0n) {
+    if (outputCapacity > capacity) {
+        console.log(`Need additional capacity: ${outputCapacity - capacity} shannons`);
         // Add more inputs to cover the increased capacity
         await tx.completeInputsByCapacity(signer);
     }

package/dist/utils/witness.d.ts

@@ -7,14 +7,14 @@
  * @param version Optional version byte (default is 0)
  * @returns Uint8Array containing the witness data
  */
-export declare function createCKBFSWitness(content: Uint8Array, version?: number): Uint8Array;
+export declare function createCKBFSWitness(content: Uint8Array): Uint8Array;
 /**
  * Creates a CKBFS witness with text content
  * @param text The text content to include in the witness
  * @param version Optional version byte (default is 0)
  * @returns Uint8Array containing the witness data
  */
-export declare function createTextCKBFSWitness(text: string, version?: number): Uint8Array;
+export declare function createTextCKBFSWitness(text: string): Uint8Array;
 /**
  * Extracts content from a CKBFS witness
  * @param witness The CKBFS witness data
@@ -34,7 +34,6 @@ export declare function isCKBFSWitness(witness: Uint8Array): boolean;
  * Creates an array of witnesses for a CKBFS transaction from content chunks
  * @param contentChunks Array of content chunks
  * @param version Optional version byte (default is 0)
- * @param protocolVersion Optional protocol version (default is V2)
  * @returns Array of Uint8Array witnesses
  */
-export declare function createChunkedCKBFSWitnesses(contentChunks: Uint8Array[], version?: number, protocolVersion?: string): Uint8Array[];
+export declare function createChunkedCKBFSWitnesses(contentChunks: Uint8Array[]): Uint8Array[];

package/dist/utils/witness.js

@@ -15,9 +15,10 @@ const molecule_1 = require("./molecule");
  * @param version Optional version byte (default is 0)
  * @returns Uint8Array containing the witness data
  */
-function createCKBFSWitness(content, version = 0) {
+function createCKBFSWitness(content) {
     // Create witness with CKBFS header, version byte, and content
-    const versionByte = new Uint8Array([version]);
+    // Version byte must always be 0x00 per protocol
+    const versionByte = new Uint8Array([0]);
     return Buffer.concat([molecule_1.CKBFS_HEADER, versionByte, content]);
 }
 /**
@@ -26,10 +27,10 @@ function createCKBFSWitness(content, version = 0) {
  * @param version Optional version byte (default is 0)
  * @returns Uint8Array containing the witness data
  */
-function createTextCKBFSWitness(text, version = 0) {
+function createTextCKBFSWitness(text) {
     const textEncoder = new TextEncoder();
     const contentBytes = textEncoder.encode(text);
-    return createCKBFSWitness(contentBytes, version);
+    return createCKBFSWitness(contentBytes);
 }
 /**
  * Extracts content from a CKBFS witness
@@ -65,9 +66,8 @@ function isCKBFSWitness(witness) {
  * Creates an array of witnesses for a CKBFS transaction from content chunks
  * @param contentChunks Array of content chunks
  * @param version Optional version byte (default is 0)
- * @param protocolVersion Optional protocol version (default is V2)
  * @returns Array of Uint8Array witnesses
  */
-function createChunkedCKBFSWitnesses(contentChunks, version = 0, protocolVersion) {
-    return contentChunks.map(chunk => createCKBFSWitness(chunk, version));
+function createChunkedCKBFSWitnesses(contentChunks) {
+    return contentChunks.map(chunk => createCKBFSWitness(chunk));
 }

package/examples/retrieve.ts

@@ -0,0 +1,115 @@
+import { CKBFS, NetworkType, ProtocolVersion, getFileContentFromChain, saveFileFromChain } from '../src/index';
+import { ClientPublicTestnet } from "@ckb-ccc/core";
+
+// Replace with your actual private key (or leave this default if just reading)
+const privateKey = process.env.CKB_PRIVATE_KEY || 'your-private-key-here';
+
+// Parse command line arguments for transaction hash
+const txHashArg = process.argv.find(arg => arg.startsWith('--txhash='));
+const outputArg = process.argv.find(arg => arg.startsWith('--output='));
+
+const txHash = txHashArg ? txHashArg.split('=')[1] : process.env.CKBFS_TX_HASH || '';
+const outputPath = outputArg ? outputArg.split('=')[1] : undefined;
+
+if (!txHash) {
+  console.error('Please provide a transaction hash using --txhash=<tx_hash> or the CKBFS_TX_HASH environment variable');
+  process.exit(1);
+}
+
+// Initialize the SDK (read-only is fine for retrieval)
+const ckbfs = new CKBFS(
+  privateKey,
+  NetworkType.Testnet,
+  {
+    version: ProtocolVersion.V2,
+    useTypeID: false
+  }
+);
+
+// Initialize CKB client for testnet
+const client = new ClientPublicTestnet();
+
+/**
+ * Example of retrieving a file from CKBFS
+ */
+async function retrieveExample() {
+  try {
+    console.log(`Retrieving CKBFS file from transaction: ${txHash}`);
+    
+    // Get transaction details
+    const txWithStatus = await client.getTransaction(txHash);
+    if (!txWithStatus || !txWithStatus.transaction) {
+      throw new Error(`Transaction ${txHash} not found`);
+    }
+    
+    // Find index of the CKBFS cell in outputs (assuming it's the first one with a type script)
+    const tx = txWithStatus.transaction;
+    let ckbfsCellIndex = 0;
+    
+    // Get cell data
+    const outputData = tx.outputsData[ckbfsCellIndex];
+    if (!outputData) {
+      throw new Error('Output data not found');
+    }
+    
+    // Get cell info for retrieval
+    const outPoint = {
+      txHash,
+      index: ckbfsCellIndex
+    };
+    
+    // Import necessary components from index
+    const { CKBFSData } = require('../src/index');
+    
+    // Parse the output data
+    const rawData = outputData.startsWith('0x') 
+      ? Buffer.from(outputData.slice(2), 'hex') 
+      : Buffer.from(outputData, 'hex');
+    
+    // Try with both V1 and V2 protocols
+    let ckbfsData;
+    try {
+      console.log('Trying to unpack with V2...');
+      ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+    } catch (error) {
+      console.log('Failed with V2, trying V1...');
+      ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
+    }
+    
+    // Retrieve full file content
+    console.log('Retrieving file content by following backlinks...');
+    const fileContent = await getFileContentFromChain(client, outPoint, ckbfsData);
+    console.log(`Retrieved file content: ${fileContent.length} bytes`);
+    
+    // Save to file
+    const savedPath = saveFileFromChain(fileContent, ckbfsData, outputPath);
+    console.log(`File saved to: ${savedPath}`);
+    
+    return savedPath;
+  } catch (error) {
+    console.error('Error retrieving file:', error);
+    throw error;
+  }
+}
+
+/**
+ * Main function to run the example
+ */
+async function main() {
+  console.log('Running CKBFS file retrieval example...');
+  console.log('--------------------------------------');
+  
+  try {
+    await retrieveExample();
+    console.log('Example completed successfully!');
+    process.exit(0);
+  } catch (error) {
+    console.error('Example failed:', error);
+    process.exit(1);
+  }
+}
+
+// Run the example if this file is executed directly
+if (require.main === module) {
+  main().catch(console.error);
+} 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckbfs/api",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "SDK for CKBFS protocol on CKB",
   "license": "MIT",
   "author": "Code Monad<code@lab-11.org>",
@@ -14,7 +14,8 @@
     "test": "jest",
     "example": "ts-node examples/index.ts",
     "example:publish": "ts-node examples/publish.ts",
-    "example:append": "ts-node examples/append.ts"
+    "example:append": "ts-node examples/append.ts",
+    "example:retrieve": "ts-node examples/retrieve.ts"
   },
   "keywords": [
     "ckb",

package/src/index.ts

@@ -22,7 +22,9 @@ import {
   writeFile,
   getContentType,
   splitFileIntoChunks,
-  combineChunksToFile
+  combineChunksToFile,
+  getFileContentFromChain,
+  saveFileFromChain
 } from './utils/file';
 import {
   createCKBFSWitness,
@@ -323,6 +325,8 @@ export {
   getContentType,
   splitFileIntoChunks,
   combineChunksToFile,
+  getFileContentFromChain,
+  saveFileFromChain,
   
   // Witness utilities
   createCKBFSWitness,

package/src/utils/checksum.ts

@@ -44,11 +44,16 @@ export async function updateChecksum(previousChecksum: number, newData: Uint8Arr
   }
   
   // Combine a and b to get the final checksum
-  const updatedChecksum = (adlerB << 16) | adlerA;
+  // 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)
   
-  // The result should match what you'd get from the adler-32 package
-  // You can verify this in testing by calculating a full checksum
-  // of original + new data and comparing with this rolling result
+  // Read as an unsigned 32-bit integer
+  const updatedChecksum = view.getUint32(0, true);
+  
+  console.log(`Updated checksum from ${previousChecksum} to ${updatedChecksum} for appended content`);
   
   return updatedChecksum;
 }

package/src/utils/file.ts

@@ -106,4 +106,147 @@ export function splitFileIntoChunks(filePath: string, chunkSize: number): Uint8A
 export function combineChunksToFile(chunks: Uint8Array[], outputPath: string): void {
   const combinedBuffer = Buffer.concat(chunks.map(chunk => Buffer.from(chunk)));
   writeFile(outputPath, combinedBuffer);
+}
+
+/**
+ * Utility function to safely decode buffer to string
+ * @param buffer The buffer to decode
+ * @returns Decoded string or placeholder on error
+ */
+function safelyDecode(buffer: any): string {
+  if (!buffer) return '[Unknown]';
+  try {
+    if (buffer instanceof Uint8Array) {
+      return new TextDecoder().decode(buffer);
+    } else if (typeof buffer === 'string') {
+      return buffer;
+    } else {
+      return `[Buffer: ${buffer.toString()}]`;
+    }
+  } catch (e) {
+    return '[Decode Error]';
+  }
+}
+
+/**
+ * Retrieves complete file content from the blockchain by following backlinks
+ * @param client The CKB client to use for blockchain queries
+ * @param outPoint The output point of the latest CKBFS cell
+ * @param ckbfsData The data from the latest CKBFS cell
+ * @returns Promise resolving to the complete file content
+ */
+export async function getFileContentFromChain(
+  client: any,
+  outPoint: { txHash: string; index: number },
+  ckbfsData: any
+): Promise<Uint8Array> {
+  console.log(`Retrieving file: ${safelyDecode(ckbfsData.filename)}`);
+  console.log(`Content type: ${safelyDecode(ckbfsData.contentType)}`);
+  
+  // Prepare to collect all content pieces
+  const contentPieces: Uint8Array[] = [];
+  let currentData = ckbfsData;
+  let currentOutPoint = outPoint;
+  
+  // Process the current transaction first
+  const tx = await client.getTransaction(currentOutPoint.txHash);
+  if (!tx || !tx.transaction) {
+    throw new Error(`Transaction ${currentOutPoint.txHash} not found`);
+  }
+  
+  // Get content from witnesses
+  const indexes = currentData.indexes || (currentData.index !== undefined ? [currentData.index] : []);
+  if (indexes.length > 0) {
+    // Get content from each witness index
+    for (const idx of indexes) {
+      if (idx >= tx.transaction.witnesses.length) {
+        console.warn(`Witness index ${idx} out of range`);
+        continue;
+      }
+      
+      const witnessHex = tx.transaction.witnesses[idx];
+      const witness = Buffer.from(witnessHex.slice(2), 'hex'); // Remove 0x prefix
+      
+      // Extract content (skip CKBFS header + version byte)
+      if (witness.length >= 6 && witness.slice(0, 5).toString() === 'CKBFS') {
+        const content = witness.slice(6);
+        contentPieces.unshift(content); // Add to beginning of array (we're going backwards)
+      } else {
+        console.warn(`Witness at index ${idx} is not a valid CKBFS witness`);
+      }
+    }
+  }
+  
+  // Follow backlinks recursively
+  if (currentData.backLinks && currentData.backLinks.length > 0) {
+    // Process each backlink, from most recent to oldest
+    for (let i = currentData.backLinks.length - 1; i >= 0; i--) {
+      const backlink = currentData.backLinks[i];
+      
+      // Get the transaction for this backlink
+      const backTx = await client.getTransaction(backlink.txHash);
+      if (!backTx || !backTx.transaction) {
+        console.warn(`Backlink transaction ${backlink.txHash} not found`);
+        continue;
+      }
+      
+      // Get content from backlink witnesses
+      const backIndexes = backlink.indexes || (backlink.index !== undefined ? [backlink.index] : []);
+      if (backIndexes.length > 0) {
+        // Get content from each witness index
+        for (const idx of backIndexes) {
+          if (idx >= backTx.transaction.witnesses.length) {
+            console.warn(`Backlink witness index ${idx} out of range`);
+            continue;
+          }
+          
+          const witnessHex = backTx.transaction.witnesses[idx];
+          const witness = Buffer.from(witnessHex.slice(2), 'hex'); // Remove 0x prefix
+          
+          // Extract content (skip CKBFS header + version byte)
+          if (witness.length >= 6 && witness.slice(0, 5).toString() === 'CKBFS') {
+            const content = witness.slice(6);
+            contentPieces.unshift(content); // Add to beginning of array (we're going backwards)
+          } else {
+            console.warn(`Backlink witness at index ${idx} is not a valid CKBFS witness`);
+          }
+        }
+      }
+    }
+  }
+  
+  // Combine all content pieces
+  return Buffer.concat(contentPieces);
+}
+
+/**
+ * Saves file content retrieved from blockchain to disk
+ * @param content The file content to save
+ * @param ckbfsData The CKBFS cell data containing file metadata
+ * @param outputPath Optional path to save the file (defaults to filename in current directory)
+ * @returns The path where the file was saved
+ */
+export function saveFileFromChain(
+  content: Uint8Array,
+  ckbfsData: any,
+  outputPath?: string
+): string {
+  // Get filename from CKBFS data
+  const filename = safelyDecode(ckbfsData.filename);
+  
+  // Determine output path
+  const filePath = outputPath || filename;
+  
+  // Ensure directory exists
+  const directory = path.dirname(filePath);
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+  
+  // Write file
+  fs.writeFileSync(filePath, content);
+  console.log(`File saved to: ${filePath}`);
+  console.log(`Size: ${content.length} bytes`);
+  
+  return filePath;
 } 

package/test-download.txt

@@ -0,0 +1,2 @@
+Hello, CKBFS! This is a sample file published using 20240906.ce6724722cf6 protocol.
+This is content to append to the previously published file.