@ckbfs/api 1.2.3 → 1.3.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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 { createCKBFSCell, createPublishTransaction as utilCreatePublishTransaction, createAppendTransaction as utilCreateAppendTransaction, publishCKBFS as utilPublishCKBFS, appendCKBFS as utilAppendCKBFS, CKBFSCellOptions, PublishOptions, AppendOptions } from './utils/transaction';
 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';
@@ -17,6 +17,18 @@ export interface FileOptions {
     version?: string;
     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
  */
@@ -65,13 +77,28 @@ export declare class CKBFS {
      */
     publishFile(filePath: string, options?: FileOptions): Promise<string>;
     /**
-     * Appends content to an existing CKBFS file
+     * 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
+     */
+    publishContent(content: string | Uint8Array, options: PublishContentOptions): Promise<string>;
+    /**
+     * 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
      */
     appendFile(filePath: string, ckbfsCell: AppendOptions['ckbfsCell'], options?: Omit<FileOptions, 'contentType' | 'filename'>): Promise<string>;
+    /**
+     * 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
+     */
+    appendContent(content: string | Uint8Array, ckbfsCell: AppendOptions['ckbfsCell'], options?: AppendContentOptions): Promise<string>;
     /**
      * Creates a new transaction for publishing a file but doesn't sign or send it
      * @param filePath The path to the file to publish
@@ -80,12 +107,27 @@ export declare class CKBFS {
      */
     createPublishTransaction(filePath: string, options?: FileOptions): Promise<Transaction>;
     /**
-     * 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
+     */
+    createPublishContentTransaction(content: string | Uint8Array, options: PublishContentOptions): Promise<Transaction>;
+    /**
+     * 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
      */
     createAppendTransaction(filePath: string, ckbfsCell: AppendOptions['ckbfsCell'], options?: Omit<FileOptions, 'contentType' | 'filename'>): Promise<Transaction>;
+    /**
+     * 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
+     */
+    createAppendContentTransaction(content: string | Uint8Array, ckbfsCell: AppendOptions['ckbfsCell'], options?: AppendContentOptions): Promise<Transaction>;
 }
-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 };
+export { calculateChecksum, verifyChecksum, updateChecksum, verifyWitnessChecksum, createCKBFSCell, utilCreatePublishTransaction as createPublishTransaction, utilCreateAppendTransaction as createAppendTransaction, utilPublishCKBFS as publishCKBFS, utilAppendCKBFS as 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

@@ -47,6 +47,9 @@ Object.defineProperty(exports, "ADLER32_TYPE_ID", { enumerable: true, get: funct
 Object.defineProperty(exports, "DEP_GROUP_TX_HASH", { enumerable: true, get: function () { return constants_1.DEP_GROUP_TX_HASH; } });
 Object.defineProperty(exports, "DEPLOY_TX_HASH", { enumerable: true, get: function () { return constants_1.DEPLOY_TX_HASH; } });
 Object.defineProperty(exports, "getCKBFSScriptConfig", { enumerable: true, get: function () { return constants_1.getCKBFSScriptConfig; } });
+const transaction_2 = require("./utils/transaction");
+// Helper to encode string to Uint8Array
+const textEncoder = new TextEncoder();
 /**
  * Main CKBFS SDK class
  */
@@ -123,7 +126,7 @@ class CKBFS {
         // 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
+        // Create and sign the transaction using the utility function
         const tx = await (0, transaction_1.publishCKBFS)(this.signer, {
             contentChunks,
             contentType,
@@ -135,13 +138,43 @@ class CKBFS {
             version: options.version || this.version,
             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 (0, transaction_2.ensureHexPrefix)(txHash);
     }
     /**
-     * Appends content to an existing CKBFS file
+     * 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, options) {
+        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 (0, transaction_1.publishCKBFS)(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 (0, transaction_2.ensureHexPrefix)(txHash);
+    }
+    /**
+     * 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
@@ -154,7 +187,7 @@ class CKBFS {
         for (let i = 0; i < fileContent.length; i += this.chunkSize) {
             contentChunks.push(fileContent.slice(i, i + this.chunkSize));
         }
-        // Create and sign the transaction
+        // Create and sign the transaction using the utility function
         const tx = await (0, transaction_1.appendCKBFS)(this.signer, {
             ckbfsCell,
             contentChunks,
@@ -162,9 +195,35 @@ class CKBFS {
             network: options.network || this.network,
             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 (0, transaction_2.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, ckbfsCell, options = {}) {
+        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 (0, transaction_1.appendCKBFS)(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 (0, transaction_2.ensureHexPrefix)(txHash);
     }
     /**
      * Creates a new transaction for publishing a file but doesn't sign or send it
@@ -186,7 +245,34 @@ class CKBFS {
         // Use the filename from the path if not provided
         const pathParts = filePath.split(/[\\\/]/);
         const filename = options.filename || pathParts[pathParts.length - 1];
-        // Create the transaction
+        // Create the transaction using the utility function
+        return (0, transaction_1.createPublishTransaction)(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 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, options) {
+        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 (0, transaction_1.createPublishTransaction)(this.signer, {
             contentChunks,
             contentType,
@@ -200,7 +286,7 @@ class CKBFS {
         });
     }
     /**
-     * Creates a new transaction for appending content but doesn't sign or send it
+     * 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
@@ -213,13 +299,35 @@ class CKBFS {
         for (let i = 0; i < fileContent.length; i += this.chunkSize) {
             contentChunks.push(fileContent.slice(i, i + this.chunkSize));
         }
-        // Create the transaction
+        // Create the transaction using the utility function
+        return (0, transaction_1.createAppendTransaction)(this.signer, {
+            ckbfsCell,
+            contentChunks,
+            feeRate: options.feeRate,
+            network: options.network || this.network,
+            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, ckbfsCell, options = {}) {
+        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 (0, transaction_1.createAppendTransaction)(this.signer, {
             ckbfsCell,
             contentChunks,
             feeRate: options.feeRate,
             network: options.network || this.network,
             version: options.version || this.version
+            // No useTypeID option for append
         });
     }
 }

package/dist/utils/transaction.d.ts

@@ -42,6 +42,12 @@ export interface AppendOptions {
     network?: NetworkType;
     version?: string;
 }
+/**
+ * Ensures a string is prefixed with '0x'
+ * @param value The string to ensure is hex prefixed
+ * @returns A hex prefixed string
+ */
+export declare function ensureHexPrefix(value: string): `0x${string}`;
 /**
  * Creates a CKBFS cell
  * @param options Options for creating the CKBFS cell

package/dist/utils/transaction.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureHexPrefix = ensureHexPrefix;
 exports.createCKBFSCell = createCKBFSCell;
 exports.createPublishTransaction = createPublishTransaction;
 exports.createAppendTransaction = createAppendTransaction;
@@ -168,10 +169,12 @@ async function createAppendTransaction(signer, options) {
     // 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`);
+    // Get the recommended address to ensure lock script cell deps are included
+    const address = await signer.getRecommendedAddressObj();
     // 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;
+    // CKBFS data starts at index 1 if signer's lock script is the same as ckbfs's lock script
+    // else CKBFS data starts at index 0
+    const contentStartIndex = address.script.hash() === lock.hash() ? 1 : 0;
     const witnessIndices = Array.from({ length: contentChunks.length }, (_, i) => contentStartIndex + i);
     // Create backlink for the current state based on version
     let newBackLink;
@@ -266,8 +269,6 @@ async function createAppendTransaction(signer, options) {
         },
         depType: "depGroup"
     });
-    // Get the recommended address to ensure lock script cell deps are included
-    const address = await signer.getRecommendedAddressObj();
     const inputsBefore = tx.inputs.length;
     // If we need more capacity than the original cell had, add additional inputs
     if (outputCapacity > capacity) {

package/example.txt

@@ -1 +1 @@
-Hello, CKBFS! This is a sample file published using 20240906.ce6724722cf6 protocol.
+hello, world

package/examples/append.ts

@@ -1,4 +1,4 @@
-import { CKBFS, NetworkType, ProtocolVersion, CKBFSDataType, extractCKBFSWitnessContent, isCKBFSWitness, CKBFSData } from '../src/index';
+import { CKBFS, NetworkType, ProtocolVersion, CKBFSDataType, extractCKBFSWitnessContent, isCKBFSWitness, CKBFSData, AppendContentOptions } from '../src/index';
 import { Script, ClientPublicTestnet, Transaction, ccc } from "@ckb-ccc/core";
 
 // Replace with your actual private key
@@ -169,6 +169,37 @@ async function appendExample() {
   }
 }
 
+/**
+ * Example of appending content directly (string) to an existing CKBFS file
+ * @param previousAppendTxHash The transaction hash from the previous append operation
+ */
+async function appendContentExample(previousAppendTxHash: string) {
+  try {
+    console.log(`Getting cell info from previous append transaction: ${previousAppendTxHash}`);
+    const ckbfsCell = await getCellInfoFromTransaction(previousAppendTxHash);
+    
+    const contentToAppend = "\nAnd this is more content appended directly as a string!";
+    const options: AppendContentOptions = {
+      // You can optionally specify feeRate, network, version
+      // feeRate: 3000 
+    };
+    
+    console.log(`Appending direct content: "${contentToAppend}"`);
+    
+    // Append the string content
+    const txHash = await ckbfs.appendContent(contentToAppend, ckbfsCell, options);
+    
+    console.log(`Direct content appended successfully!`);
+    console.log(`Transaction Hash: ${txHash}`);
+    console.log(`View at: https://pudge.explorer.nervos.org/transaction/${txHash}`);
+    
+    return txHash;
+  } catch (error) {
+    console.error('Error appending direct content:', error);
+    throw error;
+  }
+}
+
 /**
  * Main function to run the example
  */
@@ -178,7 +209,13 @@ async function main() {
   console.log(`Using CKBFS protocol version: ${ProtocolVersion.V2}`);
   
   try {
-    await appendExample();
+    // Run the file append first
+    const firstAppendTxHash = await appendExample();
+    console.log('-------------------------------');
+    
+    // Now run the content append, using the output from the first append
+    await appendContentExample(firstAppendTxHash);
+    
     console.log('Example completed successfully!');
     process.exit(0);
   } catch (error) {

package/examples/publish.ts

@@ -1,4 +1,4 @@
-import { CKBFS, NetworkType, ProtocolVersion } from '../src/index';
+import { CKBFS, NetworkType, ProtocolVersion, PublishContentOptions } from '../src/index';
 
 // Replace with your actual private key
 const privateKey = process.env.CKB_PRIVATE_KEY || 'your-private-key-here';
@@ -52,6 +52,38 @@ async function publishExample() {
   }
 }
 
+/**
+ * Example of publishing content directly (string) to CKBFS
+ */
+async function publishContentExample() {
+  try {
+    // Get address info
+    const address = await ckbfs.getAddress();
+    console.log(`Using address for content publish: ${address.toString()}`);
+    
+    // Define content and options (contentType and filename are required)
+    const content = "Hello CKBFS from direct content!";
+    const options: PublishContentOptions = {
+      contentType: 'text/plain',
+      filename: 'direct_content_example.txt',
+      // You can optionally specify feeRate, network, version, useTypeID
+      // feeRate: 3000 
+    };
+    
+    console.log(`Publishing direct content: "${content}"`);
+    const txHash = await ckbfs.publishContent(content, options);
+    
+    console.log(`Direct content published successfully!`);
+    console.log(`Transaction Hash: ${txHash}`);
+    console.log(`View at: https://pudge.explorer.nervos.org/transaction/${txHash}`);
+    
+    return txHash;
+  } catch (error) {
+    console.error('Error publishing direct content:', error);
+    throw error;
+  }
+}
+
 /**
  * Main function to run the example
  */
@@ -62,6 +94,8 @@ async function main() {
   
   try {
     await publishExample();
+    console.log('----------------------------------');
+    await publishContentExample();
     console.log('Example completed successfully!');
     process.exit(0);
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckbfs/api",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "SDK for CKBFS protocol on CKB",
   "license": "MIT",
   "author": "Code Monad<code@lab-11.org>",