@ckbfs/api 1.2.3 → 1.2.5

package/src/utils/file.ts

@@ -1,5 +1,5 @@
-import fs from 'fs';
-import path from 'path';
+import fs from "fs";
+import path from "path";
 
 /**
  * Utility functions for file operations
@@ -20,7 +20,7 @@ export function readFile(filePath: string): Buffer {
  * @returns String containing the file contents
  */
 export function readFileAsText(filePath: string): string {
-  return fs.readFileSync(filePath, 'utf-8');
+  return fs.readFileSync(filePath, "utf-8");
 }
 
 /**
@@ -44,7 +44,7 @@ export function writeFile(filePath: string, data: Buffer | string): void {
   if (!fs.existsSync(dirPath)) {
     fs.mkdirSync(dirPath, { recursive: true });
   }
-  
+
   fs.writeFileSync(filePath, data);
 }
 
@@ -55,30 +55,30 @@ export function writeFile(filePath: string, data: Buffer | string): void {
  */
 export function getContentType(filePath: string): string {
   const extension = path.extname(filePath).toLowerCase();
-  
+
   const mimeTypes: { [key: string]: string } = {
-    '.txt': 'text/plain',
-    '.html': 'text/html',
-    '.htm': 'text/html',
-    '.css': 'text/css',
-    '.js': 'application/javascript',
-    '.json': 'application/json',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.png': 'image/png',
-    '.gif': 'image/gif',
-    '.svg': 'image/svg+xml',
-    '.pdf': 'application/pdf',
-    '.mp3': 'audio/mpeg',
-    '.mp4': 'video/mp4',
-    '.wav': 'audio/wav',
-    '.xml': 'application/xml',
-    '.zip': 'application/zip',
-    '.md': 'text/markdown',
-    '.markdown': 'text/markdown',
+    ".txt": "text/plain",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".css": "text/css",
+    ".js": "application/javascript",
+    ".json": "application/json",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".mp3": "audio/mpeg",
+    ".mp4": "video/mp4",
+    ".wav": "audio/wav",
+    ".xml": "application/xml",
+    ".zip": "application/zip",
+    ".md": "text/markdown",
+    ".markdown": "text/markdown",
   };
-  
-  return mimeTypes[extension] || 'application/octet-stream';
+
+  return mimeTypes[extension] || "application/octet-stream";
 }
 
 /**
@@ -87,14 +87,17 @@ export function getContentType(filePath: string): string {
  * @param chunkSize The maximum size of each chunk in bytes
  * @returns Array of Uint8Array chunks
  */
