@ckbfs/api 1.0.0

package/examples/index.ts

@@ -0,0 +1,43 @@
+import { CKBFS, NetworkType, ProtocolVersion } from '../src/index';
+
+/**
+ * Main CKBFS Examples
+ * 
+ * This file serves as the entry point for running all CKBFS SDK examples.
+ * 
+ * To run all examples:
+ *   npm run example
+ * 
+ * To run specific examples:
+ *   npm run example:publish
+ *   npm run example:append -- --txhash=0x123456...
+ */
+
+console.log('CKBFS SDK Examples');
+console.log('=================');
+console.log('');
+console.log('Available examples:');
+console.log('1. Publish File Example - npm run example:publish');
+console.log('2. Append File Example  - npm run example:append -- --txhash=0x123456...');
+console.log('');
+console.log('Run all examples with: npm run example');
+console.log('');
+console.log('Note: For the append example, you need to provide a transaction hash');
+console.log('of a previously published file using the --txhash parameter or');
+console.log('by setting the PUBLISH_TX_HASH environment variable.');
+console.log('');
+
+// Check if we should run all examples
+const runAll = process.argv.includes('--all');
+
+if (runAll) {
+  console.log('Running all examples is not recommended. Please run specific examples instead.');
+  console.log('');
+  console.log('For example:');
+  console.log('  npm run example:publish');
+  console.log('  npm run example:append -- --txhash=0x123456...');
+  process.exit(1);
+}
+
+// Default behavior - just show instructions
+console.log('For more information, see the README.md file.'); 

package/examples/publish.ts

