@ckbfs/api 1.2.4 → 1.2.5

package/package.json

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

package/src/index.ts

@@ -1,20 +1,26 @@
-import { Script, Signer, Transaction, ClientPublicTestnet, SignerCkbPrivateKey } from "@ckb-ccc/core";
-import { 
-  calculateChecksum, 
-  verifyChecksum, 
-  updateChecksum, 
-  verifyWitnessChecksum 
-} from './utils/checksum';
+import {
+  Script,
+  Signer,
+  Transaction,
+  ClientPublicTestnet,
+  SignerCkbPrivateKey,
+} from "@ckb-ccc/core";
+import {
+  calculateChecksum,
+  verifyChecksum,
+  updateChecksum,
+  verifyWitnessChecksum,
+} from "./utils/checksum";
 import {
   createCKBFSCell,
-  createPublishTransaction,
-  createAppendTransaction,
-  publishCKBFS,
-  appendCKBFS,
+  createPublishTransaction as utilCreatePublishTransaction,
+  createAppendTransaction as utilCreateAppendTransaction,
+  publishCKBFS as utilPublishCKBFS,
+  appendCKBFS as utilAppendCKBFS,
   CKBFSCellOptions,
   PublishOptions,
-  AppendOptions
-} from './utils/transaction';
+  AppendOptions,
+} from "./utils/transaction";
 import {
   readFile,
   readFileAsText,
@@ -24,15 +30,28 @@ import {
   splitFileIntoChunks,
   combineChunksToFile,
   getFileContentFromChain,
-  saveFileFromChain
-} from './utils/file';
+  saveFileFromChain,
+  getFileContentFromChainByTypeId,
+  saveFileFromChainByTypeId,
+  decodeFileFromChainByTypeId,
+  getFileContentFromChainByIdentifier,
+  saveFileFromChainByIdentifier,
+  decodeFileFromChainByIdentifier,
+  parseIdentifier,
+  IdentifierType,
+  decodeWitnessContent,
+  decodeMultipleWitnessContents,
+  extractFileFromWitnesses,
+  decodeFileFromWitnessData,
+  saveFileFromWitnessData,
+} from "./utils/file";
 import {
   createCKBFSWitness,
   createTextCKBFSWitness,
   extractCKBFSWitnessContent,
   isCKBFSWitness,
-  createChunkedCKBFSWitnesses
-} from './utils/witness';
+  createChunkedCKBFSWitnesses,
+} from "./utils/witness";
 import {
   CKBFSData,
   BackLinkV1,
@@ -40,11 +59,12 @@ import {
   CKBFSDataType,
   BackLinkType,
   CKBFS_HEADER,
-  CKBFS_HEADER_STRING
-} from './utils/molecule';
+  CKBFS_HEADER_STRING,
+} from "./utils/molecule";
 import {
   NetworkType,
   ProtocolVersion,
+  ProtocolVersionType,
   DEFAULT_NETWORK,
   DEFAULT_VERSION,
   CKBFS_CODE_HASH,
@@ -54,8 +74,12 @@ import {
   DEP_GROUP_TX_HASH,
   DEPLOY_TX_HASH,
   getCKBFSScriptConfig,
-  CKBFSScriptConfig
-} from './utils/constants';
+  CKBFSScriptConfig,
+} from "./utils/constants";
+import { ensureHexPrefix } from "./utils/transaction";
+
+// Helper to encode string to Uint8Array
+const textEncoder = new TextEncoder();
 
 /**
  * Custom options for file publishing and appending
@@ -66,16 +90,35 @@ export interface FileOptions {
   capacity?: bigint;
   feeRate?: number;
   network?: NetworkType;
-  version?: string;
+  version?: ProtocolVersionType;
   useTypeID?: boolean;
 }
 
+/**
+ * Options required when publishing content directly (string or Uint8Array)
+ */
+export type PublishContentOptions = Omit<
+  FileOptions,
+  "capacity" | "contentType" | "filename"
+> &
+  Required<Pick<FileOptions, "contentType" | "filename">> & {
+    capacity?: bigint;
+  };
+
+/**
+ * Options required when appending content directly (string or Uint8Array)
+ */
+export type AppendContentOptions = Omit<
+  FileOptions,
+  "contentType" | "filename" | "capacity"
+> & { capacity?: bigint };
+
 /**
  * Configuration options for the CKBFS SDK
  */
 export interface CKBFSOptions {
   chunkSize?: number;
-  version?: string;
+  version?: ProtocolVersionType;
   useTypeID?: boolean;
   network?: NetworkType;
 }
