@ckb-ccc/core 2.0.0-next.0 → 2.0.0-next.1

package/src/client/clientPublicTestnet.ts

@@ -1,55 +1,94 @@
 import WebSocket from "isomorphic-ws";
+import { RequestorJsonRpc } from "../jsonRpc/requestor.js";
+import type { ClientConfig } from "./client.js";
 import { TESTNET_SCRIPTS } from "./clientPublicTestnet.advanced.js";
-import { ScriptInfo, ScriptInfoLike } from "./clientTypes.js";
-import { ClientJsonRpc, ClientJsonRpcConfig } from "./jsonRpc/index.js";
-import { KnownScript } from "./knownScript.js";
+import { ClientJsonRpc, type ClientJsonRpcConfig } from "./jsonRpc/client.js";
 
 /**
  * @public
  */
 export class ClientPublicTestnet extends ClientJsonRpc {
+  private static defaultUrls(): readonly [string, ...string[]] {
+    return typeof WebSocket !== "undefined"
+      ? [
+          "wss://testnet.ckb.dev/ws",
+          "https://testnet.ckb.dev/",
+          "https://testnet.ckbapp.dev/",
+        ]
+      : ["https://testnet.ckb.dev/", "https://testnet.ckbapp.dev/"];
+  }
+
+  private static resolveConfig(
+    config?: ClientJsonRpcConfig & {
+      /** @deprecated URL belongs to Transport construction. */
+      url?: string;
+    },
+  ): ClientJsonRpcConfig & { url: string; fallbacks: string[] } {
+    const defaultUrls = this.defaultUrls();
+    return {
+      ...config,
+      url: config?.url ?? defaultUrls[0],
+      fallbacks: config?.fallbacks ?? [...defaultUrls],
+      scripts: config?.scripts ?? TESTNET_SCRIPTS,
+    };
+  }
+
+  /**
+   * @deprecated Use {@link ClientPublicTestnet.new} with a borrowed Transport or
+   * {@link ClientPublicTestnet.open} when creating Transports.
+   */
   constructor(
-    private readonly config?: ClientJsonRpcConfig & {
+    config?: ClientJsonRpcConfig & {
+      /** @deprecated URL belongs to Transport construction. */
       url?: string;
-      scripts?: Record<KnownScript, ScriptInfoLike | undefined>;
     },
   ) {
-    const hasWebSocket = typeof WebSocket !== "undefined";
-    super(
-      config?.url ??
-        (hasWebSocket
-          ? "wss://testnet.ckb.dev/ws"
-          : "https://testnet.ckb.dev/"),
-      {
-        ...config,
-        fallbacks:
-          config?.fallbacks ??
-          (hasWebSocket
-            ? [
-                "wss://testnet.ckb.dev/ws",
-                "https://testnet.ckb.dev/",
-                "https://testnet.ckbapp.dev/",
-              ]
-            : ["https://testnet.ckb.dev/", "https://testnet.ckbapp.dev/"]),
-      },
-    );
+    const resolved = ClientPublicTestnet.resolveConfig(config);
+    super(resolved.url, resolved);
   }
 
-  get scripts(): Record<KnownScript, ScriptInfoLike | undefined> {
-    return this.config?.scripts ?? TESTNET_SCRIPTS;
+  /** Creates a Client that borrows an existing Transport. */
+  static new(
+    config: Omit<Parameters<typeof RequestorJsonRpc.new>[0], "onError"> &
+      ClientConfig,
+  ): ClientPublicTestnet {
+    const { cache, scripts, ...requestorConfig } = config;
+    const requestor = this.newRequestor(requestorConfig);
+    return new ClientPublicTestnet({ cache, scripts, requestor });
   }
 
-  get addressPrefix(): string {
-    return "ckt";
+  /** Opens a Client with explicit ownership of its default dependencies. */
+  static open(
+    config?: Omit<
+      Parameters<typeof RequestorJsonRpc.open>[0],
+      "onError" | "urls"
+    > &
+      ClientConfig & {
+        urls?: Parameters<typeof RequestorJsonRpc.open>[0]["urls"];
+      },
+  ) {
+    const {
+      cache,
+      scripts,
+      urls = this.defaultUrls(),
+      ...requestorConfig
+    } = config ?? {};
+    return this.openRequestor({
+      ...requestorConfig,
+      urls,
+    }).map(
+      (requestor) =>
+        new ClientPublicTestnet({
+          cache,
+          scripts,
+          requestor,
+          url: urls[0],
+          fallbacks: [...urls.slice(1)],
+        }),
+    );
   }
 
-  async getKnownScript(script: KnownScript): Promise<ScriptInfo> {
-    const found = this.scripts[script];
-    if (!found) {
-      throw new Error(
-        `No script information was found for ${script} on ${this.addressPrefix}`,
-      );
-    }
-    return ScriptInfo.from(found);
+  get addressPrefix(): string {
+    return "ckt";
   }
 }

package/src/client/jsonRpc/client.ts

@@ -10,8 +10,8 @@ import {
   RequestorJsonRpcConfig,
 } from "../../jsonRpc/requestor.js";
 import { Num, NumLike, numFrom, numToHex } from "../../num/index.js";
-import { apply } from "../../utils/index.js";
-import { ClientCache } from "../cache/index.js";
+import { Owner, apply } from "../../utils/index.js";
+import type { ClientConfig } from "../client.js";
 import { Client } from "../client.js";
 import {
   ClientFindCellsResponse,
@@ -67,10 +67,35 @@ const ERROR_PARSERS: [
   ],
 ];
 
-export type ClientJsonRpcConfig = RequestorJsonRpcConfig & {
-  cache?: ClientCache;
-  requestor?: RequestorJsonRpc;
-};
+function handleJsonRpcError(errAny: unknown): never {
+  if (
+    typeof errAny !== "object" ||
+    errAny === null ||
+    !("data" in errAny) ||
+    typeof errAny.data !== "string"
+  ) {
+    throw errAny;
+  }
+  const err = errAny as ErrorClientBaseLike;
+
+  for (const [regexp, builder] of ERROR_PARSERS) {
+    const match = err.data.match(regexp);
+    if (match) {
+      throw builder(err, match);
+    }
+  }
+
+  throw new ErrorClientBase(err);
+}
+
+export type ClientJsonRpcConfig = RequestorJsonRpcConfig &
+  ClientConfig & {
+    /**
+     * @deprecated Requestor injection is supported only by legacy constructors.
+     * Use a borrowed Transport with `Client.new` or let `Client.open` create one.
+     */
+    requestor?: RequestorJsonRpc;
+  };
 
 /**
  * An abstract class implementing JSON-RPC client functionality for a specific URL and timeout.
@@ -84,42 +109,64 @@ export abstract class ClientJsonRpc extends Client {
    *
    * @param url_ - The URL of the JSON-RPC server.
    * @param timeout - The timeout for requests in milliseconds
+   * @deprecated Use the concrete Client's `new` or `open` method.
    */
 
-  constructor(url_: string, config?: ClientJsonRpcConfig) {
+  constructor(
+    private readonly url_: string,
+    config?: ClientJsonRpcConfig,
+  ) {
     super(config);
 
-    this.requestor =
-      config?.requestor ??
-      new RequestorJsonRpc(url_, config, (errAny) => {
-        if (
-          typeof errAny !== "object" ||
-          errAny === null ||
-          !("data" in errAny) ||
-          typeof errAny.data !== "string"
-        ) {
-          throw errAny;
-        }
-        const err = errAny as ErrorClientBaseLike;
-
-        for (const [regexp, builder] of ERROR_PARSERS) {
-          const match = err.data.match(regexp);
-          if (match) {
-            throw builder(err, match);
-          }
-        }
-
-        throw new ErrorClientBase(err);
+    const requestor = config?.requestor;
+    if (requestor) {
+      this.requestor = requestor;
+    } else if (config?.transport) {
+      this.requestor = RequestorJsonRpc.new({
+        transport: config.transport,
+        maxConcurrent: config.maxConcurrent,
+        onError: handleJsonRpcError,
       });
+    } else {
+      // Legacy constructor intentionally discards ownership.
+      this.requestor = RequestorJsonRpc.open({
+        urls: [url_, ...(config?.fallbacks ?? [])],
+        timeout: config?.timeout,
+        maxConcurrent: config?.maxConcurrent,
+        onError: handleJsonRpcError,
+      }).value;
+    }
+  }
+
+  /** Creates a Requestor that borrows an existing Transport. */
+  protected static newRequestor(
+    config: Omit<Parameters<typeof RequestorJsonRpc.new>[0], "onError">,
+  ): RequestorJsonRpc {
+    return RequestorJsonRpc.new({
+      ...config,
+      onError: handleJsonRpcError,
+    });
+  }
+
+  /** Opens a Requestor with ownership of its default Transport. */
+  protected static openRequestor(
+    config: Omit<Parameters<typeof RequestorJsonRpc.open>[0], "onError">,
+  ): Owner<RequestorJsonRpc> {
+    return RequestorJsonRpc.open({
+      ...config,
+      onError: handleJsonRpcError,
+    });
   }
 
   /**
-   * Returns the URL of the JSON-RPC server.
+   * Returns the legacy primary URL of the JSON-RPC server.
    *
    * @returns The URL of the JSON-RPC server.
+   * @deprecated A Client may use multiple endpoints or a Transport without a
+   * URL, so this value does not reliably identify its connection.
    */
   get url(): string {
-    return this.requestor.url;
+    return this.url_;
   }
 
   /**

package/src/client/jsonRpc/transformers.ts

@@ -212,10 +212,10 @@ export class JsonRpcTransformers {
     return {
       compactTarget: numFrom(header.compact_target),
       dao: {
-        c: numLeFromBytes(dao.slice(0, 8)),
-        ar: numLeFromBytes(dao.slice(8, 16)),
-        s: numLeFromBytes(dao.slice(16, 24)),
-        u: numLeFromBytes(dao.slice(24, 32)),
+        c: numLeFromBytes(dao.subarray(0, 8)),
+        ar: numLeFromBytes(dao.subarray(8, 16)),
+        s: numLeFromBytes(dao.subarray(16, 24)),
+        u: numLeFromBytes(dao.subarray(24, 32)),
       },
       epoch: Epoch.fromNum(header.epoch),
       extraHash: header.extra_hash,

package/src/jsonRpc/index.ts

@@ -1 +1,2 @@
 export * from "./requestor.js";
+export * from "./transports/index.js";

package/src/jsonRpc/requestor.ts

@@ -1,9 +1,27 @@
+import { abortSignalToPromise } from "../utils/abortSignal.js";
+import { OwnerAggregated } from "../utils/owner/aggregated.js";
+import { Owner } from "../utils/owner/owner.js";
+import { jsonRpcTransportFromUri } from "./transports/factory.js";
+import { JsonRpcTransportFallback } from "./transports/fallback.js";
 import {
+  JsonRpcError,
   JsonRpcPayload,
-  Transport,
-  TransportFallback,
-  transportFromUri,
-} from "./transports/advanced.js";
+  JsonRpcResponse,
+  JsonRpcTransport,
+  JsonRpcTransportRequestOptions,
+} from "./transports/index.js";
+
+function openTransports(
+  urls: readonly [string, ...string[]],
+  config?: { timeout?: number },
+): Owner<JsonRpcTransportFallback> {
+  const transportOwners = Array.from(new Set(urls), (url) =>
+    jsonRpcTransportFromUri(url, config),
+  );
+  return OwnerAggregated.from(transportOwners).map(
+    (transports) => new JsonRpcTransportFallback([...transports]),
+  );
+}
 
 /**
  * Applies a transformation function to a value if the transformer is provided.
@@ -25,11 +43,15 @@ function transform(value: unknown, transformer?: (i: unknown) => unknown) {
   return value;
 }
 
+/**
+ * @deprecated Used only by the legacy positional constructor. Use the static
+ * {@link RequestorJsonRpc.new} or {@link RequestorJsonRpc.open} methods.
+ */
 export type RequestorJsonRpcConfig = {
   fallbacks?: string[];
   timeout?: number;
   maxConcurrent?: number;
-  transport?: Transport;
+  transport?: JsonRpcTransport;
 };
 
 export class RequestorJsonRpc {
@@ -37,15 +59,17 @@ export class RequestorJsonRpc {
   private concurrent = 0;
   private readonly pending: (() => void)[] = [];
 
-  public readonly transport: Transport;
+  public readonly transport: JsonRpcTransport;
 
   private id = 0;
 
   /**
-   * Creates an instance of ClientJsonRpc.
+   * Creates a Requestor using legacy positional arguments.
    *
    * @param url_ - The URL of the JSON-RPC server.
    * @param timeout - The timeout for requests in milliseconds
+   * @deprecated Use {@link RequestorJsonRpc.new} with a borrowed Transport or
+   * {@link RequestorJsonRpc.open} when creating Transports.
    */
   constructor(
     private readonly url_: string,
@@ -53,20 +77,56 @@ export class RequestorJsonRpc {
     private readonly onError?: (err: unknown) => Promise<void> | void,
   ) {
     this.maxConcurrent = config?.maxConcurrent;
-    this.transport =
-      config?.transport ??
-      new TransportFallback(
-        Array.from(
-          new Set([url_, ...(config?.fallbacks ?? [])]).values(),
-          (url) => transportFromUri(url, config),
-        ),
-      );
+    if (config?.transport) {
+      this.transport = config.transport;
+    } else {
+      this.transport = openTransports(
+        [url_, ...(config?.fallbacks ?? [])],
+        config,
+      ).value;
+    }
+  }
+
+  /** Creates a Requestor that borrows an existing Transport. */
+  static new({
+    transport,
+    maxConcurrent,
+    onError,
+  }: {
+    transport: JsonRpcTransport;
+    maxConcurrent?: number;
+    onError?: (err: unknown) => Promise<void> | void;
+  }): RequestorJsonRpc {
+    return new RequestorJsonRpc("", { transport, maxConcurrent }, onError);
+  }
+
+  /** Opens a Requestor with ownership of its default transports. */
+  static open({
+    urls: [url, ...fallbacks],
+    onError,
+    ...config
+  }: {
+    urls: readonly [string, ...string[]];
+    timeout?: number;
+    maxConcurrent?: number;
+    onError?: (err: unknown) => Promise<void> | void;
+  }): Owner<RequestorJsonRpc> {
+    const transportOwner = openTransports([url, ...fallbacks], config);
+    return transportOwner.map((transport) =>
+      RequestorJsonRpc.new({
+        transport,
+        ...config,
+        onError,
+      }),
+    );
   }
 
   /**
    * Returns the URL of the JSON-RPC server.
    *
    * @returns The URL of the JSON-RPC server.
+   * @deprecated URL belongs to Transport construction and is unavailable for
+   * Requestors created with {@link RequestorJsonRpc.new}.
    */
 
   get url(): string {
@@ -89,6 +149,7 @@ export class RequestorJsonRpc {
     inTransformers?: (((_: any) => unknown) | undefined)[],
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     outTransformer?: (_: any) => unknown,
+    options?: JsonRpcTransportRequestOptions,
   ): Promise<unknown> {
     const payload = this.buildPayload(
       rpcMethod,
@@ -107,7 +168,7 @@ export class RequestorJsonRpc {
 
     try {
       return await transform(
-        await this.requestPayload(payload),
+        await this.requestPayload(payload, options),
         outTransformer,
       );
     } catch (err: unknown) {
@@ -118,36 +179,52 @@ export class RequestorJsonRpc {
     }
   }
 
-  async requestPayload(payload: JsonRpcPayload): Promise<unknown> {
+  async requestPayload(
+    payload: JsonRpcPayload,
+    options?: JsonRpcTransportRequestOptions,
+  ): Promise<unknown> {
     if (
       this.maxConcurrent !== undefined &&
       this.concurrent >= this.maxConcurrent
     ) {
-      const pending = new Promise<void>((resolve) =>
-        this.pending.push(resolve),
-      );
-      await pending;
+      options?.signal?.throwIfAborted();
+      let resolvePending: (() => void) | undefined;
+      const pending = new Promise<void>((resolve) => {
+        resolvePending = resolve;
+        this.pending.push(resolve);
+      });
+      try {
+        await (options?.signal
+          ? Promise.race([pending, abortSignalToPromise(options.signal)])
+          : pending);
+      } catch (cause) {
+        const index = resolvePending
+          ? this.pending.indexOf(resolvePending)
+          : -1;
+        if (index !== -1) {
+          this.pending.splice(index, 1);
+        } else {
+          this.pending.shift()?.();
+        }
+        throw cause;
+      }
     }
 
-    const res = (await (async () => {
+    const res: JsonRpcResponse = await (async () => {
       this.concurrent += 1;
       try {
-        return await this.transport.request(payload);
+        return await this.transport.request(payload, options);
       } finally {
         this.concurrent -= 1;
         this.pending.shift()?.();
       }
-    })()) as {
-      id: number;
-      error: unknown;
-      result: unknown;
-    };
+    })();
 
     if (res.id !== payload.id) {
       throw new Error(`Id mismatched, got ${res.id}, expected ${payload.id}`);
     }
     if (res.error != null) {
-      throw res.error as unknown;
+      throw new JsonRpcError(res.error);
     }
     return res.result;
   }

package/src/jsonRpc/transports/advanced.ts

@@ -1,5 +1 @@
 export * from "./factory.js";
-export * from "./fallback.js";
-export * from "./http.js";
-export * from "./transport.js";
-export * from "./webSocket.js";

package/src/jsonRpc/transports/factory.ts

@@ -1,10 +1,17 @@
-import { TransportHttp } from "./http.js";
-import { TransportWebSocket } from "./webSocket.js";
+import { OwnerUnique } from "../../utils/owner/unique.js";
+import { JsonRpcTransportHttp } from "./http.js";
+import { JsonRpcTransportWebSocket } from "./webSocket.js";
 
-export function transportFromUri(uri: string, config?: { timeout?: number }) {
+export function jsonRpcTransportFromUri(
+  uri: string,
+  config?: { timeout?: number },
+) {
   if (uri.startsWith("wss://") || uri.startsWith("ws://")) {
-    return new TransportWebSocket(uri, config?.timeout);
+    return JsonRpcTransportWebSocket.open(uri, config?.timeout);
   }
 
-  return new TransportHttp(uri, config?.timeout);
+  return new OwnerUnique(
+    new JsonRpcTransportHttp(uri, config?.timeout),
+    () => {},
+  );
 }

package/src/jsonRpc/transports/fallback.ts

@@ -1,22 +1,30 @@
-import { JsonRpcPayload, Transport } from "./transport.js";
+import {
+  JsonRpcPayload,
+  JsonRpcResponse,
+  JsonRpcTransport,
+  JsonRpcTransportRequestOptions,
+} from "./transport.js";
 
-export class TransportFallback implements Transport {
+export class JsonRpcTransportFallback implements JsonRpcTransport {
   // Current transport index
   private i = 0;
 
-  constructor(private readonly transports: Transport[]) {}
+  constructor(private readonly transports: JsonRpcTransport[]) {}
 
-  async request(data: JsonRpcPayload): Promise<unknown> {
+  async request(
+    data: JsonRpcPayload,
+    options?: JsonRpcTransportRequestOptions,
+  ): Promise<JsonRpcResponse> {
     const startI = this.i;
     let lastErr: unknown = new Error(
-      "TransportFallback requires at least one transport",
+      "JsonRpcTransportFallback requires at least one transport",
     );
 
     for (let tried = 0; tried < this.transports.length; tried += 1) {
       const i = (startI + tried) % this.transports.length;
 
       try {
-        const res = await this.transports[i].request(data);
+        const res = await this.transports[i].request(data, options);
 
         this.i = i;
         return res;

package/src/jsonRpc/transports/http.ts

@@ -1,28 +1,35 @@
-import { JsonRpcPayload, Transport } from "./transport.js";
+import { abortSignalAny } from "../../utils/abortSignal.js";
+import {
+  JsonRpcPayload,
+  JsonRpcResponse,
+  JsonRpcTransport,
+  JsonRpcTransportRequestOptions,
+} from "./transport.js";
 
-export class TransportHttp implements Transport {
+export class JsonRpcTransportHttp implements JsonRpcTransport {
   constructor(
     private readonly url: string,
     private readonly timeout = 30000,
   ) {}
 
-  async request(payload: JsonRpcPayload) {
-    const aborter = new AbortController();
-    const abortTimer = setTimeout(() => aborter.abort(), this.timeout);
+  async request(
+    payload: JsonRpcPayload,
+    options?: JsonRpcTransportRequestOptions,
+  ): Promise<JsonRpcResponse> {
+    const timeoutSignal = AbortSignal.timeout(options?.timeout ?? this.timeout);
+    const signal = options?.signal
+      ? abortSignalAny([options.signal, timeoutSignal])
+      : timeoutSignal;
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    const raw = await (
+    return (await (
       await fetch(this.url, {
         method: "POST",
         headers: {
           "content-type": "application/json",
         },
         body: JSON.stringify(payload),
-        signal: aborter.signal,
+        signal,
       })
-    ).json();
-    clearTimeout(abortTimer);
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return raw;
+    ).json()) as JsonRpcResponse;
   }
 }

package/src/jsonRpc/transports/index.ts

@@ -0,0 +1,4 @@
+export * from "./fallback.js";
+export * from "./http.js";
+export * from "./transport.js";
+export * from "./webSocket.js";

package/src/jsonRpc/transports/transport.ts

@@ -1,18 +1,54 @@
+export type JsonRpcId = string | number;
+
 export type JsonRpcPayload = {
-  id: number;
+  id: JsonRpcId;
   jsonrpc: "2.0";
   method: string;
   params: unknown[] | Record<string, unknown>;
 };
 
-export interface Transport {
+export type JsonRpcErrorLike<Data = unknown> = {
+  code: number;
+  message: string;
+  data?: Data;
+};
+
+export class JsonRpcError<Data = unknown> extends Error {
+  readonly code: number;
+  readonly data?: Data;
+
+  constructor(error: JsonRpcErrorLike<Data>) {
+    super(error.message);
+    this.name = "JsonRpcError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+}
+
+export type JsonRpcResponse<Result = unknown, ErrorData = unknown> = {
+  id: JsonRpcId;
+  jsonrpc: "2.0";
+} & (
+  | { result: Result; error?: never }
+  | { result?: never; error: JsonRpcErrorLike<ErrorData> }
+);
+
+export type JsonRpcTransportRequestOptions = {
+  /** Cancels this individual request without disposing the transport. */
+  signal?: AbortSignal;
+  /** Overrides the transport's default timeout for this request. */
+  timeout?: number;
+};
+
+export interface JsonRpcTransport {
   /**
    * 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.
+   * @returns The JSON-RPC response.
    */
-  request(data: JsonRpcPayload): Promise<unknown>;
+  request(
+    payload: JsonRpcPayload,
+    options?: JsonRpcTransportRequestOptions,
+  ): Promise<JsonRpcResponse>;
 }