@ckbfs/api 1.5.0 → 2.0.0

package/dist/utils/witness.js

@@ -4,11 +4,12 @@ exports.createCKBFSWitness = createCKBFSWitness;
 exports.createTextCKBFSWitness = createTextCKBFSWitness;
 exports.extractCKBFSWitnessContent = extractCKBFSWitnessContent;
 exports.isCKBFSWitness = isCKBFSWitness;
+exports.createCKBFSV3Witness = createCKBFSV3Witness;
+exports.createChunkedCKBFSV3Witnesses = createChunkedCKBFSV3Witnesses;
+exports.extractCKBFSV3WitnessContent = extractCKBFSV3WitnessContent;
+exports.isCKBFSV3Witness = isCKBFSV3Witness;
 exports.createChunkedCKBFSWitnesses = createChunkedCKBFSWitnesses;
 const molecule_1 = require("./molecule");
-/**
- * Utility functions for creating and handling CKBFS witnesses
- */
 /**
  * Creates a CKBFS witness with content
  * @param content The content to include in the witness
@@ -62,6 +63,147 @@ function isCKBFSWitness(witness) {
     const headerString = new TextDecoder().decode(header);
     return headerString === 'CKBFS';
 }
+/**
+ * Creates a CKBFS v3 witness with structured format
+ * @param options Witness options including backlink data and content
+ * @returns Uint8Array containing the v3 witness data
+ */
+function createCKBFSV3Witness(options) {
+    const { previousTxHash = '0x' + '00'.repeat(32), previousWitnessIndex = 0, previousChecksum = 0, nextIndex = 0, content } = options;
+    // Create witness components
+    const header = molecule_1.CKBFS_HEADER; // "CKBFS" (5 bytes)
+    const version = new Uint8Array([0x03]); // Version 3 (1 byte)
+    // Previous position: txHash (32 bytes) + witnessIndex (4 bytes)
+    const prevTxHashBytes = new Uint8Array(32);
+    if (previousTxHash !== '0x' + '00'.repeat(32)) {
+        const hexStr = previousTxHash.startsWith('0x') ? previousTxHash.slice(2) : previousTxHash;
+        for (let i = 0; i < 32; i++) {
+            prevTxHashBytes[i] = parseInt(hexStr.substr(i * 2, 2), 16);
+        }
+    }
+    const prevWitnessIndexBytes = new Uint8Array(4);
+    new DataView(prevWitnessIndexBytes.buffer).setUint32(0, previousWitnessIndex, true); // little-endian
+    // Previous checksum (4 bytes)
+    const prevChecksumBytes = new Uint8Array(4);
+    new DataView(prevChecksumBytes.buffer).setUint32(0, previousChecksum, true); // little-endian
+    // Next index (4 bytes)
+    const nextIndexBytes = new Uint8Array(4);
+    new DataView(nextIndexBytes.buffer).setUint32(0, nextIndex, true); // little-endian
+    // Combine all parts
+    return Buffer.concat([
+        header, // 5 bytes: "CKBFS"
+        version, // 1 byte: 0x03
+        prevTxHashBytes, // 32 bytes: previous tx hash
+        prevWitnessIndexBytes, // 4 bytes: previous witness index
+        prevChecksumBytes, // 4 bytes: previous checksum
+        nextIndexBytes, // 4 bytes: next index
+        content // variable: content bytes
+    ]);
+}
+/**
+ * Creates an array of v3 witnesses for chunked content
+ * @param contentChunks Array of content chunks
+ * @param options Backlink options for head witness and start index
+ * @returns Array of Uint8Array witnesses
+ */
+function createChunkedCKBFSV3Witnesses(contentChunks, options = {}) {
+    if (contentChunks.length === 0) {
+        return [];
+    }
+    // Default start index to 1 if not provided (witness 0 is typically for signing)
+    const startIndex = options.startIndex || 1;
+    const witnesses = [];
+    for (let i = 0; i < contentChunks.length; i++) {
+        const isHead = i === 0;
+        const isTail = i === contentChunks.length - 1;
+        if (isHead) {
+            // Head witness with backlink info
+            witnesses.push(createCKBFSV3Witness({
+                ...options,
+                nextIndex: isTail ? 0 : startIndex + i + 1, // Correct next witness index calculation
+                content: contentChunks[i]
+            }));
+        }
+        else {
+            // Middle/tail witness with minimal header
+            const nextIndex = isTail ? 0 : startIndex + i + 1;
+            const nextIndexBytes = new Uint8Array(4);
+            new DataView(nextIndexBytes.buffer).setUint32(0, nextIndex, true);
+            witnesses.push(Buffer.concat([
+                nextIndexBytes, // 4 bytes: next index
+                contentChunks[i] // variable: content bytes
+            ]));
+        }
+    }
+    return witnesses;
+}
+/**
+ * Extracts content from a CKBFS v3 witness
+ * @param witness The CKBFS v3 witness data
+ * @param isHeadWitness Whether this is the head witness or a continuation witness
+ * @returns Object containing the extracted data
+ */
+function extractCKBFSV3WitnessContent(witness, isHeadWitness = true) {
+    if (isHeadWitness) {
+        // Head witness format: CKBFS(5) + version(1) + prevTxHash(32) + prevWitnessIndex(4) + prevChecksum(4) + nextIndex(4) + content
+        if (witness.length < 50) {
+            throw new Error('Invalid CKBFS v3 head witness: too short');
+        }
+        const header = witness.slice(0, 5);
+        const headerString = new TextDecoder().decode(header);
+        if (headerString !== 'CKBFS') {
+            throw new Error('Invalid CKBFS v3 head witness: missing CKBFS header');
+        }
+        const version = witness[5];
+        if (version !== 0x03) {
+            throw new Error(`Invalid CKBFS v3 head witness: expected version 0x03, got 0x${version.toString(16)}`);
+        }
+        // Extract previous position
+        const prevTxHashBytes = witness.slice(6, 38);
+        const previousTxHash = '0x' + Array.from(prevTxHashBytes).map(b => b.toString(16).padStart(2, '0')).join('');
+        const previousWitnessIndex = new DataView(witness.slice(38, 42).buffer).getUint32(0, true);
+        const previousChecksum = new DataView(witness.slice(42, 46).buffer).getUint32(0, true);
+        const nextIndex = new DataView(witness.slice(46, 50).buffer).getUint32(0, true);
+        const content = witness.slice(50);
+        return {
+            version,
+            previousTxHash,
+            previousWitnessIndex,
+            previousChecksum,
+            nextIndex,
+            content
+        };
+    }
+    else {
+        // Continuation witness format: nextIndex(4) + content
+        if (witness.length < 4) {
+            throw new Error('Invalid CKBFS v3 continuation witness: too short');
+        }
+        const nextIndex = new DataView(witness.slice(0, 4).buffer).getUint32(0, true);
+        const content = witness.slice(4);
+        return {
+            nextIndex,
+            content
+        };
+    }
+}
+/**
+ * Checks if a witness is a valid CKBFS v3 witness
+ * @param witness The witness data to check
+ * @returns Boolean indicating whether the witness is a valid CKBFS v3 witness
+ */
+function isCKBFSV3Witness(witness) {
+    if (witness.length < 50) {
+        return false;
+    }
+    const header = witness.slice(0, 5);
+    const headerString = new TextDecoder().decode(header);
+    if (headerString !== 'CKBFS') {
+        return false;
+    }
+    const version = witness[5];
+    return version === 0x03;
+}
 /**
  * Creates an array of witnesses for a CKBFS transaction from content chunks
  * @param contentChunks Array of content chunks

package/examples/append-v3.ts

@@ -0,0 +1,310 @@
+import { CKBFS, NetworkType, ProtocolVersion, CKBFSDataType, extractCKBFSV3WitnessContent, isCKBFSV3Witness, CKBFSData } from '../src/index';
+import { Script, ClientPublicTestnet, Transaction, ccc } from "@ckb-ccc/core";
+
+// Replace with your actual private key
+const privateKey = process.env.CKB_PRIVATE_KEY || 'your-private-key-here';
+
+// Parse command line arguments for transaction hash
+const txHashArg = process.argv.find(arg => arg.startsWith('--txhash='));
+const publishTxHash = txHashArg ? txHashArg.split('=')[1] : process.env.PUBLISH_TX_HASH || '0x0000000000000000000000000000000000000000000000000000000000000000';
+
+/**
+ * Ensures a string is prefixed with '0x'
+ * @param value The string to ensure is hex prefixed
+ * @returns A hex prefixed string
+ */
+function ensureHexPrefix(value: string): `0x${string}` {
+  if (value.startsWith('0x')) {
+    return value as `0x${string}`;
+  }
+  return `0x${value}` as `0x${string}`;
+}
+
+// Initialize the SDK for CKBFS v3
+const ckbfs = new CKBFS(
+  privateKey,
+  NetworkType.Testnet, // Use testnet
+  {
+    version: ProtocolVersion.V3, // Use v3
+    chunkSize: 20 * 1024, // 20KB chunks
+    useTypeID: false, // Use code hash instead of type ID
+  }
+);
+
+// Initialize CKB client for testnet
+const client = new ClientPublicTestnet();
+
+/**
+ * Get cell information from a v3 transaction using CKB client
+ * @param txHash The transaction hash to get cell information from
+ * @returns Promise resolving to the cell information including v3 backlink data
+ */
+async function getCellInfoFromV3Transaction(txHash: string): Promise<{ 
+  outPoint: { txHash: string; index: number };
+  type: Script; 
+  data: CKBFSDataType;
+  lock: Script;
+  capacity: bigint;
+  previousTxHash: string;
+  previousWitnessIndex: number;
+  previousChecksum: number;
+}> {
+  console.log(`Retrieving v3 transaction data for: ${txHash}`);
+  
+  try {
+    // Get transaction from RPC
+    const txWithStatus = await client.getTransaction(txHash);
+    if (!txWithStatus || !txWithStatus.transaction) {
+      throw new Error(`Transaction ${txHash} not found`);
+    }
+    
+    const tx = Transaction.from(txWithStatus.transaction);
+    console.log(`Transaction found with ${tx.outputs.length} outputs`);
+    
+    // Find the CKBFS cell output (first output with type script)
+    let ckbfsCellIndex = 0;
+    const output = tx.outputs[ckbfsCellIndex];
+    if (!output || !output.type) {
+      throw new Error('No CKBFS cell found in the transaction');
+    }
+    
+    console.log(`Found CKBFS v3 cell at index ${ckbfsCellIndex}`);
+    console.log(`Cell type script hash: ${output.type.hash()}`);
+    
+    // Get output data
+    const outputData = tx.outputsData[ckbfsCellIndex];
+    if (!outputData) {
+      throw new Error('Output data not found');
+    }
+    
+    // Parse the output data as CKBFS v3 data
+    const rawData = outputData.startsWith('0x') 
+      ? ccc.bytesFrom(outputData.slice(2), 'hex')
+      : Buffer.from(outputData, 'hex');
+    
+    // Unpack the raw data using v3 format
+    const version = ProtocolVersion.V3;
+    console.log(`Using protocol version ${version} for unpacking v3 cell data`);
+    
+    let ckbfsData: CKBFSDataType;
+    try {
+      ckbfsData = CKBFSData.unpack(rawData, version);
+      
+      console.log('Successfully unpacked CKBFS v3 cell data:');
+      console.log(`- Checksum: ${ckbfsData.checksum}`);
+      console.log(`- File: ${ckbfsData.filename}`);
+      console.log(`- Content Type: ${ckbfsData.contentType}`);
+      console.log(`- Index: ${ckbfsData.index}`);
+    } catch (error) {
+      console.error('Error unpacking CKBFS v3 data:', error);
+      throw new Error(`Failed to unpack CKBFS v3 data: ${error}`);
+    }
+    
+    // Extract backlink information from v3 witness
+    let previousTxHash = '0x' + '00'.repeat(32);
+    let previousWitnessIndex = 0;
+    let previousChecksum = 0;
+    
+    if (ckbfsData.index !== undefined && ckbfsData.index < tx.witnesses.length) {
+      const witnessHex = tx.witnesses[ckbfsData.index];
+      const witness = Buffer.from(witnessHex.slice(2), 'hex');
+      
+      if (isCKBFSV3Witness(witness)) {
+        try {
+          const witnessData = extractCKBFSV3WitnessContent(witness, true);
+          previousTxHash = witnessData.previousTxHash || previousTxHash;
+          previousWitnessIndex = witnessData.previousWitnessIndex || 0;
+          previousChecksum = witnessData.previousChecksum || 0;
+          
+          console.log('Extracted v3 backlink information:');
+          console.log(`- Previous TX Hash: ${previousTxHash}`);
+          console.log(`- Previous Witness Index: ${previousWitnessIndex}`);
+          console.log(`- Previous Checksum: ${previousChecksum}`);
+        } catch (error) {
+          console.warn('Could not extract backlink info from witness:', error);
+        }
+      }
+    }
+    
+    return {
+      outPoint: {
+        txHash,
+        index: ckbfsCellIndex
+      },
+      type: output.type,
+      lock: output.lock,
+      capacity: output.capacity,
+      data: ckbfsData,
+      previousTxHash,
+      previousWitnessIndex,
+      previousChecksum
+    };
+  } catch (error) {
+    console.error('Error retrieving v3 transaction data:', error);
+    throw new Error(`Failed to retrieve or parse v3 cell data: ${error}`);
+  }
+}
+
+/**
+ * Example of appending content to an existing CKBFS v3 file
+ */
+async function appendContentV3Example() {
+  try {
+    // Validate transaction hash
+    if (publishTxHash === '0x0000000000000000000000000000000000000000000000000000000000000000') {
+      throw new Error('Please provide a valid transaction hash by setting the PUBLISH_TX_HASH environment variable or using --txhash=0x... argument');
+    }
+    
+    // Get address info
+    const address = await ckbfs.getAddress();
+    console.log(`Using address: ${address.toString()}`);
+    
+    // Get the cell information from the v3 transaction
+    console.log(`Getting v3 cell info from transaction: ${publishTxHash}`);
+    const cellInfo = await getCellInfoFromV3Transaction(publishTxHash);
+    
+    // Create the CKBFS v3 cell structure
+    const ckbfsCell = {
+      outPoint: cellInfo.outPoint,
+      data: cellInfo.data,
+      type: cellInfo.type,
+      lock: cellInfo.lock,
+      capacity: cellInfo.capacity
+    };
+    
+    // Content to append
+    const contentToAppend = "\n\nThis content was appended using CKBFS v3!";
+    console.log(`Appending content to CKBFS v3 file: "${contentToAppend}"`);
+    
+    console.log('Note: CKBFS v3 append requires backlink information from the previous transaction.');
+    console.log('The SDK will create witnesses with structured backlinks.');
+    console.log('Make sure your account has enough CKB to cover the fees.');
+    
+    const txHash = await ckbfs.appendContentV3(
+      contentToAppend,
+      ckbfsCell,
+      publishTxHash,
+      cellInfo.data.index!,
+      cellInfo.data.checksum!,
+      {
+        feeRate: 2000,
+      }
+    );
+    
+    console.log(`Content appended successfully to CKBFS v3!`);
+    console.log(`Transaction Hash: ${txHash}`);
+    console.log(`View at: https://pudge.explorer.nervos.org/transaction/${txHash}`);
+    
+    return txHash;
+  } catch (error) {
+    console.error('Error appending content to v3:', error);
+    throw error;
+  }
+}
+
+/**
+ * Example of transferring ownership of a CKBFS v3 file
+ */
+async function transferFileV3Example() {
+  try {
+    // Example CKBFS v3 cell (you need to replace with actual values)
+    const ckbfsCell = {
+      outPoint: {
+        txHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+        index: 0
+      },
+      data: {
+        index: 1,
+        checksum: 12345678,
+        contentType: "text/plain",
+        filename: "v3-example.txt"
+      },
+      type: Script.from({
+        codeHash: "0x25a6d8a4017d675e457b76e9228bfc3942ddbf8227f8624db4fcf315e49a6b07",
+        hashType: "data1",
+        args: "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
+      }),
+      lock: Script.from({
+        codeHash: "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
+        hashType: "type",
+        args: "0x1234567890abcdef1234567890abcdef12345678"
+      }),
+      capacity: 200n * 100000000n
+    };
+
+    // New lock script for the transferred file
+    const newLock = Script.from({
+      codeHash: "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
+      hashType: "type",
+      args: "0xfedcba0987654321fedcba0987654321fedcba09" // New owner's lock args
+    });
+
+    // V3 backlink information (from previous transaction)
+    const previousTxHash = "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890";
+    const previousWitnessIndex = 1;
+    const previousChecksum = 12345678; // Same checksum (transfer doesn't change content)
+
+    console.log(`Transferring CKBFS v3 file ownership...`);
+    
+    const txHash = await ckbfs.transferFileV3(
+      ckbfsCell,
+      newLock,
+      previousTxHash,
+      previousWitnessIndex,
+      previousChecksum,
+      {
+        feeRate: 2000,
+      }
+    );
+    
+    console.log(`File ownership transferred successfully in CKBFS v3!`);
+    console.log(`Transaction Hash: ${txHash}`);
+    console.log(`View at: https://pudge.explorer.nervos.org/transaction/${txHash}`);
+    
+    return txHash;
+  } catch (error) {
+    console.error('Error transferring v3 file:', error);
+    throw error;
+  }
+}
+
+/**
+ * Main function to run the v3 append/transfer example
+ */
+async function main() {
+  console.log('Running CKBFS v3 append/transfer example...');
+  console.log('==========================================');
+  console.log(`Using CKBFS protocol version: ${ProtocolVersion.V3}`);
+  console.log('Key v3 operations:');
+  console.log('- Append: Add content with backlink chain');
+  console.log('- Transfer: Change ownership with backlink');
+  console.log('- Backlinks stored in witnesses, not cell data');
+  console.log('==========================================');
+  
+  try {
+    console.log('Note: This example requires an existing CKBFS v3 cell.');
+    console.log('Please run publish-v3.ts first to create a v3 file,');
+    console.log('then update the cell details in this example.');
+    console.log('');
+    console.log('Uncomment the desired operation below:');
+    console.log('');
+    
+    // Uncomment to test append:
+    await appendContentV3Example();
+    
+    // Uncomment to test transfer:
+    // await transferFileV3Example();
+    
+    console.log('Example structure completed successfully!');
+    console.log('Update the cell details and uncomment operations to test.');
+    process.exit(0);
+  } catch (error) {
+    console.error('CKBFS v3 append/transfer example failed:', error);
+    process.exit(1);
+  }
+}
+
+// Run the example if this file is executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}