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

package/src/client/clientPublicMainnet.advanced.ts

@@ -1,7 +1,10 @@
-import { ScriptLike } from "../ckb";
+import { Script } from "../ckb";
 import { KnownScript } from "./client";
 
-export const MAINNET_SCRIPTS: Record<KnownScript, Omit<ScriptLike, "args">> = {
+export const MAINNET_SCRIPTS: Record<
+  KnownScript,
+  Pick<Script, "codeHash" | "hashType">
+> = {
   [KnownScript.Secp256k1Blake160]: {
     codeHash:
       "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",

package/src/client/clientPublicMainnet.ts

@@ -1,4 +1,4 @@
-import { ScriptLike } from "../ckb";
+import { Script } from "../ckb";
 import { KnownScript } from "./client";
 import { MAINNET_SCRIPTS } from "./clientPublicMainnet.advanced";
 import { ClientJsonRpc } from "./jsonRpc";
@@ -12,7 +12,9 @@ export class ClientPublicMainnet extends ClientJsonRpc {
     return "ckb";
   }
 
-  async getKnownScript(script: KnownScript): Promise<Omit<ScriptLike, "args">> {
+  async getKnownScript(
+    script: KnownScript,
+  ): Promise<Pick<Script, "codeHash" | "hashType">> {
     return { ...MAINNET_SCRIPTS[script] };
   }
 }

package/src/client/clientPublicTestnet.advanced.ts

@@ -1,7 +1,10 @@
-import { ScriptLike } from "../ckb";
+import { Script } from "../ckb";
 import { KnownScript } from "./client";
 
-export const TESTNET_SCRIPTS: Record<KnownScript, Omit<ScriptLike, "args">> = {
+export const TESTNET_SCRIPTS: Record<
+  KnownScript,
+  Pick<Script, "codeHash" | "hashType">
+> = {
   [KnownScript.Secp256k1Blake160]: {
     codeHash:
       "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",

package/src/client/clientPublicTestnet.ts

@@ -1,4 +1,4 @@
-import { ScriptLike } from "../ckb";
+import { Script } from "../ckb";
 import { KnownScript } from "./client";
 import { TESTNET_SCRIPTS } from "./clientPublicTestnet.advanced";
 import { ClientJsonRpc } from "./jsonRpc";
@@ -12,7 +12,9 @@ export class ClientPublicTestnet extends ClientJsonRpc {
     return "ckt";
   }
 
-  async getKnownScript(script: KnownScript): Promise<Omit<ScriptLike, "args">> {
+  async getKnownScript(
+    script: KnownScript,
+  ): Promise<Pick<Script, "codeHash" | "hashType">> {
     return { ...TESTNET_SCRIPTS[script] };
   }
 }

package/src/client/clientTypes.ts

@@ -1 +1,14 @@
+import { Transaction } from "../ckb";
+
 export type OutputsValidator = "passthrough" | "well_known_scripts_only";
+
+export type TransactionStatus =
+  | "pending"
+  | "proposed"
+  | "committed"
+  | "unknown"
+  | "rejected";
+export type ClientTransactionResponse = {
+  transaction: Transaction;
+  status: TransactionStatus;
+};

package/src/client/jsonRpc/advanced.ts

@@ -1,93 +1,2 @@
-import {
-  CellDepLike,
-  CellInputLike,
-  CellOutputLike,
-  DepTypeLike,
-  OutPointLike,
-  ScriptLike,
-  TransactionLike,
-  depTypeFrom,
-} from "../../ckb";
-import { hexFrom } from "../../hex";
-import { numToHex } from "../../num";
-import { apply } from "../../utils";
-import type { Client } from "../client";
-
-export type JsonRpcPayload = {
-  id: number;
-  jsonrpc: "2.0";
-  method: string;
-  params: unknown[] | Record<string, unknown>;
-};
-
-export type JsonRpcMethod = {
-  method: keyof Client;
-  rpcMethod: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  inTransformers: (((_: any) => unknown) | undefined)[];
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  outTransformer?: (_: any) => unknown;
-};
-
-export class JsonRpcTransformers {
-  static toDepType(depType: DepTypeLike) {
-    switch (depTypeFrom(depType)) {
-      case "code":
-        return "code";
-      case "depGroup":
-        return "dep_group";
-    }
-  }
-  static toScript(script: ScriptLike) {
-    return {
-      code_hash: script.codeHash,
-      hash_type: script.hashType,
-      args: script.args,
-    };
-  }
-  static toOutPoint(outPoint: OutPointLike) {
-    return {
-      index: numToHex(outPoint.index),
-      tx_hash: outPoint.txHash,
-    };
-  }
-  static toCellInput(cellInput: CellInputLike) {
-    return {
-      previous_output: JsonRpcTransformers.toOutPoint(cellInput.previousOutput),
-      since: numToHex(cellInput.since),
-    };
-  }
-  static toCellOutput(cellOutput: CellOutputLike) {
-    return {
-      capacity: numToHex(cellOutput.capacity),
-      lock: JsonRpcTransformers.toScript(cellOutput.lock),
-      type: apply(JsonRpcTransformers.toScript, cellOutput.type),
-    };
-  }
-  static toCellDep(cellDep: CellDepLike) {
-    return {
-      out_point: JsonRpcTransformers.toOutPoint(cellDep.outPoint),
-      dep_type: JsonRpcTransformers.toDepType(cellDep.depType),
-    };
-  }
-  static toTransaction(tx: TransactionLike) {
-    return {
-      version: numToHex(tx.version),
-      cell_deps: tx.cellDeps.map((c) => JsonRpcTransformers.toCellDep(c)),
-      header_deps: tx.headerDeps,
-      inputs: tx.inputs.map((i) => JsonRpcTransformers.toCellInput(i)),
-      outputs: tx.outputs.map((o) => JsonRpcTransformers.toCellOutput(o)),
-      outputs_data: tx.outputsData,
-      witnesses: tx.witnesses,
-    };
-  }
-}
-
-export const CkbRpcMethods: JsonRpcMethod[] = [
-  {
-    method: "sendTransaction",
-    rpcMethod: "send_transaction",
-    inTransformers: [JsonRpcTransformers.toTransaction],
-    outTransformer: hexFrom,
-  },
-];
+export * from "./transformers";
+export * from "./types";

package/src/client/jsonRpc/index.ts

@@ -1,8 +1,23 @@
 import fetch from "cross-fetch";
-import type { Client } from "../client";
-import { CkbRpcMethods, JsonRpcMethod, JsonRpcPayload } from "./advanced";
+import { TransactionLike } from "../../ckb";
+import { Hex, HexLike, hexFrom } from "../../hex";
+import { Client } from "../client";
+import { ClientTransactionResponse, OutputsValidator } from "../clientTypes";
+import { JsonRpcPayload, JsonRpcTransformers } from "./advanced";
 
-export interface ClientJsonRpc extends Pick<Client, "sendTransaction"> {}
+/**
+ * Applies a transformation function to a value if the transformer is provided.
+ *
+ * @param value - The value to be transformed.
+ * @param transformer - An optional transformation function.
+ * @returns The transformed value if a transformer is provided, otherwise the original value.
+ *
+ * @example
+ * ```typescript
+ * const result = await transform(5, (x) => x * 2); // Outputs 10
+ * const resultWithoutTransformer = await transform(5); // Outputs 5
+ * ```
+ */
 
 async function transform(
   value: unknown,
@@ -14,24 +29,80 @@ async function transform(
   return value;
 }
 
-export abstract class ClientJsonRpc implements Pick<Client, "sendTransaction"> {
+/**
+ * An abstract class implementing JSON-RPC client functionality for a specific URL and timeout.
+ * Provides methods for sending transactions and building JSON-RPC payloads.
+ */
+
+export abstract class ClientJsonRpc extends Client {
+  /**
+   * Creates an instance of ClientJsonRpc.
+   *
+   * @param url - The URL of the JSON-RPC server.
+   * @param timeout - The timeout for requests in milliseconds, default is 30000.
+   */
+
   constructor(
     private readonly url: string,
     private readonly timeout = 30000,
   ) {
-    CkbRpcMethods.map((method) =>
-      Object.defineProperty(this, method.method, {
-        value: this.buildSender(method),
-        enumerable: true,
-      }),
-    );
+    super();
   }
 
+  /**
+   * Returns the URL of the JSON-RPC server.
+   *
+   * @returns The URL of the JSON-RPC server.
+   */
+
   getUrl() {
     return this.url;
   }
 
-  buildSender({ rpcMethod, inTransformers, outTransformer }: JsonRpcMethod) {
+  /**
+   * Send a transaction to node.
+   *
+   * @param transaction - The transaction to send.
+   * @param validator - "passthrough": Disable validation. "well_known_scripts_only": Only accept well known scripts in the transaction.
+   * @returns Transaction hash.
+   */
+
+  sendTransaction = this.buildSender(
+    "send_transaction",
+    [JsonRpcTransformers.toTransaction],
+    hexFrom,
+  ) as (
+    transaction: TransactionLike,
+    validator?: OutputsValidator | undefined,
+  ) => Promise<Hex>;
+
+  /**
+   * Get a transaction from node.
+   *
+   * @param txHash - The hash of the transaction.
+   * @returns The transaction with status.
+   */
+
+  getTransaction = this.buildSender(
+    "get_transaction",
+    [hexFrom],
+    JsonRpcTransformers.fromTransactionResponse,
+  ) as (txHash: HexLike) => Promise<ClientTransactionResponse>;
+
+  /**
+   * Builds a sender function for a JSON-RPC method.
+   *
+   * @param rpcMethod - The JSON-RPC method.
+   * @param inTransformers - An array of input transformers.
+   * @param outTransformer - An output transformer function.
+   * @returns A function that sends a JSON-RPC request with the given method and transformed parameters.
+   */
+
+  buildSender(
+    rpcMethod: string,
+    inTransformers: (((_: any) => unknown) | undefined)[],
+    outTransformer?: (_: any) => unknown,
+  ) {
     return async (...req: unknown[]) => {
       const payload = ClientJsonRpc.buildPayload(
         rpcMethod,
@@ -42,6 +113,15 @@ export abstract class ClientJsonRpc implements Pick<Client, "sendTransaction"> {
     };
   }
 
+  /**
+   * Sends a JSON-RPC request to the server.
+   *
+   * @param payload - The JSON-RPC payload to send.
+   * @returns The result of the JSON-RPC request.
+   *
+   * @throws Will throw an error if the response ID does not match the request ID, or if the response contains an error.
+   */
+
   async send(payload: JsonRpcPayload) {
     const aborter = new AbortController();
     const abortTimer = setTimeout(() => aborter.abort(), this.timeout);
@@ -70,6 +150,14 @@ export abstract class ClientJsonRpc implements Pick<Client, "sendTransaction"> {
     return res.result;
   }
 
+  /**
+   * Builds a JSON-RPC payload for the given method and parameters.
+   *
+   * @param method - The JSON-RPC method name.
+   * @param req - The parameters for the JSON-RPC method.
+   * @returns The JSON-RPC payload.
+   */
+
   static buildPayload(method: string, req: unknown[]): JsonRpcPayload {
     return {
       id: Math.round(Math.random() * 10000),

package/src/client/jsonRpc/transformers.ts

@@ -0,0 +1,159 @@
+import {
+  CellDep,
+  CellDepLike,
+  CellInput,
+  CellInputLike,
+  CellOutput,
+  CellOutputLike,
+  DepType,
+  DepTypeLike,
+  HashType,
+  HashTypeLike,
+  OutPoint,
+  OutPointLike,
+  Script,
+  ScriptLike,
+  Transaction,
+  TransactionLike,
+  depTypeFrom,
+  hashTypeFrom,
+} from "../../ckb";
+import { numToHex } from "../../num";
+import { apply } from "../../utils";
+import { ClientTransactionResponse, TransactionStatus } from "../clientTypes";
+import {
+  JsonRpcCellDep,
+  JsonRpcCellInput,
+  JsonRpcCellOutput,
+  JsonRpcDepType,
+  JsonRpcHashType,
+  JsonRpcOutPoint,
+  JsonRpcScript,
+  JsonRpcTransaction,
+} from "./types";
+
+export class JsonRpcTransformers {
+  static toHashType(hashType: HashTypeLike): JsonRpcHashType {
+    return hashTypeFrom(hashType);
+  }
+  static fromHashType(hashType: JsonRpcHashType): HashType {
+    return hashType;
+  }
+  static toDepType(depType: DepTypeLike): JsonRpcDepType {
+    switch (depTypeFrom(depType)) {
+      case "code":
+        return "code";
+      case "depGroup":
+        return "dep_group";
+    }
+  }
+  static fromDepType(depType: JsonRpcDepType): DepType {
+    switch (depType) {
+      case "code":
+        return "code";
+      case "dep_group":
+        return "depGroup";
+    }
+  }
+  static toScript(scriptLike: ScriptLike): JsonRpcScript {
+    const script = Script.from(scriptLike);
+    return {
+      code_hash: script.codeHash,
+      hash_type: JsonRpcTransformers.toHashType(script.hashType),
+      args: script.args,
+    };
+  }
+  static fromScript(script: JsonRpcScript): Script {
+    return Script.from({
+      codeHash: script.code_hash,
+      hashType: JsonRpcTransformers.fromHashType(script.hash_type),
+      args: script.args,
+    });
+  }
+  static toOutPoint(outPointLike: OutPointLike): JsonRpcOutPoint {
+    const outPoint = OutPoint.from(outPointLike);
+    return {
+      index: numToHex(outPoint.index),
+      tx_hash: outPoint.txHash,
+    };
+  }
+  static fromOutPoint(outPoint: JsonRpcOutPoint): OutPoint {
+    return OutPoint.from({
+      index: outPoint.index,
+      txHash: outPoint.tx_hash,
+    });
+  }
+  static toCellInput(cellInput: CellInputLike): JsonRpcCellInput {
+    return {
+      previous_output: JsonRpcTransformers.toOutPoint(cellInput.previousOutput),
+      since: numToHex(cellInput.since),
+    };
+  }
+  static fromCellInput(cellInput: JsonRpcCellInput): CellInput {
+    return CellInput.from({
+      previousOutput: this.fromOutPoint(cellInput.previous_output),
+      since: cellInput.since,
+    });
+  }
+  static toCellOutput(cellOutput: CellOutputLike): JsonRpcCellOutput {
+    return {
+      capacity: numToHex(cellOutput.capacity),
+      lock: JsonRpcTransformers.toScript(cellOutput.lock),
+      type: apply(JsonRpcTransformers.toScript, cellOutput.type),
+    };
+  }
+  static fromCellOutput(cellOutput: JsonRpcCellOutput): CellOutput {
+    return CellOutput.from({
+      capacity: cellOutput.capacity,
+      lock: JsonRpcTransformers.fromScript(cellOutput.lock),
+      type: apply(JsonRpcTransformers.fromScript, cellOutput.type),
+    });
+  }
+  static toCellDep(cellDep: CellDepLike): JsonRpcCellDep {
+    return {
+      out_point: JsonRpcTransformers.toOutPoint(cellDep.outPoint),
+      dep_type: JsonRpcTransformers.toDepType(cellDep.depType),
+    };
+  }
+  static fromCellDep(cellDep: JsonRpcCellDep): CellDep {
+    return CellDep.from({
+      outPoint: JsonRpcTransformers.fromOutPoint(cellDep.out_point),
+      depType: JsonRpcTransformers.fromDepType(cellDep.dep_type),
+    });
+  }
+  static toTransaction(txLike: TransactionLike): JsonRpcTransaction {
+    const tx = Transaction.from(txLike);
+    return {
+      version: numToHex(tx.version),
+      cell_deps: tx.cellDeps.map((c) => JsonRpcTransformers.toCellDep(c)),
+      header_deps: tx.headerDeps,
+      inputs: tx.inputs.map((i) => JsonRpcTransformers.toCellInput(i)),
+      outputs: tx.outputs.map((o) => JsonRpcTransformers.toCellOutput(o)),
+      outputs_data: tx.outputsData,
+      witnesses: tx.witnesses,
+    };
+  }
+  static fromTransaction(tx: JsonRpcTransaction): Transaction {
+    return Transaction.from({
+      version: tx.version,
+      cellDeps: tx.cell_deps.map((c) => JsonRpcTransformers.fromCellDep(c)),
+      headerDeps: tx.header_deps,
+      inputs: tx.inputs.map((i) => JsonRpcTransformers.fromCellInput(i)),
+      outputs: tx.outputs.map((o) => JsonRpcTransformers.fromCellOutput(o)),
+      outputsData: tx.outputs_data,
+      witnesses: tx.witnesses,
+    });
+  }
+  static fromTransactionResponse({
+    tx_status: { status },
+    transaction,
+  }: {
+    tx_status: { status: TransactionStatus };
+    transaction: JsonRpcTransaction;
+  }): ClientTransactionResponse {
+    return {
+      transaction: JsonRpcTransformers.fromTransaction(transaction),
+      status,
+    };
+  }
+}

package/src/client/jsonRpc/types.ts

@@ -0,0 +1,48 @@
+import { Hex } from "../../hex";
+
+export type JsonRpcPayload = {
+  id: number;
+  jsonrpc: "2.0";
+  method: string;
+  params: unknown[] | Record<string, unknown>;
+};
+
+export type JsonRpcHashType = "type" | "data" | "data1" | "data2";
+export type JsonRpcDepType = "dep_group" | "code";
+
+export type JsonRpcScript = {
+  code_hash: Hex;
+  hash_type: JsonRpcHashType;
+  args: Hex;
+};
+
+export type JsonRpcOutPoint = {
+  index: Hex;
+  tx_hash: Hex;
+};
+
+export type JsonRpcCellInput = {
+  previous_output: JsonRpcOutPoint;
+  since: Hex;
+};
+
+export type JsonRpcCellOutput = {
+  capacity: Hex;
+  lock: JsonRpcScript;
+  type?: JsonRpcScript;
+};
+
+export type JsonRpcCellDep = {
+  out_point: JsonRpcOutPoint;
+  dep_type: JsonRpcDepType;
+};
+
+export type JsonRpcTransaction = {
+  version: Hex;
+  cell_deps: JsonRpcCellDep[];
+  header_deps: Hex[];
+  inputs: JsonRpcCellInput[];
+  outputs: JsonRpcCellOutput[];
+  outputs_data: Hex[];
+  witnesses: Hex[];
+};

package/src/fixedPoint/index.ts

@@ -1,8 +1,33 @@
+/**
+ * Represents a fixed point value as a bigint.
+ */
+
 export type FixedPoint = bigint;
+
+/**
+ * Represents a value that can be converted to a fixed point value.
+ * It can be a bigint, string, or number.
+ */
+
 export type FixedPointLike = bigint | string | number;
 
-export function fixedPointToString(val: FixedPoint, decimals = 8): string {
-  const str = val.toString();
+/**
+ * Converts a FixedPointLike value to its string representation with fixed-point decimals.
+ *
+ * @param val - The value to convert, which can be a bigint, string, or number.
+ * @param decimals - The number of decimal places for the fixed-point representation. Default is 8.
+ * @returns A string representing the fixed-point value.
+ *
+ * @example
+ * ```typescript
+ * const str = fixedPointToString(123456789n, 8); // Outputs "1.23456789"
+ * const strFromString = fixedPointToString("123456789", 8); // Outputs "1.23456789"
+ * const strFromNumber = fixedPointToString(123456789, 8); // Outputs "1.23456789"
+ * ```
+ */
+
+export function fixedPointToString(val: FixedPointLike, decimals = 8): string {
+  const str = fixedPointFrom(val).toString();
   const l = str.length <= decimals ? "0" : str.slice(0, -decimals);
   const r = str.slice(-decimals).padStart(decimals, "0").replace(/0*$/, "");
   if (r === "") {
@@ -12,6 +37,21 @@ export function fixedPointToString(val: FixedPoint, decimals = 8): string {
   return `${l}.${r}`;
 }
 
+/**
+ * Converts a FixedPointLike value to a FixedPoint (bigint) with fixed-point decimals.
+ *
+ * @param val - The value to convert, which can be a bigint, string, or number.
+ * @param decimals - The number of decimal places for the fixed-point representation. Default is 8.
+ * @returns A FixedPoint (bigint) representing the value with fixed-point decimals.
+ *
+ * @example
+ * ```typescript
+ * const fixedPoint = fixedPointFrom(1.23456789, 8); // Outputs 123456789n
+ * const fixedPointFromString = fixedPointFrom("1.23456789", 8); // Outputs 123456789n
+ * const fixedPointFromNumber = fixedPointFrom(1.23456789, 8); // Outputs 123456789n
+ * ```
+ */
+
 export function fixedPointFrom(val: FixedPointLike, decimals = 8): FixedPoint {
   if (typeof val === "bigint") {
     return val;
@@ -26,5 +66,15 @@ export function fixedPointFrom(val: FixedPointLike, decimals = 8): FixedPoint {
   return lVal + BigInt(r.slice(0, decimals).padEnd(decimals, "0"));
 }
 
+/**
+ * Represents the fixed point value of zero as a bigint.
+ */
+
 export const Zero = 0n;
+
+/**
+ * Represents the fixed point value of one as a FixedPoint (bigint).
+ * Equivalent to 1 in fixed-point representation with default decimals (8).
+ */
+
 export const One = fixedPointFrom("1");

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")}`;
 }