@ckbfs/api 1.1.0 → 1.2.0

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/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.0",
   "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/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.