@@ -87,9 +130,9 @@ export class CKBFS {
   private signer: Signer;
   private chunkSize: number;
   private network: NetworkType;
-  private version: string;
+  private version: ProtocolVersionType;
   private useTypeID: boolean;
-  
+
   /**
    * Creates a new CKBFS SDK instance
    * @param signerOrPrivateKey The signer instance or CKB private key to use for signing transactions
@@ -99,15 +142,20 @@ export class CKBFS {
   constructor(
     signerOrPrivateKey: Signer | string,
     networkOrOptions: NetworkType | CKBFSOptions = DEFAULT_NETWORK,
-    options?: CKBFSOptions
+    options?: CKBFSOptions,
   ) {
     // Determine if first parameter is a Signer or privateKey
-    if (typeof signerOrPrivateKey === 'string') {
+    if (typeof signerOrPrivateKey === "string") {
       // Initialize with private key
       const privateKey = signerOrPrivateKey;
-      const network = typeof networkOrOptions === 'string' ? networkOrOptions : DEFAULT_NETWORK;
-      const opts = options || (typeof networkOrOptions === 'object' ? networkOrOptions : {});
-      
+      const network =
+        typeof networkOrOptions === "string"
+          ? networkOrOptions
+          : DEFAULT_NETWORK;
+      const opts =
+        options ||
+        (typeof networkOrOptions === "object" ? networkOrOptions : {});
+
       const client = new ClientPublicTestnet();
       this.signer = new SignerCkbPrivateKey(client, privateKey);
       this.network = network;
@@ -117,15 +165,15 @@ export class CKBFS {
     } else {
       // Initialize with signer
       this.signer = signerOrPrivateKey;
-      const opts = typeof networkOrOptions === 'object' ? networkOrOptions : {};
-      
+      const opts = typeof networkOrOptions === "object" ? networkOrOptions : {};
+
       this.network = opts.network || DEFAULT_NETWORK;
       this.chunkSize = opts.chunkSize || 30 * 1024;
       this.version = opts.version || DEFAULT_VERSION;
       this.useTypeID = opts.useTypeID || false;
     }
   }
-  
+
   /**
    * Gets the recommended address object for the signer
    * @returns Promise resolving to the address object
@@ -133,7 +181,7 @@ export class CKBFS {
   async getAddress() {
     return this.signer.getRecommendedAddressObj();
   }
-  
+
   /**
    * Gets the lock script for the signer
    * @returns Promise resolving to the lock script
@@ -142,7 +190,7 @@ export class CKBFS {
     const address = await this.getAddress();
     return address.script;
   }
-  
+
   /**
    * Gets the CKBFS script configuration for the current settings
    * @returns The CKBFS script configuration
@@ -150,34 +198,37 @@ export class CKBFS {
   getCKBFSConfig(): CKBFSScriptConfig {
     return getCKBFSScriptConfig(this.network, this.version, this.useTypeID);
   }
-  
+
   /**
    * Publishes a file to CKBFS
    * @param filePath The path to the file to publish
    * @param options Options for publishing the file
    * @returns Promise resolving to the transaction hash
    */
-  async publishFile(filePath: string, options: FileOptions = {}): Promise<string> {
+  async publishFile(
+    filePath: string,
+    options: FileOptions = {},
+  ): Promise<string> {
     // Read the file and split into chunks
     const fileContent = readFileAsUint8Array(filePath);
     const contentChunks = [];
-    
+
     for (let i = 0; i < fileContent.length; i += this.chunkSize) {
       contentChunks.push(fileContent.slice(i, i + this.chunkSize));
     }
-    
+
     // Get the lock script
     const lock = await this.getLock();
-    
+
     // Determine content type if not provided
     const contentType = options.contentType || getContentType(filePath);
-    
+
     // Use the filename from the path if not provided
     const pathParts = filePath.split(/[\\\/]/);
     const filename = options.filename || pathParts[pathParts.length - 1];
-    
-    // Create and sign the transaction
-    const tx = await publishCKBFS(this.signer, {
+
+    // Create and sign the transaction using the utility function
+    const tx = await utilPublishCKBFS(this.signer, {
       contentChunks,
       contentType,
       filename,
@@ -186,79 +237,162 @@ export class CKBFS {
       feeRate: options.feeRate,
       network: options.network || this.network,
       version: options.version || this.version,
-      useTypeID: options.useTypeID !== undefined ? options.useTypeID : this.useTypeID
+      useTypeID:
+        options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
     });
 
-    console.log('tx', tx.stringify());
-    
+    console.log("Publish file tx:", tx.stringify());
+
     // Send the transaction
     const txHash = await this.signer.sendTransaction(tx);
-    
-    return txHash;
+
+    return ensureHexPrefix(txHash);
+  }
+
+  /**
+   * Publishes content (string or Uint8Array) directly to CKBFS
+   * @param content The content string or byte array to publish
+   * @param options Options for publishing the content (contentType and filename are required)
+   * @returns Promise resolving to the transaction hash
+   */
+  async publishContent(
+    content: string | Uint8Array,
+    options: PublishContentOptions,
+  ): Promise<string> {
+    const contentBytes =
+      typeof content === "string" ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    const lock = await this.getLock();
+
+    // Use provided contentType and filename (required)
+    const { contentType, filename } = options;
+
+    const tx = await utilPublishCKBFS(this.signer, {
+      contentChunks,
+      contentType,
+      filename,
+      lock,
+      capacity: options.capacity,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version,
+      useTypeID:
+        options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+    });
+
+    console.log("Publish content tx:", tx.stringify());
+
+    const txHash = await this.signer.sendTransaction(tx);
+    return ensureHexPrefix(txHash);
   }
-  
+
   /**
-   * Appends content to an existing CKBFS file
+   * Appends content from a file to an existing CKBFS file
    * @param filePath The path to the file containing the content to append
    * @param ckbfsCell The CKBFS cell to append to
    * @param options Additional options for the append operation
    * @returns Promise resolving to the transaction hash
    */
   async appendFile(
-    filePath: string, 
-    ckbfsCell: AppendOptions['ckbfsCell'], 
-    options: Omit<FileOptions, 'contentType' | 'filename'> = {}
+    filePath: string,
+    ckbfsCell: AppendOptions["ckbfsCell"],
+    options: Omit<FileOptions, "contentType" | "filename"> = {},
   ): Promise<string> {
     // Read the file and split into chunks
     const fileContent = readFileAsUint8Array(filePath);
     const contentChunks = [];
-    
+
     for (let i = 0; i < fileContent.length; i += this.chunkSize) {
       contentChunks.push(fileContent.slice(i, i + this.chunkSize));
     }
-    
-    // Create and sign the transaction
-    const tx = await appendCKBFS(this.signer, {
+
+    // Create and sign the transaction using the utility function
+    const tx = await utilAppendCKBFS(this.signer, {
       ckbfsCell,
       contentChunks,
       feeRate: options.feeRate,
       network: options.network || this.network,
-      version: options.version || this.version
+      version: options.version || this.version,
     });
-    
+
+    console.log("Append file tx:", tx.stringify());
+
     // Send the transaction
     const txHash = await this.signer.sendTransaction(tx);
-    
-    return txHash;
+
+    return ensureHexPrefix(txHash);
   }
-  
+
+  /**
+   * Appends content (string or Uint8Array) directly to an existing CKBFS file
+   * @param content The content string or byte array to append
+   * @param ckbfsCell The CKBFS cell to append to
+   * @param options Additional options for the append operation
+   * @returns Promise resolving to the transaction hash
+   */
+  async appendContent(
+    content: string | Uint8Array,
+    ckbfsCell: AppendOptions["ckbfsCell"],
+    options: AppendContentOptions = {},
+  ): Promise<string> {
+    const contentBytes =
+      typeof content === "string" ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    const tx = await utilAppendCKBFS(this.signer, {
+      ckbfsCell,
+      contentChunks,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version,
+      // No useTypeID option for append
+    });
+
+    console.log("Append content tx:", tx.stringify());
+
+    const txHash = await this.signer.sendTransaction(tx);
+    return ensureHexPrefix(txHash);
+  }
+
   /**
    * Creates a new transaction for publishing a file but doesn't sign or send it
    * @param filePath The path to the file to publish
    * @param options Options for publishing the file
    * @returns Promise resolving to the unsigned transaction
    */
-  async createPublishTransaction(filePath: string, options: FileOptions = {}): Promise<Transaction> {
+  async createPublishTransaction(
+    filePath: string,
+    options: FileOptions = {},
+  ): Promise<Transaction> {
     // Read the file and split into chunks
     const fileContent = readFileAsUint8Array(filePath);
     const contentChunks = [];
-    
+
     for (let i = 0; i < fileContent.length; i += this.chunkSize) {
       contentChunks.push(fileContent.slice(i, i + this.chunkSize));
     }
-    
+
     // Get the lock script
     const lock = await this.getLock();
-    
+
     // Determine content type if not provided
     const contentType = options.contentType || getContentType(filePath);
-    
+
     // Use the filename from the path if not provided
     const pathParts = filePath.split(/[\\\/]/);
     const filename = options.filename || pathParts[pathParts.length - 1];
-    
-    // Create the transaction
-    return createPublishTransaction(this.signer, {
+
+    // Create the transaction using the utility function
+    return utilCreatePublishTransaction(this.signer, {
       contentChunks,
       contentType,
       filename,
@@ -267,37 +401,105 @@ export class CKBFS {
       feeRate: options.feeRate,
       network: options.network || this.network,
       version: options.version || this.version,
-      useTypeID: options.useTypeID !== undefined ? options.useTypeID : this.useTypeID
+      useTypeID:
+        options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
     });
   }
-  
+
   /**
-   * Creates a new transaction for appending content but doesn't sign or send it
+   * Creates a new transaction for publishing content (string or Uint8Array) directly, but doesn't sign or send it
+   * @param content The content string or byte array to publish
+   * @param options Options for publishing the content (contentType and filename are required)
+   * @returns Promise resolving to the unsigned transaction
+   */
+  async createPublishContentTransaction(
+    content: string | Uint8Array,
+    options: PublishContentOptions,
+  ): Promise<Transaction> {
+    const contentBytes =
+      typeof content === "string" ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    const lock = await this.getLock();
+
+    // Use provided contentType and filename (required)
+    const { contentType, filename } = options;
+
+    return utilCreatePublishTransaction(this.signer, {
+      contentChunks,
+      contentType,
+      filename,
+      lock,
+      capacity: options.capacity,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version,
+      useTypeID:
+        options.useTypeID !== undefined ? options.useTypeID : this.useTypeID,
+    });
+  }
+
+  /**
+   * Creates a new transaction for appending content from a file but doesn't sign or send it
    * @param filePath The path to the file containing the content to append
    * @param ckbfsCell The CKBFS cell to append to
    * @param options Additional options for the append operation
    * @returns Promise resolving to the unsigned transaction
    */
   async createAppendTransaction(
-    filePath: string, 
-    ckbfsCell: AppendOptions['ckbfsCell'],
-    options: Omit<FileOptions, 'contentType' | 'filename'> = {}
+    filePath: string,
+    ckbfsCell: AppendOptions["ckbfsCell"],
+    options: Omit<FileOptions, "contentType" | "filename"> = {},
   ): Promise<Transaction> {
     // Read the file and split into chunks
     const fileContent = readFileAsUint8Array(filePath);
     const contentChunks = [];
-    
+
     for (let i = 0; i < fileContent.length; i += this.chunkSize) {
       contentChunks.push(fileContent.slice(i, i + this.chunkSize));
     }
-    
-    // Create the transaction
-    return createAppendTransaction(this.signer, {
+
+    // Create the transaction using the utility function
+    return utilCreateAppendTransaction(this.signer, {
       ckbfsCell,
       contentChunks,
       feeRate: options.feeRate,
       network: options.network || this.network,
-      version: options.version || this.version
+      version: options.version || this.version,
+    });
+  }
+
+  /**
+   * Creates a new transaction for appending content (string or Uint8Array) directly, but doesn't sign or send it
+   * @param content The content string or byte array to append
+   * @param ckbfsCell The CKBFS cell to append to
+   * @param options Additional options for the append operation
+   * @returns Promise resolving to the unsigned transaction
+   */
+  async createAppendContentTransaction(
+    content: string | Uint8Array,
+    ckbfsCell: AppendOptions["ckbfsCell"],
+    options: AppendContentOptions = {},
+  ): Promise<Transaction> {
+    const contentBytes =
+      typeof content === "string" ? textEncoder.encode(content) : content;
+    const contentChunks = [];
+
+    for (let i = 0; i < contentBytes.length; i += this.chunkSize) {
+      contentChunks.push(contentBytes.slice(i, i + this.chunkSize));
+    }
+
+    return utilCreateAppendTransaction(this.signer, {
+      ckbfsCell,
+      contentChunks,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version,
+      // No useTypeID option for append
     });
   }
 }
@@ -309,14 +511,14 @@ export {
   verifyChecksum,
   updateChecksum,
   verifyWitnessChecksum,
-  
-  // Transaction utilities
+
+  // Transaction utilities (Exporting original names from transaction.ts)
   createCKBFSCell,
-  createPublishTransaction,
-  createAppendTransaction,
-  publishCKBFS,
-  appendCKBFS,
-  
+  utilCreatePublishTransaction as createPublishTransaction,
+  utilCreateAppendTransaction as createAppendTransaction,
+  utilPublishCKBFS as publishCKBFS,
+  utilAppendCKBFS as appendCKBFS,
+
   // File utilities
   readFile,
   readFileAsText,
@@ -327,33 +529,47 @@ export {
   combineChunksToFile,
   getFileContentFromChain,
   saveFileFromChain,
-  
+  getFileContentFromChainByTypeId,
+  saveFileFromChainByTypeId,
+  decodeFileFromChainByTypeId,
+  getFileContentFromChainByIdentifier,
+  saveFileFromChainByIdentifier,
+  decodeFileFromChainByIdentifier,
+  parseIdentifier,
+  IdentifierType,
+  decodeWitnessContent,
+  decodeMultipleWitnessContents,
+  extractFileFromWitnesses,
+  decodeFileFromWitnessData,
+  saveFileFromWitnessData,
+
   // Witness utilities
   createCKBFSWitness,
   createTextCKBFSWitness,
   extractCKBFSWitnessContent,
   isCKBFSWitness,
   createChunkedCKBFSWitnesses,
-  
+
   // Molecule definitions
   CKBFSData,
   BackLinkV1,
   BackLinkV2,
-  
+
   // Types
   CKBFSDataType,
   BackLinkType,
   CKBFSCellOptions,
   PublishOptions,
   AppendOptions,
-  
+
   // Constants
   CKBFS_HEADER,
   CKBFS_HEADER_STRING,
-  
+
   // CKBFS Protocol Constants & Configuration
   NetworkType,
   ProtocolVersion,
+  ProtocolVersionType,
   DEFAULT_NETWORK,
   DEFAULT_VERSION,
   CKBFS_CODE_HASH,
@@ -363,5 +579,5 @@ export {
   DEP_GROUP_TX_HASH,
   DEPLOY_TX_HASH,
   getCKBFSScriptConfig,
-  CKBFSScriptConfig
-}; 
+  CKBFSScriptConfig,
+};