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

package/src/address/address.advanced.ts

@@ -1,8 +1,25 @@
 import { bech32, bech32m } from "bech32";
-import { Script, hashTypeFromBytes } from "../ckb";
+import { hashTypeFromBytes } from "../ckb";
 import { Client, KnownScript } from "../client";
 import { hexFrom } from "../hex";
-import { type Address } from "./index";
+import { type AddressLike } from "./index";
+
+/**
+ * Parses an address string into an address information object.
+ *
+ * @param address - The address string to parse.
+ * @returns An object containing the address prefix, address format, and payload array.
+ *
+ * @throws Will throw an error if the address format is unknown.
+ *
+ * @example
+ * ```typescript
+ * const addressInfo = addressPayloadFromString("ckt1112139193129");
+ * console.log(addressInfo.prefix); // Outputs the address prefix
+ * console.log(addressInfo.format); // Outputs the address format
+ * console.log(addressInfo.payload); // Outputs the payload array
+ * ```
+ */
 
 export function addressPayloadFromString(address: string): {
   prefix: string;
@@ -37,12 +54,31 @@ export function addressPayloadFromString(address: string): {
   throw Error(`Unknown address format ${address}`);
 }
 
+/**
+ * Converts an address payload into an address-like object.
+ *
+ * @param prefix - The address prefix.
+ * @param format - The format of the address, as defined by the AddressFormat enum.
+ * @param payload - The payload array containing the address data.
+ * @param client - The client instance used to fetch known scripts.
+ * @returns A promise that resolves to an AddressLike object.
+ *
+ * @throws Will throw an error if the payload length is insufficient or if the script type is unknown.
+ *
+ * @example
+ * ```typescript
+ * const address = await addressFromPayload("ckt", AddressFormat.Full, [/* payload data *\/], client);
+ * console.log(address.script); // Outputs the script object
+ * console.log(address.prefix); // Outputs the address prefix
+ * ```
+ */
+
 export async function addressFromPayload(
   prefix: string,
   format: AddressFormat,
   payload: number[],
   client: Client,
-): Promise<Address> {
+): Promise<AddressLike> {
   if (format === AddressFormat.Full) {
     if (payload.length < 32 + 1) {
       throw new Error(
@@ -51,11 +87,11 @@ export async function addressFromPayload(
     }
 
     return {
-      script: Script.from({
-        codeHash: hexFrom(payload.slice(0, 32)),
+      script: {
+        codeHash: payload.slice(0, 32),
         hashType: hashTypeFromBytes(payload.slice(32, 33)),
-        args: hexFrom(payload.slice(33)),
-      }),
+        args: payload.slice(33),
+      },
       prefix,
     };
   }
@@ -68,11 +104,11 @@ export async function addressFromPayload(
     }
 
     return {
-      script: Script.from({
-        codeHash: hexFrom(payload.slice(0, 32)),
+      script: {
+        codeHash: payload.slice(0, 32),
         hashType: "data",
-        args: hexFrom(payload.slice(32)),
-      }),
+        args: payload.slice(32),
+      },
       prefix,
     };
   }
@@ -85,11 +121,11 @@ export async function addressFromPayload(
     }
 
     return {
-      script: Script.from({
-        codeHash: hexFrom(payload.slice(0, 32)),
+      script: {
+        codeHash: payload.slice(0, 32),
         hashType: "type",
-        args: hexFrom(payload.slice(32)),
-      }),
+        args: payload.slice(32),
+      },
       prefix,
     };
   }
@@ -112,10 +148,10 @@ export async function addressFromPayload(
   }
 
   return {
-    script: Script.from({
+    script: {
       ...(await client.getKnownScript(script)),
-      args: hexFrom(payload.slice(1)),
-    }),
+      args: payload.slice(1),
+    },
     prefix,
   };
 }

package/src/address/index.ts

@@ -14,12 +14,30 @@ export type AddressLike = {
   script: ScriptLike;
   prefix: string;
 };
+
+/**
+ * Represents a ckb address with associated script and prefix.
+ */
+
 export class Address {
+  /**
+   * Creates an instance of Address.
+   *
+   * @param script - The script associated with the address.
+   * @param prefix - The address prefix.
+   */
   constructor(
     public script: Script,
     public prefix: string,
   ) {}
 
+  /**
+   * Creates an Address instance from an AddressLike object.
+   *
+   * @param address - An AddressLike object or an instance of Address.
+   * @returns An Address instance.
+   */
+
   static from(address: AddressLike): Address {
     if (address instanceof Address) {
       return address;
@@ -28,6 +46,16 @@ export class Address {
     return new Address(Script.from(address.script), address.prefix);
   }
 
+  /**
+   * Creates an Address instance from an address string.
+   *
+   * @param address - The address string to parse.
+   * @param clients - A Client instance or a record of Client instances keyed by prefix.
+   * @returns A promise that resolves to an Address instance.
+   *
+   * @throws Will throw an error if the address prefix is unknown or mismatched.
+   */
+
   static async fromString(
     address: string,
     clients: Client | Record<string, Client>,
@@ -45,14 +73,24 @@ export class Address {
       );
     }
 
-    return addressFromPayload(prefix, format, payload, client);
+    return Address.from(
+      await addressFromPayload(prefix, format, payload, client),
+    );
   }
 
+  /**
+   * Creates an Address instance from a script and client.
+   *
+   * @param script - The script-like object.
+   * @param client - The client instance used to fetch the address prefix.
+   * @returns A promise that resolves to an Address instance.
+   */
+
   static async fromScript(
     script: ScriptLike,
     client: Client,
   ): Promise<Address> {
-    return new Address(Script.from(script), await client.getAddressPrefix());
+    return Address.from({ script, prefix: await client.getAddressPrefix() });
   }
 
   static async fromKnownScript(
@@ -60,15 +98,21 @@ export class Address {
     args: HexLike,
     client: Client,
   ) {
-    return new Address(
-      Script.from({
+    return Address.from({
+      script: {
         ...(await client.getKnownScript(script)),
         args,
-      }),
-      await client.getAddressPrefix(),
-    );
+      },
+      prefix: await client.getAddressPrefix(),
+    });
   }
 
+  /**
+   * Converts the Address instance to a string.
+   *
+   * @returns The address as a string.
+   */
+
   toString(): string {
     const data = bytesConcat(
       [AddressFormat.Full],

package/src/bytes/advanced.ts

@@ -1,10 +1,13 @@
+/**
+ * Represents the possible encoding formats for converting bytes.
+ */
 export type BytesFromEncoding =
-  | "utf8"
-  | "utf16le"
-  | "latin1"
-  | "base64"
-  | "base64url"
-  | "hex"
-  | "ascii"
-  | "binary"
-  | "ucs2";
+  | "utf8" // UTF-8 encoding
+  | "utf16le" // UTF-16 Little Endian encoding
+  | "latin1" // Latin-1 (ISO-8859-1) encoding
+  | "base64" // Base64 encoding
+  | "base64url" // Base64 URL encoding
+  | "hex" // Hexadecimal encoding
+  | "ascii" // ASCII encoding
+  | "binary" // Binary encoding
+  | "ucs2"; // UCS-2 (alias of UTF-16LE) encoding

package/src/bytes/index.ts

@@ -4,6 +4,24 @@ import { BytesFromEncoding } from "./advanced";
 export type Bytes = Uint8Array;
 export type BytesLike = string | Uint8Array | ArrayBuffer | number[];
 
+/**
+ * Concatenates multiple byte-like arrays into a single byte array.
+ *
+ * @param args - The byte-like arrays to concatenate.
+ * @returns A Uint8Array containing the concatenated bytes.
+ *
+ * @example
+ * ```typescript
+ * const concatenatedBytes = bytesConcat(
+ *   new Uint8Array([1, 2]),
+ *   new Uint8Array([3, 4]),
+ *   "hello",
+ *   [5, 6, 7]
+ * );
+ * console.log(concatenatedBytes); // Outputs Uint8Array [1, 2, 3, 4, /* bytes of "hello" *\/, 5, 6, 7]
+ * ```
+ */
+
 export function bytesConcat(...args: BytesLike[]): Bytes {
   return new Uint8Array(
     args.reduce((acc: number[], v) => {
@@ -13,10 +31,52 @@ export function bytesConcat(...args: BytesLike[]): Bytes {
   );
 }
 
+/**
+ * Converts a byte-like value to a string using the specified encoding.
+ *
+ * @param val - The byte-like value to convert.
+ * @param encoding - The encoding to use for the conversion, as defined by the BytesFromEncoding type.
+ * @returns A string representing the encoded bytes.
+ *
+ * @example
+ * ```typescript
+ * const encodedString = bytesTo(new Uint8Array([104, 101, 108, 108, 111]), "utf8");
+ * console.log(encodedString); // Outputs "hello"
+ *
+ * const base64String = bytesTo(new Uint8Array([104, 101, 108, 108, 111]), "base64");
+ * console.log(base64String); // Outputs "aGVsbG8="
+ * ```
+ */
+
 export function bytesTo(val: BytesLike, encoding: BytesFromEncoding): string {
   return Buffer.from(bytesFrom(val)).toString(encoding);
 }
 
+/**
+ * Converts various types of byte-like values to a Uint8Array.
+ *
+ * @param bytes - The byte-like value to convert. It can be a string, Uint8Array, ArrayBuffer, or number array.
+ * @param encoding - Optional encoding to use if the input is a string. Defaults to hexadecimal if not specified.
+ * @returns A Uint8Array representing the input bytes.
+ *
+ * @throws Will throw an error if the input bytes are invalid or out of range.
+ *
+ * @example
+ * ```typescript
+ * const bytes1 = bytesFrom(new Uint8Array([1, 2, 3]));
+ * console.log(bytes1); // Outputs Uint8Array [1, 2, 3]
+ *
+ * const bytes2 = bytesFrom("68656c6c6f", "hex");
+ * console.log(bytes2); // Outputs Uint8Array [104, 101, 108, 108, 111]
+ *
+ * const bytes3 = bytesFrom("hello", "utf8");
+ * console.log(bytes3); // Outputs Uint8Array [104, 101, 108, 108, 111]
+ *
+ * const bytes4 = bytesFrom([1, 2, 255]);
+ * console.log(bytes4); // Outputs Uint8Array [1, 2, 255]
+ * ```
+ */
+
 export function bytesFrom(
   bytes: BytesLike,
   encoding?: BytesFromEncoding,

package/src/ckb/script.ts

@@ -9,6 +9,22 @@ import {
 
 export type HashTypeLike = string | number | bigint;
 export type HashType = "type" | "data" | "data1" | "data2";
+
+/**
+ * Converts a HashTypeLike value to a HashType.
+ *
+ * @param val - The value to convert, which can be a string, number, or bigint.
+ * @returns The corresponding HashType.
+ *
+ * @throws Will throw an error if the input value is not a valid hash type.
+ *
+ * @example
+ * ```typescript
+ * const hashType = hashTypeFrom(1); // Outputs "data"
+ * const hashType = hashTypeFrom("type"); // Outputs "type"
+ * ```
+ */
+
 export function hashTypeFrom(val: HashTypeLike): HashType {
   const hashType = (() => {
     if (typeof val === "number") {
@@ -29,9 +45,37 @@ export function hashTypeFrom(val: HashTypeLike): HashType {
   }
   return hashType;
 }
-export function hashTypeToBytes(hashType: HashType): Bytes {
-  return bytesFrom([HASH_TYPE_TO_NUM[hashType]]);
+
+/**
+ * Converts a HashTypeLike value to its corresponding byte representation.
+ *
+ * @param hashType - The hash type value to convert.
+ * @returns A Uint8Array containing the byte representation of the hash type.
+ *
+ * @example
+ * ```typescript
+ * const hashTypeBytes = hashTypeToBytes("type"); // Outputs Uint8Array [0]
+ * ```
+ */
+
+export function hashTypeToBytes(hashType: HashTypeLike): Bytes {
+  return bytesFrom([HASH_TYPE_TO_NUM[hashTypeFrom(hashType)]]);
 }
+
+/**
+ * Converts a byte-like value to a HashType.
+ *
+ * @param bytes - The byte-like value to convert.
+ * @returns The corresponding HashType.
+ *
+ * @throws Will throw an error if the input bytes do not correspond to a valid hash type.
+ *
+ * @example
+ * ```typescript
+ * const hashType = hashTypeFromBytes(new Uint8Array([0])); // Outputs "type"
+ * ```
+ */
+
 export function hashTypeFromBytes(bytes: BytesLike): HashType {
   return NUM_TO_HASH_TYPE[bytesFrom(bytes)[0]];
 }
@@ -42,12 +86,36 @@ export type ScriptLike = {
   args: BytesLike;
 };
 export class Script {
+  /**
+   * Creates an instance of Script.
+   *
+   * @param codeHash - The code hash of the script.
+   * @param hashType - The hash type of the script.
+   * @param args - The arguments for the script.
+   */
+
   constructor(
     public codeHash: Hex,
     public hashType: HashType,
     public args: Hex,
   ) {}
 
+  /**
+   * Creates a Script instance from a ScriptLike object.
+   *
+   * @param script - A ScriptLike object or an instance of Script.
+   * @returns A Script instance.
+   *
+   * @example
+   * ```typescript
+   * const script = Script.from({
+   *   codeHash: "0x1234...",
+   *   hashType: "type",
+   *   args: "0xabcd..."
+   * });
+   * ```
+   */
+
   static from(script: ScriptLike): Script {
     if (script instanceof Script) {
       return script;
@@ -60,6 +128,12 @@ export class Script {
     );
   }
 
+  /**
+   * Converts the Script instance to molecule data format.
+   *
+   * @returns An object representing the script in molecule data format.
+   */
+
   _toMolData() {
     return {
       codeHash: bytesFrom(this.codeHash),
@@ -68,10 +142,33 @@ export class Script {
     };
   }
 
+  /**
+   * Converts the Script instance to bytes.
+   *
+   * @returns A Uint8Array containing the script bytes.
+   *
+   * @example
+   * ```typescript
+   * const scriptBytes = script.toBytes();
+   * ```
+   */
+
   toBytes(): Bytes {
     return bytesFrom(mol.SerializeScript(this._toMolData()));
   }
 
+  /**
+   * Creates a Script instance from a byte-like value or molecule Script.
+   *
+   * @param bytes - The byte-like value or molecule Script to convert.
+   * @returns A Script instance.
+   *
+   * @example
+   * ```typescript
+   * const script = Script.fromBytes(new Uint8Array([/* script bytes *\/]));
+   * ```
+   */
+
   static fromBytes(bytes: BytesLike | mol.Script): Script {
     const view =
       bytes instanceof mol.Script ? bytes : new mol.Script(bytesFrom(bytes));
@@ -83,6 +180,18 @@ export class Script {
     );
   }
 
+  /**
+   * Compares the current Script instance with another ScriptLike object for equality.
+   *
+   * @param val - The ScriptLike object to compare with.
+   * @returns True if the scripts are equal, otherwise false.
+   *
+   * @example
+   * ```typescript
+   * const isEqual = script.eq(anotherScript);
+   * ```
+   */
+
   eq(val: ScriptLike): boolean {
     const script = Script.from(val);
     return (