@ckb-ccc/core 0.0.4-alpha.1 → 0.0.4-alpha.11

package/src/hasher/index.ts

@@ -4,7 +4,14 @@ import { Hex } from "../hex";
 import { CKB_BLAKE2B_PERSONAL } from "./advanced";
 
 export class Hasher {
-  hasher: Blake2b;
+  private readonly hasher: Blake2b;
+
+  /**
+   * Creates an instance of Hasher.
+   *
+   * @param outLength - The output length of the hash in bytes. Default is 32.
+   * @param personal - The personal string for the Blake2b algorithm. Default is CKB_BLAKE2B_PERSONAL.
+   */
 
   constructor(outLength = 32, personal = CKB_BLAKE2B_PERSONAL) {
     this.hasher = blake2b(
@@ -15,16 +22,55 @@ export class Hasher {
     );
   }
 
+  /**
+   * Updates the hash with the given data.
+   *
+   * @param data - The data to update the hash with.
+   * @returns The current Hasher instance for chaining.
+   *
+   * @example
+   * ```typescript
+   * const hasher = new Hasher();
+   * hasher.update("some data").update("more data");
+   * const hash = hasher.digest();
+   * ```
+   */
+
   update(data: BytesLike): Hasher {
     this.hasher.update(bytesFrom(data));
     return this;
   }
 
+  /**
+   * Finalizes the hash and returns the digest as a hexadecimal string.
+   *
+   * @returns The hexadecimal string representation of the hash.
+   *
+   * @example
+   * ```typescript
+   * const hasher = new Hasher();
+   * hasher.update("some data");
+   * const hash = hasher.digest(); // Outputs something like "0x..."
+   * ```
+   */
+
   digest(): Hex {
     return `0x${this.hasher.digest("hex")}`;
   }
 }
 
+/**
+ * Computes the CKB hash of the given data using the Blake2b algorithm.
+ *
+ * @param data - The data to hash.
+ * @returns The hexadecimal string representation of the hash.
+ *
+ * @example
+ * ```typescript
+ * const hash = ckbHash("some data"); // Outputs something like "0x..."
+ * ```
+ */
+
 export function ckbHash(data: BytesLike): Hex {
   return new Hasher().update(data).digest();
 }

package/src/hex/index.ts

@@ -1,8 +1,27 @@
 import { bytesFrom, BytesLike, bytesTo } from "../bytes";
 
+/**
+ * Represents a hexadecimal string prefixed with "0x".
+ */
 export type Hex = `0x${string}`;
+/**
+ * Represents a value that can be converted to a hexadecimal string.
+ * It extends the BytesLike type.
+ */
 export type HexLike = BytesLike;
 
+/**
+ * Converts a HexLike value to a Hex string.
+ *
+ * @param hex - The value to convert, which can be a string, Uint8Array, ArrayBuffer, or number array.
+ * @returns A Hex string representing the value.
+ *
+ * @example
+ * ```typescript
+ * const hexString = hexFrom("68656c6c6f"); // Outputs "0x68656c6c6f"
+ * const hexStringFromBytes = hexFrom(new Uint8Array([104, 101, 108, 108, 111])); // Outputs "0x68656c6c6f"
+ * ```
+ */
 export function hexFrom(hex: HexLike): Hex {
   return `0x${bytesTo(bytesFrom(hex), "hex")}`;
 }

package/src/num/index.ts

@@ -1,9 +1,29 @@
 import { Bytes, BytesLike, bytesConcat, bytesFrom } from "../bytes";
 import { Hex, HexLike, hexFrom } from "../hex";
 
+/**
+ * Represents a numeric value as a bigint.
+ */
 export type Num = bigint;
+
+/**
+ * Represents a value that can be converted to a numeric value.
+ * It can be a string, number, bigint, or HexLike.
+ */
 export type NumLike = string | number | bigint | HexLike;
 
+/**
+ * Converts a NumLike value to a Num (bigint).
+ *
+ * @param val - The value to convert, which can be a string, number, bigint, or HexLike.
+ * @returns A Num (bigint) representing the value.
+ *
+ * @example
+ * ```typescript
+ * const num = numFrom("12345"); // Outputs 12345n
+ * const numFromHex = numFrom("0x3039"); // Outputs 12345n
+ * ```
+ */
 export function numFrom(val: NumLike): Num {
   if (typeof val === "bigint") {
     return val;
@@ -16,18 +36,66 @@ export function numFrom(val: NumLike): Num {
   return BigInt(hexFrom(val));
 }
 
+/**
+ * Converts a NumLike value to a hexadecimal string.
+ *
+ * @param val - The value to convert, which can be a string, number, bigint, or HexLike.
+ * @returns A Hex string representing the numeric value.
+ *
+ * @example
+ * ```typescript
+ * const hex = numToHex(12345); // Outputs "0x3039"
+ * ```
+ */
 export function numToHex(val: NumLike): Hex {
   return `0x${numFrom(val).toString(16)}`;
 }
 
+/**
+ * Converts a NumLike value to a byte array in little-endian order.
+ *
+ * @param val - The value to convert, which can be a string, number, bigint, or HexLike.
+ * @param bytes - The number of bytes to use for the representation. If not provided, the exact number of bytes needed is used.
+ * @returns A Uint8Array containing the byte representation of the numeric value.
+ *
+ * @example
+ * ```typescript
+ * const bytes = numToBytes(12345, 4); // Outputs Uint8Array [57, 48, 0, 0]
+ * ```
+ */
+
 export function numToBytes(val: NumLike, bytes?: number): Bytes {
   return numLeToBytes(val, bytes);
 }
 
+/**
+ * Converts a NumLike value to a byte array in little-endian order.
+ *
+ * @param val - The value to convert, which can be a string, number, bigint, or HexLike.
+ * @param bytes - The number of bytes to use for the representation. If not provided, the exact number of bytes needed is used.
+ * @returns A Uint8Array containing the byte representation of the numeric value.
+ *
+ * @example
+ * ```typescript
+ * const bytes = numLeToBytes(12345, 4); // Outputs Uint8Array [57, 48, 0, 0]
+ * ```
+ */
 export function numLeToBytes(val: NumLike, bytes?: number): Bytes {
   return numBeToBytes(val, bytes).reverse();
 }
 
+/**
+ * Converts a NumLike value to a byte array in big-endian order.
+ *
+ * @param val - The value to convert, which can be a string, number, bigint, or HexLike.
+ * @param bytes - The number of bytes to use for the representation. If not provided, the exact number of bytes needed is used.
+ * @returns A Uint8Array containing the byte representation of the numeric value.
+ *
+ * @example
+ * ```typescript
+ * const bytes = numBeToBytes(12345, 4); // Outputs Uint8Array [0, 0, 48, 57]
+ * ```
+ */
 export function numBeToBytes(val: NumLike, bytes?: number): Bytes {
   const rawBytes = bytesFrom(numFrom(val).toString(16));
   if (bytes == null) {
@@ -40,14 +108,47 @@ export function numBeToBytes(val: NumLike, bytes?: number): Bytes {
   );
 }
 
+/**
+ * Converts a byte array to a Num (bigint) assuming little-endian order.
+ *
+ * @param val - The byte array to convert.
+ * @returns A Num (bigint) representing the numeric value.
+ *
+ * @example
+ * ```typescript
+ * const num = numFromBytes(new Uint8Array([57, 48, 0, 0])); // Outputs 12345n
+ * ```
+ */
 export function numFromBytes(val: BytesLike): Num {
   return numLeFromBytes(val);
 }
 
+/**
+ * Converts a byte array to a Num (bigint) assuming little-endian order.
+ *
+ * @param val - The byte array to convert.
+ * @returns A Num (bigint) representing the numeric value.
+ *
+ * @example
+ * ```typescript
+ * const num = numLeFromBytes(new Uint8Array([57, 48, 0, 0])); // Outputs 12345n
+ * ```
+ */
 export function numLeFromBytes(val: BytesLike): Num {
   return numBeFromBytes(bytesFrom(val).reverse());
 }
 
+/**
+ * Converts a byte array to a Num (bigint) assuming big-endian order.
+ *
+ * @param val - The byte array to convert.
+ * @returns A Num (bigint) representing the numeric value.
+ *
+ * @example
+ * ```typescript
+ * const num = numBeFromBytes(new Uint8Array([0, 0, 48, 57])); // Outputs 12345n
+ * ```
+ */
 export function numBeFromBytes(val: BytesLike): Num {
   return numFrom(bytesFrom(val));
 }

package/src/signer/btc/signerBtc.ts

@@ -2,22 +2,47 @@ import { ripemd160 } from "@noble/hashes/ripemd160";
 import { sha256 } from "@noble/hashes/sha256";
 import { Address } from "../../address";
 import { bytesConcat, bytesFrom } from "../../bytes";
-import { Transaction, WitnessArgs } from "../../ckb";
+import { Transaction, TransactionLike, WitnessArgs } from "../../ckb";
 import { KnownScript } from "../../client";
 import { HexLike, hexFrom } from "../../hex";
 import { numToBytes } from "../../num";
-import { getSignHashInfo } from "../helpers";
+import { getSignHashInfo, prepareSighashAllWitness } from "../helpers";
 import { Signer } from "../signer";
 
+/**
+ * An abstract class extending the Signer class for Bitcoin-like signing operations.
+ * This class provides methods to get Bitcoin account, public key, and internal address,
+ * as well as signing transactions.
+ */
 export abstract class SignerBtc extends Signer {
+  /**
+   * Gets the Bitcoin account associated with the signer.
+   *
+   * @returns A promise that resolves to a string representing the Bitcoin account.
+   */
   abstract getBtcAccount(): Promise<string>;
 
+  /**
+   * Gets the Bitcoin public key associated with the signer.
+   *
+   * @returns A promise that resolves to a HexLike value representing the Bitcoin public key.
+   */
   abstract getBtcPublicKey(): Promise<HexLike>;
 
+  /**
+   * Gets the internal address, which is the Bitcoin account in this case.
+   *
+   * @returns A promise that resolves to a string representing the internal address.
+   */
   async getInternalAddress(): Promise<string> {
     return this.getBtcAccount();
   }
 
+  /**
+   * Gets an array of Address objects representing the known script addresses for the signer.
+   *
+   * @returns A promise that resolves to an array of Address objects.
+   */
   async getAddressObjs(): Promise<Address[]> {
     const publicKey = await this.getBtcPublicKey();
     const hash = ripemd160(sha256(bytesFrom(publicKey)));
@@ -31,9 +56,27 @@ export abstract class SignerBtc extends Signer {
     ];
   }
 
-  async signOnlyTransaction(tx: Transaction): Promise<Transaction> {
+  /**
+   * prepare a transaction before signing. This method is not implemented and should be overridden by subclasses.
+   *
+   * @param txLike - The transaction to prepare, represented as a TransactionLike object.
+   * @returns A promise that resolves to the prepared Transaction object.
+   */
+  async prepareTransaction(txLike: TransactionLike): Promise<Transaction> {
     const { script } = await this.getRecommendedAddressObj();
-    const info = await getSignHashInfo(tx, script);
+    return prepareSighashAllWitness(txLike, script, 85, this.client);
+  }
+
+  /**
+   * Signs a transaction without modifying it.
+   *
+   * @param txLike - The transaction to sign, represented as a TransactionLike object.
+   * @returns A promise that resolves to a signed Transaction object.
+   */
+  async signOnlyTransaction(txLike: TransactionLike): Promise<Transaction> {
+    const tx = Transaction.from(txLike);
+    const { script } = await this.getRecommendedAddressObj();
+    const info = await getSignHashInfo(tx, script, this.client);
     if (!info) {
       return tx;
     }

package/src/signer/btc/signerBtcPublicKeyReadonly.ts

@@ -2,9 +2,20 @@ import { Client } from "../../client";
 import { Hex, HexLike, hexFrom } from "../../hex";
 import { SignerBtc } from "./signerBtc";
 
+/**
+ * A class extending SignerBtc that provides read-only access to a Bitcoin public key and account.
+ * This class does not support signing operations.
+ */
 export class SignerBtcPublicKeyReadonly extends SignerBtc {
   private readonly publicKey: Hex;
 
+  /**
+   * Creates an instance of SignerBtcPublicKeyReadonly.
+   *
+   * @param client - The client instance used for communication.
+   * @param account - The Bitcoin account associated with the signer.
+   * @param publicKey - The public key associated with the signer.
+   */
   constructor(
     client: Client,
     private readonly account: string,
@@ -15,12 +26,55 @@ export class SignerBtcPublicKeyReadonly extends SignerBtc {
     this.publicKey = hexFrom(publicKey);
   }
 
+  /**
+   * Construct a new signer with the client replaced.
+   *
+   * @returns A promise that resolves the new Signer.
+   */
+  async replaceClient(client: Client): Promise<SignerBtcPublicKeyReadonly> {
+    return new SignerBtcPublicKeyReadonly(client, this.account, this.publicKey);
+  }
+
+  /**
+   * Connects to the client. This implementation does nothing as the class is read-only.
+   *
+   * @returns A promise that resolves when the connection is complete.
+   */
   async connect(): Promise<void> {}
 
+  /**
+   * Check if the signer is connected.
+   *
+   * @returns A promise that resolves the connection status.
+   */
+  async isConnected(): Promise<boolean> {
+    return true;
+  };
+
+  /**
+   * Gets the Bitcoin account associated with the signer.
+   *
+   * @returns A promise that resolves to a string representing the Bitcoin account.
+   *
+   * @example
+   * ```typescript
+   * const account = await signer.getBtcAccount(); // Outputs the Bitcoin account
+   * ```
+   */
   async getBtcAccount(): Promise<string> {
     return this.account;
   }
 
+  /**
+   * Gets the Bitcoin public key associated with the signer.
+   *
+   * @returns A promise that resolves to a Hex string representing the Bitcoin public key.
+   *
+   * @example
+   * ```typescript
+   * const publicKey = await signer.getBtcPublicKey(); // Outputs the Bitcoin public key
+   * ```
+   */
   async getBtcPublicKey(): Promise<Hex> {
     return this.publicKey;
   }

package/src/signer/ckb/signerCkbScriptReadonly.ts

@@ -3,21 +3,75 @@ import { Script, ScriptLike } from "../../ckb";
 import { Client } from "../../client";
 import { Signer } from "../signer";
 
+/**
+ * A class extending Signer that provides read-only access to a CKB script.
+ * This class does not support signing operations.
+ */
 export class SignerCkbScriptReadonly extends Signer {
   private readonly script: Script;
 
+  /**
+   * Creates an instance of SignerCkbScriptReadonly.
+   *
+   * @param client - The client instance used for communication.
+   * @param script - The script associated with the signer.
+   */
   constructor(client: Client, script: ScriptLike) {
     super(client);
 
     this.script = Script.from(script);
   }
 
+  /**
+   * Construct a new signer with the client replaced.
+   *
+   * @returns A promise that resolves the new Signer.
+   */
+  async replaceClient(client: Client): Promise<SignerCkbScriptReadonly> {
+    return new SignerCkbScriptReadonly(client, this.script);
+  }
+
+  /**
+   * Connects to the client. This implementation does nothing as the class is read-only.
+   *
+   * @returns A promise that resolves when the connection is complete.
+   */
   async connect(): Promise<void> {}
 
+  /**
+   * Check if the signer is connected.
+   *
+   * @returns A promise that resolves the connection status.
+   */
+  async isConnected(): Promise<boolean> {
+    return true;
+  };
+
+  /**
+   * Gets the internal address for the script.
+   *
+   * @returns A promise that resolves to a string representing the internal address.
+   *
+   * @example
+   * ```typescript
+   * const internalAddress = await signer.getInternalAddress(); // Outputs the internal address
+   * ```
+   */
   async getInternalAddress(): Promise<string> {
     return this.getRecommendedAddress();
   }
 
+  /**
+   * Gets an array of Address objects representing the script address.
+   *
+   * @returns A promise that resolves to an array of Address objects.
+   *
+   * @example
+   * ```typescript
+   * const addressObjs = await signer.getAddressObjs(); // Outputs the array of Address objects
+   * ```
+   */
+
   async getAddressObjs(): Promise<Address[]> {
     return [await Address.fromScript(this.script, this.client)];
   }

package/src/signer/evm/signerEvm.ts

@@ -1,19 +1,38 @@
 import { Address } from "../../address";
 import { bytesConcat, bytesFrom } from "../../bytes";
-import { Transaction, WitnessArgs } from "../../ckb";
+import { Transaction, TransactionLike, WitnessArgs } from "../../ckb";
 import { KnownScript } from "../../client";
 import { hexFrom } from "../../hex";
 import { numToBytes } from "../../num";
-import { getSignHashInfo } from "../helpers";
+import { getSignHashInfo, prepareSighashAllWitness } from "../helpers";
 import { Signer } from "../signer";
 
+/**
+ * An abstract class extending Signer for Ethereum Virtual Machine (EVM) based signing operations.
+ * This class provides methods to get EVM account, internal address, and signing transactions.
+ */
 export abstract class SignerEvm extends Signer {
+  /**
+   * Gets the EVM account associated with the signer.
+   *
+   * @returns A promise that resolves to a string representing the EVM account.
+   */
   abstract getEvmAccount(): Promise<string>;
 
+  /**
+   * Gets the internal address, which is the EVM account in this case.
+   *
+   * @returns A promise that resolves to a string representing the internal address.
+   */
   async getInternalAddress(): Promise<string> {
     return this.getEvmAccount();
   }
 
+  /**
+   * Gets an array of Address objects representing the known script addresses for the signer.
+   *
+   * @returns A promise that resolves to an array of Address objects.
+   */
   async getAddressObjs(): Promise<Address[]> {
     const account = await this.getEvmAccount();
     return [
@@ -25,9 +44,28 @@ export abstract class SignerEvm extends Signer {
     ];
   }
 
-  async signOnlyTransaction(tx: Transaction): Promise<Transaction> {
+  /**
+   * prepare a transaction before signing. This method is not implemented and should be overridden by subclasses.
+   *
+   * @param txLike - The transaction to prepare, represented as a TransactionLike object.
+   * @returns A promise that resolves to the prepared Transaction object.
+   */
+  async prepareTransaction(txLike: TransactionLike): Promise<Transaction> {
     const { script } = await this.getRecommendedAddressObj();
-    const info = await getSignHashInfo(tx, script);
+    return prepareSighashAllWitness(txLike, script, 85, this.client);
+  }
+
+  /**
+   * Signs a transaction without modifying it.
+   *
+   * @param txLike - The transaction to sign, represented as a TransactionLike object.
+   * @returns A promise that resolves to a signed Transaction object.
+   */
+  async signOnlyTransaction(txLike: TransactionLike): Promise<Transaction> {
+    const tx = Transaction.from(txLike);
+
+    const { script } = await this.getRecommendedAddressObj();
+    const info = await getSignHashInfo(tx, script, this.client);
     if (!info) {
       return tx;
     }

package/src/signer/evm/signerEvmAddressReadonly.ts

@@ -2,17 +2,66 @@ import { Client } from "../../client";
 import { Hex, HexLike, hexFrom } from "../../hex";
 import { SignerEvm } from "./signerEvm";
 
-export abstract class SignerEvmAddressReadonly extends SignerEvm {
+/**
+ * A class extending SignerEvm that provides read-only access to an EVM address.
+ * This class does not support signing operations.
+ */
+export class SignerEvmAddressReadonly extends SignerEvm {
   private readonly address: Hex;
 
+  /**
+   * Creates an instance of SignerEvmAddressReadonly.
+   *
+   * @param client - The client instance used for communication.
+   * @param address - The EVM address associated with the signer.
+   */
   constructor(client: Client, address: HexLike) {
     super(client);
 
     this.address = hexFrom(address);
   }
 
+  /**
+   * Construct a new signer with the client replaced.
+   *
+   * @returns A promise that resolves the new Signer.
+   */
+  async replaceClient(client: Client): Promise<SignerEvmAddressReadonly> {
+    return new SignerEvmAddressReadonly(client, this.address);
+  }
+
+  /**
+   * Connects to the client. This implementation does nothing as the class is read-only.
+   *
+   * @returns A promise that resolves when the connection is complete.
+   *
+   * @example
+   * ```typescript
+   * await signer.connect();
+   * ```
+   */
+
   async connect(): Promise<void> {}
 
+  /**
+   * Check if the signer is connected.
+   *
+   * @returns A promise that resolves the connection status.
+   */
+  async isConnected(): Promise<boolean> {
+    return true;
+  };
+
+  /**
+   * Gets the EVM account associated with the signer.
+   *
+   * @returns A promise that resolves to a string representing the EVM account.
+   *
+   * @example
+   * ```typescript
+   * const account = await signer.getEvmAccount(); // Outputs the EVM account
+   * ```
+   */
   async getEvmAccount(): Promise<string> {
     return this.address;
   }