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

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 { 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,16 @@ export abstract class SignerBtc extends Signer {
     ];
   }
 
-  async signOnlyTransaction(tx: Transaction): Promise<Transaction> {
+  /**
+   * 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);
+    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,37 @@ export class SignerBtcPublicKeyReadonly extends SignerBtc {
     this.publicKey = hexFrom(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> {}
 
+  /**
+   * 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,57 @@ 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);
   }
 
+  /**
+   * 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> {}
 
+  /**
+   * 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 { 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,17 @@ export abstract class SignerEvm extends Signer {
     ];
   }
 
-  async signOnlyTransaction(tx: Transaction): Promise<Transaction> {
+  /**
+   * 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);
+    const info = await getSignHashInfo(tx, script, this.client);
     if (!info) {
       return tx;
     }

package/src/signer/evm/signerEvmAddressReadonly.ts

@@ -2,17 +2,48 @@ import { Client } from "../../client";
 import { Hex, HexLike, hexFrom } from "../../hex";
 import { SignerEvm } from "./signerEvm";
 
+/**
+ * A class extending SignerEvm that provides read-only access to an EVM address.
+ * This class does not support signing operations.
+ */
 export abstract 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);
   }
 
+  /**
+   * 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> {}
 
+  /**
+   * 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;
   }

package/src/signer/helpers.ts

@@ -1,10 +1,29 @@
 import { Script, ScriptLike, Transaction, TransactionLike } from "../ckb";
+import { Client } from "../client";
 import { Hasher } from "../hasher";
 import { Hex } from "../hex";
 
+/**
+ * Computes the signing hash information for a given transaction and script.
+ *
+ * @param txLike - The transaction to sign, represented as a TransactionLike object.
+ * @param scriptLike - The script associated with the transaction, represented as a ScriptLike object.
+ * @returns A promise that resolves to an object containing the signing message and the witness position,
+ *          or undefined if no matching input is found.
+ *
+ * @example
+ * ```typescript
+ * const signHashInfo = await getSignHashInfo(transactionLike, scriptLike);
+ * if (signHashInfo) {
+ *   console.log(signHashInfo.message); // Outputs the signing message
+ *   console.log(signHashInfo.position); // Outputs the witness position
+ * }
+ * ```
+ */
 export async function getSignHashInfo(
   txLike: TransactionLike,
   scriptLike: ScriptLike,
+  client: Client,
 ): Promise<{ message: Hex; position: number } | undefined> {
   const tx = Transaction.from(txLike);
   const script = Script.from(scriptLike);
@@ -12,14 +31,15 @@ export async function getSignHashInfo(
   const hasher = new Hasher();
   hasher.update(tx.hash());
 
-  tx.witnesses.forEach((witness, i) => {
-    const input = tx.inputs[i];
-    if (input) {
-      if (!input.cellOutput?.lock) {
-        throw Error("Incomplete inputs info");
+  for (let i = 0; i < tx.witnesses.length; i += 1) {
+    if (tx.inputs[i]) {
+      const input = await tx.inputs[i].completeExtraInfos(client);
+
+      if (!input.cellOutput) {
+        throw Error("Unable to resolve inputs info");
       }
 
-      if (!script.eq(input.cellOutput?.lock)) {
+      if (!script.eq(input.cellOutput.lock)) {
         return;
       }
 
@@ -32,8 +52,8 @@ export async function getSignHashInfo(
       return undefined;
     }
 
-    Transaction.hashWitnessToHasher(witness, hasher);
-  });
+    Transaction.hashWitnessToHasher(tx.witnesses[i], hasher);
+  }
 
   if (position === -1) {
     return undefined;

package/src/signer/signer.ts

@@ -1,52 +1,122 @@
 import { Address } from "../address";
 import { BytesLike } from "../bytes";
-import { Transaction } from "../ckb";
+import { Transaction, TransactionLike } from "../ckb";
 import { Client } from "../client";
 import { Hex } from "../hex";
 
+/**
+ * An abstract class representing a generic signer.
+ * This class provides methods to connect, get addresses, and sign transactions.
+ */
 export abstract class Signer {
   constructor(public readonly client: Client) {}
 
+  /**
+   * Connects to the client.
+   *
+   * @returns A promise that resolves when the connection is complete.
+   */
   abstract connect(): Promise<void>;
 
+  /**
+   * Gets the internal address associated with the signer.
+   *
+   * @returns A promise that resolves to a string representing the internal address.
+   */
   abstract getInternalAddress(): Promise<string>;
 
+  /**
+   * Gets an array of Address objects associated with the signer.
+   *
+   * @returns A promise that resolves to an array of Address objects.
+   */
   abstract getAddressObjs(): Promise<Address[]>;
+
+  /**
+   * Gets the recommended Address object for the signer.
+   *
+   * @param _preference - Optional preference parameter.
+   * @returns A promise that resolves to the recommended Address object.
+   */
   async getRecommendedAddressObj(_preference?: unknown): Promise<Address> {
     return (await this.getAddressObjs())[0];
   }
 
+  /**
+   * Gets the recommended address for the signer as a string.
+   *
+   * @param preference - Optional preference parameter.
+   * @returns A promise that resolves to the recommended address as a string.
+   */
   async getRecommendedAddress(preference?: unknown): Promise<string> {
     return (await this.getRecommendedAddressObj(preference)).toString();
   }
+
+  /**
+   * Gets an array of addresses associated with the signer as strings.
+   *
+   * @returns A promise that resolves to an array of addresses as strings.
+   */
   async getAddresses(): Promise<string[]> {
     return this.getAddressObjs().then((addresses) =>
       addresses.map((address) => address.toString()),
     );
   }
 
+  /**
+   * Signs a message. This method is not implemented and should be overridden by subclasses.
+   *
+   * @param _ - The message to sign, as a string or BytesLike object.
+   * @returns A promise that resolves to the signed message as a string.
+   * @throws Will throw an error if not implemented.
+   */
   signMessage(_: string | BytesLike): Promise<string> {
     throw Error("Signer.signMessage not implemented");
   }
 
-  async sendTransaction(tx: Transaction): Promise<Hex> {
+  /**
+   * Sends a transaction after signing it.
+   *
+   * @param tx - The transaction to send, represented as a TransactionLike object.
+   * @returns A promise that resolves to the transaction hash as a Hex string.
+   */
+  async sendTransaction(tx: TransactionLike): Promise<Hex> {
     return this.client.sendTransaction(await this.signTransaction(tx));
   }
 
-  async signTransaction(tx: Transaction): Promise<Transaction> {
+  /**
+   * Signs a transaction.
+   *
+   * @param tx - The transaction to sign, represented as a TransactionLike object.
+   * @returns A promise that resolves to the signed Transaction object.
+   */
+  async signTransaction(tx: TransactionLike): Promise<Transaction> {
     return this.signOnlyTransaction(tx);
   }
 
-  signOnlyTransaction(_: Transaction): Promise<Transaction> {
+  /**
+   * Signs a transaction without sending it. This method is not implemented and should be overridden by subclasses.
+   *
+   * @param _ - The transaction to sign, represented as a TransactionLike object.
+   * @returns A promise that resolves to the signed Transaction object.
+   * @throws Will throw an error if not implemented.
+   */
+  signOnlyTransaction(_: TransactionLike): Promise<Transaction> {
     throw Error("Signer.signOnlyTransaction not implemented");
   }
 }
 
+/**
+ * An enumeration of signer types.
+ */
 export enum SignerType {
   EVM = "EVM",
   BTC = "BTC",
 }
 
+/**
+ * A class representing information about a signer, including its type and the signer instance.
+ */
 export class SignerInfo {
   constructor(
     public type: SignerType,
@@ -54,6 +124,9 @@ export class SignerInfo {
   ) {}
 }
 
+/**
+ * Represents a wallet with a name, icon, and an array of signer information.
+ */
 export type Wallet = {
   name: string;
   icon: string;