-export function splitFileIntoChunks(filePath: string, chunkSize: number): Uint8Array[] {
+export function splitFileIntoChunks(
+  filePath: string,
+  chunkSize: number,
+): Uint8Array[] {
   const fileBuffer = fs.readFileSync(filePath);
   const chunks: Uint8Array[] = [];
-  
+
   for (let i = 0; i < fileBuffer.length; i += chunkSize) {
     chunks.push(new Uint8Array(fileBuffer.slice(i, i + chunkSize)));
   }
-  
+
   return chunks;
 }
 
@@ -103,8 +106,13 @@ export function splitFileIntoChunks(filePath: string, chunkSize: number): Uint8A
  * @param chunks Array of chunks to combine
  * @param outputPath The path to write the combined file to
  */
-export function combineChunksToFile(chunks: Uint8Array[], outputPath: string): void {
-  const combinedBuffer = Buffer.concat(chunks.map(chunk => Buffer.from(chunk)));
+export function combineChunksToFile(
+  chunks: Uint8Array[],
+  outputPath: string,
+): void {
+  const combinedBuffer = Buffer.concat(
+    chunks.map((chunk) => Buffer.from(chunk)),
+  );
   writeFile(outputPath, combinedBuffer);
 }
 
@@ -114,17 +122,17 @@ export function combineChunksToFile(chunks: Uint8Array[], outputPath: string): v
  * @returns Decoded string or placeholder on error
  */
 function safelyDecode(buffer: any): string {
-  if (!buffer) return '[Unknown]';
+  if (!buffer) return "[Unknown]";
   try {
     if (buffer instanceof Uint8Array) {
       return new TextDecoder().decode(buffer);
-    } else if (typeof buffer === 'string') {
+    } else if (typeof buffer === "string") {
       return buffer;
     } else {
       return `[Buffer: ${buffer.toString()}]`;
     }
   } catch (e) {
-    return '[Decode Error]';
+    return "[Decode Error]";
   }
 }
 
@@ -138,24 +146,26 @@ function safelyDecode(buffer: any): string {
 export async function getFileContentFromChain(
   client: any,
   outPoint: { txHash: string; index: number },
-  ckbfsData: any
+  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] : []);
+  const indexes =
+    currentData.indexes ||
+    (currentData.index !== undefined ? [currentData.index] : []);
   if (indexes.length > 0) {
     // Get content from each witness index
     for (const idx of indexes) {
@@ -163,12 +173,12 @@ export async function getFileContentFromChain(
         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
-      
+      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') {
+      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 {
@@ -176,22 +186,24 @@ export async function getFileContentFromChain(
       }
     }
   }
-  
+
   // 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] : []);
+      const backIndexes =
+        backlink.indexes ||
+        (backlink.index !== undefined ? [backlink.index] : []);
       if (backIndexes.length > 0) {
         // Get content from each witness index
         for (const idx of backIndexes) {
@@ -199,22 +211,27 @@ export async function getFileContentFromChain(
             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
-          
+          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') {
+          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`);
+            console.warn(
+              `Backlink witness at index ${idx} is not a valid CKBFS witness`,
+            );
           }
         }
       }
     }
   }
-  
+
   // Combine all content pieces
   return Buffer.concat(contentPieces);
 }
@@ -229,24 +246,812 @@ export async function getFileContentFromChain(
 export function saveFileFromChain(
   content: Uint8Array,
   ckbfsData: any,
-  outputPath?: string
+  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;
-} 
+}
+
+/**
+ * Decodes content from a single CKBFS witness
+ * @param witnessHex The witness data in hex format (with or without 0x prefix)
+ * @returns Object containing the decoded content and metadata, or null if not a valid CKBFS witness
+ */
+export function decodeWitnessContent(
+  witnessHex: string,
+): { content: Uint8Array; isValid: boolean } | null {
+  try {
+    // Remove 0x prefix if present
+    const hexData = witnessHex.startsWith("0x")
+      ? witnessHex.slice(2)
+      : witnessHex;
+    const witness = Buffer.from(hexData, "hex");
+
+    // Check if it's a valid CKBFS witness
+    if (witness.length < 6) {
+      return null;
+    }
+
+    // Check CKBFS header
+    const header = witness.slice(0, 5).toString();
+    if (header !== "CKBFS") {
+      return null;
+    }
+
+    // Extract content (skip CKBFS header + version byte)
+    const content = witness.slice(6);
+
+    return {
+      content,
+      isValid: true,
+    };
+  } catch (error) {
+    console.warn("Error decoding witness content:", error);
+    return null;
+  }
+}
+
+/**
+ * Decodes and combines content from multiple CKBFS witnesses
+ * @param witnessHexArray Array of witness data in hex format
+ * @param preserveOrder Whether to preserve the order of witnesses (default: true)
+ * @returns Combined content from all valid CKBFS witnesses
+ */
+export function decodeMultipleWitnessContents(
+  witnessHexArray: string[],
+  preserveOrder: boolean = true,
+): Uint8Array {
+  const contentPieces: Uint8Array[] = [];
+
+  for (let i = 0; i < witnessHexArray.length; i++) {
+    const witnessHex = witnessHexArray[i];
+    const decoded = decodeWitnessContent(witnessHex);
+
+    if (decoded && decoded.isValid) {
+      if (preserveOrder) {
+        contentPieces.push(decoded.content);
+      } else {
+        contentPieces.unshift(decoded.content);
+      }
+    } else {
+      console.warn(`Witness at index ${i} is not a valid CKBFS witness`);
+    }
+  }
+
+  return Buffer.concat(contentPieces);
+}
+
+/**
+ * Extracts complete file content from witnesses using specified indexes
+ * @param witnesses Array of all witnesses from a transaction
+ * @param indexes Array of witness indexes that contain CKBFS content
+ * @returns Combined content from the specified witness indexes
+ */
+export function extractFileFromWitnesses(
+  witnesses: string[],
+  indexes: number[],
+): Uint8Array {
+  const relevantWitnesses: string[] = [];
+
+  for (const idx of indexes) {
+    if (idx >= witnesses.length) {
+      console.warn(
+        `Witness index ${idx} out of range (total witnesses: ${witnesses.length})`,
+      );
+      continue;
+    }
+    relevantWitnesses.push(witnesses[idx]);
+  }
+
+  return decodeMultipleWitnessContents(relevantWitnesses, true);
+}
+
+/**
+ * Decodes file content directly from witness data without blockchain queries
+ * @param witnessData Object containing witness information
+ * @returns Object containing the decoded file content and metadata
+ */
+export function decodeFileFromWitnessData(witnessData: {
+  witnesses: string[];
+  indexes: number[] | number;
+  filename?: string;
+  contentType?: string;
+}): {
+  content: Uint8Array;
+  filename?: string;
+  contentType?: string;
+  size: number;
+} {
+  const { witnesses, indexes, filename, contentType } = witnessData;
+
+  // Normalize indexes to array
+  const indexArray = Array.isArray(indexes) ? indexes : [indexes];
+
+  // Extract content from witnesses
+  const content = extractFileFromWitnesses(witnesses, indexArray);
+
+  return {
+    content,
+    filename,
+    contentType,
+    size: content.length,
+  };
+}
+
+/**
+ * Saves decoded file content directly from witness data
+ * @param witnessData Object containing witness information
+ * @param outputPath Optional path to save the file
+ * @returns The path where the file was saved
+ */
+export function saveFileFromWitnessData(
+  witnessData: {
+    witnesses: string[];
+    indexes: number[] | number;
+    filename?: string;
+    contentType?: string;
+  },
+  outputPath?: string,
+): string {
+  const decoded = decodeFileFromWitnessData(witnessData);
+
+  // Determine output path
+  const filename = decoded.filename || "decoded_file";
+  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, decoded.content);
+  console.log(`File saved to: ${filePath}`);
+  console.log(`Size: ${decoded.size} bytes`);
+  console.log(`Content type: ${decoded.contentType || "unknown"}`);
+
+  return filePath;
+}
+
+/**
+ * Identifier types for CKBFS cells
+ */
+export enum IdentifierType {
+  TypeID = "typeId",
+  OutPoint = "outPoint",
+  Unknown = "unknown",
+}
+
+/**
+ * Parsed identifier information
+ */
+export interface ParsedIdentifier {
+  type: IdentifierType;
+  typeId?: string;
+  txHash?: string;
+  index?: number;
+  original: string;
+}
+
+/**
+ * Detects and parses different CKBFS identifier formats
+ * @param identifier The identifier string to parse
+ * @returns Parsed identifier information
+ */
+export function parseIdentifier(identifier: string): ParsedIdentifier {
+  const trimmed = identifier.trim();
+
+  // Type 1: Pure TypeID hex string (with or without 0x prefix)
+  if (trimmed.match(/^(0x)?[a-fA-F0-9]{64}$/)) {
+    const typeId = trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`;
+    return {
+      type: IdentifierType.TypeID,
+      typeId,
+      original: identifier,
+    };
+  }
+
+  // Type 2: CKBFS URI with TypeID
+  if (trimmed.startsWith("ckbfs://")) {
+    const content = trimmed.slice(8); // Remove "ckbfs://"
+
+    // Check if it's TypeID format (64 hex characters)
+    if (content.match(/^[a-fA-F0-9]{64}$/)) {
+      return {
+        type: IdentifierType.TypeID,
+        typeId: `0x${content}`,
+        original: identifier,
+      };
+    }
+
+    // Type 3: CKBFS URI with transaction hash and index (txhash + 'i' + index)
+    const outPointMatch = content.match(/^([a-fA-F0-9]{64})i(\d+)$/);
+    if (outPointMatch) {
+      const [, txHash, indexStr] = outPointMatch;
+      return {
+        type: IdentifierType.OutPoint,
+        txHash: `0x${txHash}`,
+        index: parseInt(indexStr, 10),
+        original: identifier,
+      };
+    }
+  }
+
+  // Unknown format
+  return {
+    type: IdentifierType.Unknown,
+    original: identifier,
+  };
+}
+
+/**
+ * Resolves a CKBFS cell using any supported identifier format
+ * @param client The CKB client to use for blockchain queries
+ * @param identifier The identifier (TypeID, CKBFS URI, or outPoint URI)
+ * @param options Optional configuration for network, version, and useTypeID
+ * @returns Promise resolving to the found cell and transaction info, or null if not found
+ */
+async function resolveCKBFSCell(
+  client: any,
+  identifier: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<{
+  cell: any;
+  transaction: any;
+  outPoint: { txHash: string; index: number };
+  parsedId: ParsedIdentifier;
+} | null> {
+  const {
+    network = "testnet",
+    version = "20241025.db973a8e8032",
+    useTypeID = false,
+  } = options;
+
+  const parsedId = parseIdentifier(identifier);
+
+  try {
+    if (parsedId.type === IdentifierType.TypeID && parsedId.typeId) {
+      // Use existing TypeID resolution logic
+      const cellInfo = await findCKBFSCellByTypeId(
+        client,
+        parsedId.typeId,
+        network,
+        version,
+        useTypeID,
+      );
+
+      if (cellInfo) {
+        return {
+          ...cellInfo,
+          parsedId,
+        };
+      }
+    } else if (
+      parsedId.type === IdentifierType.OutPoint &&
+      parsedId.txHash &&
+      parsedId.index !== undefined
+    ) {
+      // Resolve using transaction hash and index
+      const txWithStatus = await client.getTransaction(parsedId.txHash);
+
+      if (!txWithStatus || !txWithStatus.transaction) {
+        console.warn(`Transaction ${parsedId.txHash} not found`);
+        return null;
+      }
+
+      // Import Transaction class dynamically
+      const { Transaction } = await import("@ckb-ccc/core");
+      const tx = Transaction.from(txWithStatus.transaction);
+
+      // Check if the index is valid
+      if (parsedId.index >= tx.outputs.length) {
+        console.warn(
+          `Output index ${parsedId.index} out of range for transaction ${parsedId.txHash}`,
+        );
+        return null;
+      }
+
+      const output = tx.outputs[parsedId.index];
+
+      // Verify it's a CKBFS cell by checking if it has a type script
+      if (!output.type) {
+        console.warn(
+          `Output at index ${parsedId.index} is not a CKBFS cell (no type script)`,
+        );
+        return null;
+      }
+
+      // Create a mock cell object similar to what findSingletonCellByType returns
+      const cell = {
+        outPoint: {
+          txHash: parsedId.txHash,
+          index: parsedId.index,
+        },
+        output,
+      };
+
+      return {
+        cell,
+        transaction: txWithStatus.transaction,
+        outPoint: {
+          txHash: parsedId.txHash,
+          index: parsedId.index,
+        },
+        parsedId,
+      };
+    }
+
+    console.warn(
+      `Unable to resolve identifier: ${identifier} (type: ${parsedId.type})`,
+    );
+    return null;
+  } catch (error) {
+    console.error(
+      `Error resolving CKBFS cell for identifier ${identifier}:`,
+      error,
+    );
+    return null;
+  }
+}
+
+/**
+ * Finds a CKBFS cell by TypeID
+ * @param client The CKB client to use for blockchain queries
+ * @param typeId The TypeID (args) of the CKBFS cell to find
+ * @param network The network type (mainnet or testnet)
+ * @param version The protocol version to use
+ * @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: any,
+  typeId: string,
+  network: string = "testnet",
+  version: string = "20241025.db973a8e8032",
+  useTypeID: boolean = false,
+): Promise<{
+  cell: any;
+  transaction: any;
+  outPoint: { txHash: string; index: number };
+} | null> {
+  try {
+    // Import constants dynamically to avoid circular dependencies
+    const { getCKBFSScriptConfig, NetworkType, ProtocolVersion } = await import(
+      "./constants"
+    );
+
+    // Get CKBFS script config
+    const networkType =
+      network === "mainnet" ? NetworkType.Mainnet : NetworkType.Testnet;
+    const protocolVersion =
+      version === "20240906.ce6724722cf6"
+        ? ProtocolVersion.V1
+        : ProtocolVersion.V2;
+    const config = getCKBFSScriptConfig(
+      networkType,
+      protocolVersion,
+      useTypeID,
+    );
+
+    // Create the script to search for
+    const script = {
+      codeHash: config.codeHash,
+      hashType: config.hashType,
+      args: typeId.startsWith("0x") ? typeId : `0x${typeId}`,
+    };
+
+    // Find the cell by type script
+    const cell = await client.findSingletonCellByType(script, true);
+
+    if (!cell) {
+      return null;
+    }
+
+    // Get the transaction that contains this cell
+    const txHash = cell.outPoint.txHash;
+    const txWithStatus = await client.getTransaction(txHash);
+
+    if (!txWithStatus || !txWithStatus.transaction) {
+      throw new Error(`Transaction ${txHash} not found`);
+    }
+
+    return {
+      cell,
+      transaction: txWithStatus.transaction,
+      outPoint: {
+        txHash: cell.outPoint.txHash,
+        index: cell.outPoint.index,
+      },
+    };
+  } catch (error) {
+    console.warn(`Error finding CKBFS cell by TypeID ${typeId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Retrieves complete file content from the blockchain using any supported identifier
+ * @param client The CKB client to use for blockchain queries
+ * @param identifier The identifier (TypeID hex, CKBFS TypeID URI, or CKBFS outPoint URI)
+ * @param options Optional configuration for network, version, and useTypeID
+ * @returns Promise resolving to the complete file content and metadata
+ */
+export async function getFileContentFromChainByIdentifier(
+  client: any,
+  identifier: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<{
+  content: Uint8Array;
+  filename: string;
+  contentType: string;
+  checksum: number;
+  size: number;
+  backLinks: any[];
+  parsedId: ParsedIdentifier;
+} | null> {
+  const {
+    network = "testnet",
+    version = "20241025.db973a8e8032",
+    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 cell with identifier ${identifier} not found`);
+      return null;
+    }
+
+    const { cell, transaction, outPoint, parsedId } = cellInfo;
+
+    // Import Transaction class dynamically
+    const { Transaction } = await import("@ckb-ccc/core");
+    const tx = Transaction.from(transaction);
+
+    // Get output data from the cell
+    const outputIndex = outPoint.index;
+    const outputData = tx.outputsData[outputIndex];
+
+    if (!outputData) {
+      throw new Error(`Output data not found for cell at index ${outputIndex}`);
+    }
+
+    // Import required modules dynamically
+    const { ccc } = await import("@ckb-ccc/core");
+    const { CKBFSData } = await import("./molecule");
+    const { ProtocolVersion } = await import("./constants");
+
+    // Parse the output data
+    const rawData = outputData.startsWith("0x")
+      ? ccc.bytesFrom(outputData.slice(2), "hex")
+      : Buffer.from(outputData, "hex");
+
+    // Try to unpack CKBFS data with both protocol versions
+    let ckbfsData: any;
+    let protocolVersion = version;
+
+    try {
+      ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+    } catch (error) {
+      try {
+        ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
+        protocolVersion = "20240906.ce6724722cf6";
+      } catch (v1Error) {
+        throw new Error(
+          `Failed to unpack CKBFS data with both versions: V2(${error}), V1(${v1Error})`,
+        );
+      }
+    }
+
+    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);
+
+    return {
+      content,
+      filename: ckbfsData.filename,
+      contentType: ckbfsData.contentType,
+      checksum: ckbfsData.checksum,
+      size: content.length,
+      backLinks: ckbfsData.backLinks || [],
+      parsedId,
+    };
+  } catch (error) {
+    console.error(`Error retrieving file by identifier ${identifier}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Retrieves complete file content from the blockchain using TypeID (legacy function)
+ * @param client The CKB client to use for blockchain queries
+ * @param typeId The TypeID (args) of the CKBFS cell
+ * @param options Optional configuration for network, version, and useTypeID
+ * @returns Promise resolving to the complete file content and metadata
+ */
+export async function getFileContentFromChainByTypeId(
+  client: any,
+  typeId: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<{
+  content: Uint8Array;
+  filename: string;
+  contentType: string;
+  checksum: number;
+  size: number;
+  backLinks: any[];
+} | null> {
+  const result = await getFileContentFromChainByIdentifier(
+    client,
+    typeId,
+    options,
+  );
+  if (result) {
+    const { parsedId, ...fileData } = result;
+    return fileData;
+  }
+  return null;
+}
+
+/**
+ * Saves file content retrieved from blockchain by identifier to disk
+ * @param client The CKB client to use for blockchain queries
+ * @param identifier The identifier (TypeID hex, CKBFS TypeID URI, or CKBFS outPoint URI)
+ * @param outputPath Optional path to save the file (defaults to filename from CKBFS data)
+ * @param options Optional configuration for network, version, and useTypeID
+ * @returns Promise resolving to the path where the file was saved, or null if file not found
+ */
+export async function saveFileFromChainByIdentifier(
+  client: any,
+  identifier: string,
+  outputPath?: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<string | null> {
+  try {
+    // Get file content by identifier
+    const fileData = await getFileContentFromChainByIdentifier(
+      client,
+      identifier,
+      options,
+    );
+
+    if (!fileData) {
+      console.warn(`File with identifier ${identifier} not found`);
+      return null;
+    }
+
+    // Determine output path
+    const filePath = outputPath || fileData.filename;
+
+    // Ensure directory exists
+    const directory = path.dirname(filePath);
+    if (!fs.existsSync(directory)) {
+      fs.mkdirSync(directory, { recursive: true });
+    }
+
+    // Write file
+    fs.writeFileSync(filePath, fileData.content);
+    console.log(`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 file by identifier ${identifier}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Saves file content retrieved from blockchain by TypeID to disk (legacy function)
+ * @param client The CKB client to use for blockchain queries
+ * @param typeId The TypeID (args) of the CKBFS cell
+ * @param outputPath Optional path to save the file (defaults to filename from CKBFS data)
+ * @param options Optional configuration for network, version, and useTypeID
+ * @returns Promise resolving to the path where the file was saved, or null if file not found
+ */
+export async function saveFileFromChainByTypeId(
+  client: any,
+  typeId: string,
+  outputPath?: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<string | null> {
+  return await saveFileFromChainByIdentifier(
+    client,
+    typeId,
+    outputPath,
+    options,
+  );
+}
+
+/**
+ * Decodes file content directly from identifier using witness decoding (new method)
+ * @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 decoded file content and metadata, or null if not found
+ */
+export async function decodeFileFromChainByIdentifier(
+  client: any,
+  identifier: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<{
+  content: Uint8Array;
+  filename: string;
+  contentType: string;
+  checksum: number;
+  size: number;
+  backLinks: any[];
+  parsedId: ParsedIdentifier;
+} | null> {
+  const {
+    network = "testnet",
+    version = "20241025.db973a8e8032",
+    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 cell with identifier ${identifier} not found`);
+      return null;
+    }
+
+    const { cell, transaction, outPoint, parsedId } = cellInfo;
+
+    // Import required modules dynamically
+    const { Transaction, ccc } = await import("@ckb-ccc/core");
+    const { CKBFSData } = await import("./molecule");
+    const { ProtocolVersion } = await import("./constants");
+
+    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}`);
+    }
+
+    // Parse the output data
+    const rawData = outputData.startsWith("0x")
+      ? ccc.bytesFrom(outputData.slice(2), "hex")
+      : Buffer.from(outputData, "hex");
+
+    // Try to unpack CKBFS data with both protocol versions
+    let ckbfsData: any;
+    let protocolVersion = version;
+
+    try {
+      ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V2);
+    } catch (error) {
+      try {
+        ckbfsData = CKBFSData.unpack(rawData, ProtocolVersion.V1);
+        protocolVersion = "20240906.ce6724722cf6";
+      } catch (v1Error) {
+        throw new Error(
+          `Failed to unpack CKBFS data with both versions: V2(${error}), V1(${v1Error})`,
+        );
+      }
+    }
+
+    console.log(`Found CKBFS file: ${ckbfsData.filename}`);
+    console.log(`Content type: ${ckbfsData.contentType}`);
+    console.log(`Using direct witness decoding method`);
+
+    // 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,
+    });
+
+    return {
+      content: content.content,
+      filename: ckbfsData.filename,
+      contentType: ckbfsData.contentType,
+      checksum: ckbfsData.checksum,
+      size: content.size,
+      backLinks: ckbfsData.backLinks || [],
+      parsedId,
+    };
+  } catch (error) {
+    console.error(`Error decoding file by identifier ${identifier}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Decodes file content directly from TypeID using witness decoding (legacy function)
+ * @param client The CKB client to use for blockchain queries
+ * @param typeId The TypeID (args) of the CKBFS cell
+ * @param options Optional configuration for network, version, and useTypeID
+ * @returns Promise resolving to the decoded file content and metadata, or null if not found
+ */
+export async function decodeFileFromChainByTypeId(
+  client: any,
+  typeId: string,
+  options: {
+    network?: "mainnet" | "testnet";
+    version?: string;
+    useTypeID?: boolean;
+  } = {},
+): Promise<{
+  content: Uint8Array;
+  filename: string;
+  contentType: string;
+  checksum: number;
+  size: number;
+  backLinks: any[];
+} | null> {
+  const result = await decodeFileFromChainByIdentifier(client, typeId, options);
+  if (result) {
+    const { parsedId, ...fileData } = result;
+    return fileData;
+  }
+  return null;
+}