@@ -0,0 +1,76 @@
+import { CKBFS, NetworkType, ProtocolVersion } from '../src/index';
+
+// Replace with your actual private key
+const privateKey = process.env.CKB_PRIVATE_KEY || 'your-private-key-here';
+
+// Initialize the SDK with network and version options
+const ckbfs = new CKBFS(
+  privateKey,
+  NetworkType.Testnet, // Use testnet
+  {
+    version: ProtocolVersion.V2, // Use the latest version (V2)
+    chunkSize: 30 * 1024, // 30KB chunks
+    useTypeID: false // Use code hash instead of type ID
+  }
+);
+
+/**
+ * Example of publishing a file to CKBFS
+ */
+async function publishExample() {
+  try {
+    // Get address info
+    const address = await ckbfs.getAddress();
+    console.log(`Using address: ${address.toString()}`);
+    
+    // Get CKBFS script config
+    const config = ckbfs.getCKBFSConfig();
+    console.log('Using CKBFS config:', config);
+    
+    // Publish a text file to CKBFS
+    const filePath = './example.txt';
+    
+    // You can provide additional options
+    const options = {
+      contentType: 'text/plain',
+      filename: 'example.txt',
+      // Specify capacity if needed (default is 200 CKB)
+      // capacity: 250n * 100000000n
+    };
+    
+    console.log(`Publishing file: ${filePath}`);
+    const txHash = await ckbfs.publishFile(filePath, options);
+    
+    console.log(`File 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 file:', error);
+    throw error;
+  }
+}
+
+/**
+ * Main function to run the example
+ */
+async function main() {
+  console.log('Running CKBFS publishing example...');
+  console.log('----------------------------------');
+  console.log(`Using CKBFS protocol version: ${ProtocolVersion.V2}`);
+  
+  try {
+    await publishExample();
+    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

@@ -0,0 +1,39 @@
+{
+  "name": "@ckbfs/api",
+  "version": "1.0.0",
+  "description": "SDK for CKBFS protocol on CKB",
+  "license": "MIT",
+  "author": "Code Monad<code@lab-11.org>",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "test": "jest",
+    "example": "ts-node examples/index.ts",
+    "example:publish": "ts-node examples/publish.ts",
+    "example:append": "ts-node examples/append.ts"
+  },
+  "keywords": [
+    "ckb",
+    "ckbfs",
+    "nervos",
+    "sdk"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.7.9",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "@types/jest": "^29.5.12"
+  },
+  "dependencies": {
+    "@ckb-ccc/core": "^0.1.0-alpha.4",
+    "@ckb-lumos/base": "^0.23.0",
+    "@ckb-lumos/codec": "^0.23.0",
+    "hash-wasm": "^4.11.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,363 @@
+import { Script, Signer, Transaction, ClientPublicTestnet, SignerCkbPrivateKey } 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 {
+  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';
+
+/**
+ * Custom options for file publishing and appending
+ */
+export interface FileOptions {
+  contentType?: string;
+  filename?: string;
+  capacity?: bigint;
+  feeRate?: number;
+  network?: NetworkType;
+  version?: string;
+  useTypeID?: boolean;
+}
+
+/**
+ * Configuration options for the CKBFS SDK
+ */
+export interface CKBFSOptions {
+  chunkSize?: number;
+  version?: string;
+  useTypeID?: boolean;
+  network?: NetworkType;
+}
+
+/**
+ * Main CKBFS SDK class
+ */
+export class CKBFS {
+  private signer: Signer;
+  private chunkSize: number;
+  private network: NetworkType;
+  private version: string;
+  private useTypeID: boolean;
+  
+  /**
+   * Creates a new CKBFS SDK instance
+   * @param signerOrPrivateKey The signer instance or CKB private key to use for signing transactions
+   * @param networkOrOptions The network type or configuration options
+   * @param options Additional configuration options when using privateKey
+   */
+  constructor(
+    signerOrPrivateKey: Signer | string,
+    networkOrOptions: NetworkType | CKBFSOptions = DEFAULT_NETWORK,
+    options?: CKBFSOptions
+  ) {
+    // Determine if first parameter is a Signer or privateKey
+    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 client = new ClientPublicTestnet();
+      this.signer = new SignerCkbPrivateKey(client, privateKey);
+      this.network = network;
+      this.chunkSize = opts.chunkSize || 30 * 1024;
+      this.version = opts.version || DEFAULT_VERSION;
+      this.useTypeID = opts.useTypeID || false;
+    } else {
+      // Initialize with signer
+      this.signer = signerOrPrivateKey;
+      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
+   */
+  async getAddress() {
+    return this.signer.getRecommendedAddressObj();
+  }
+  
+  /**
+   * Gets the lock script for the signer
+   * @returns Promise resolving to the lock script
+   */
+  async getLock(): Promise<Script> {
+    const address = await this.getAddress();
+    return address.script;
+  }
+  
+  /**
+   * Gets the CKBFS script configuration for the current settings
+   * @returns The CKBFS script configuration
+   */
+  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> {
+    // 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, {
+      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('tx', tx.stringify());
+    
+    // Send the transaction
+    const txHash = await this.signer.sendTransaction(tx);
+    
+    return txHash;
+  }
+  
+  /**
+   * Appends content 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'> = {}
+  ): 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, {
+      ckbfsCell,
+      contentChunks,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version
+    });
+    
+    // Send the transaction
+    const txHash = await this.signer.sendTransaction(tx);
+    
+    return 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> {
+    // 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, {
+      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 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'> = {}
+  ): 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, {
+      ckbfsCell,
+      contentChunks,
+      feeRate: options.feeRate,
+      network: options.network || this.network,
+      version: options.version || this.version
+    });
+  }
+}
+
+// Export utility functions
+export {
+  // Checksum utilities
+  calculateChecksum,
+  verifyChecksum,
+  updateChecksum,
+  verifyWitnessChecksum,
+  
+  // Transaction utilities
+  createCKBFSCell,
+  createPublishTransaction,
+  createAppendTransaction,
+  publishCKBFS,
+  appendCKBFS,
+  
+  // File utilities
+  readFile,
+  readFileAsText,
+  readFileAsUint8Array,
+  writeFile,
+  getContentType,
+  splitFileIntoChunks,
+  combineChunksToFile,
+  
+  // 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,
+  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/src/utils/checksum.ts

@@ -0,0 +1,74 @@
+import { adler32 } from 'hash-wasm';
+
+/**
+ * Utility functions for Adler32 checksum generation and verification
+ */
+
+/**
+ * Calculates Adler32 checksum for the provided data
+ * @param data The data to calculate checksum for
+ * @returns Promise resolving to the calculated checksum as a number
+ */
+export async function calculateChecksum(data: Uint8Array): Promise<number> {
+  const checksumString = await adler32(data);
+  const checksumBuffer = Buffer.from(checksumString, 'hex');
+  return checksumBuffer.readUInt32BE();
+}
+
+/**
+ * Updates an existing checksum with new data
+ * @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
+ */
+export async function updateChecksum(previousChecksum: number, newData: Uint8Array): Promise<number> {
+  // 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);
+}
+
+/**
+ * Verifies if a given checksum matches the expected checksum for the data
+ * @param data The data to verify
+ * @param expectedChecksum The expected checksum
+ * @returns Promise resolving to a boolean indicating whether the checksum is valid
+ */
+export async function verifyChecksum(data: Uint8Array, expectedChecksum: number): Promise<boolean> {
+  const calculatedChecksum = await calculateChecksum(data);
+  return calculatedChecksum === expectedChecksum;
+}
+
+/**
+ * Verifies the checksum of a CKBFS witness
+ * @param witness The witness bytes
+ * @param expectedChecksum The expected checksum
+ * @param backlinks Optional backlinks to use for checksum verification
+ * @returns Promise resolving to a boolean indicating whether the checksum is valid
+ */
+export async function verifyWitnessChecksum(
+  witness: Uint8Array, 
+  expectedChecksum: number,
+  backlinks: { checksum: number }[] = []
+): Promise<boolean> {
+  // Extract the content bytes from the witness (skip the CKBFS header and version)
+  const contentBytes = witness.slice(6);
+  
+  // If backlinks are provided, use the last backlink's checksum
+  if (backlinks.length > 0) {
+    const lastBacklink = backlinks[backlinks.length - 1];
+    const updatedChecksum = await updateChecksum(lastBacklink.checksum, contentBytes);
+    return updatedChecksum === expectedChecksum;
+  }
+  
+  // Otherwise, calculate checksum from scratch
+  return verifyChecksum(contentBytes, expectedChecksum);
+}