@kontor/kontor-sdk 1.0.0-alpha.0

package/src/sdk/clients/base/create-http-client.ts

@@ -0,0 +1,183 @@
+import type { ExactPartial, Prettify } from "../../../wit/type-utils.js";
+import { uid } from "../../utils/uid.js";
+import type { Account, JsonRpcAccount } from "../../accounts/types.js";
+import {
+  parseAccount,
+  type ParseAccountErrorType,
+} from "../../accounts/utils/parse-account.js";
+import type { ErrorType } from "../../errors/utils.js";
+import type { Chain } from "../../types/chain.js";
+import type { HttpRequestFn, HttpSchema } from "../../types/http-schema.js";
+import type { Address, XOnlyPubKey } from "../../types/misc.js";
+import type { HttpTransport } from "../transports/create-http-transport.js";
+
+export type HttpClientConfig<
+  transport extends HttpTransport = HttpTransport,
+  chain extends Chain | undefined = Chain | undefined,
+  accountOrAddress extends Account | [Address, XOnlyPubKey] | undefined =
+    | Account
+    | [Address, XOnlyPubKey]
+    | undefined,
+  httpSchema extends HttpSchema | undefined = undefined,
+> = {
+  /** The Account to use for the Client. This will be used for Actions that require an account as an argument. */
+  account?: accountOrAddress | Account | [Address, XOnlyPubKey] | undefined;
+  /**
+   * Time (in ms) that cached data will remain in memory.
+   * @default chain.blockTime / 3
+   */
+  cacheTime?: number | undefined;
+  /** Chain for the client. */
+  chain?: Chain | undefined | chain;
+  /** A key for the client. */
+  key?: string | undefined;
+  /** A name for the client. */
+  name?: string | undefined;
+  /**
+   * Frequency (in ms) for polling enabled actions & events.
+   * @default chain.blockTime / 3
+   */
+  pollingInterval?: number | undefined;
+  transport: transport;
+  /** The type of client. */
+  type?: string | undefined;
+  httpSchema?: httpSchema | undefined;
+};
+
+type HttpClient_Base<
+  transport extends HttpTransport = HttpTransport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  httpSchema extends HttpSchema | undefined = undefined,
+> = {
+  /** The Account of the Client. */
+  account: account;
+  /** Time (in ms) that cached data will remain in memory. */
+  cacheTime: number;
+  /** Chain for the client. */
+  chain: chain;
+  /** A key for the client. */
+  key: string;
+  /** A name for the client. */
+  name: string;
+  /** Frequency (in ms) for polling enabled actions & events. Defaults to 4_000 milliseconds. */
+  pollingInterval: number;
+  transport: ReturnType<transport>["config"] & ReturnType<transport>["value"];
+  /** The type of client. */
+  type: string;
+  /** A unique ID for the client. */
+  uid: string;
+
+  request: HttpRequestFn<
+    httpSchema extends undefined ? HttpSchema : httpSchema
+  >;
+};
+
+// TODO: fill this out
+type ExtendableProtectedActions = {};
+
+type Extended = Prettify<
+  { [_ in keyof HttpClient_Base]?: undefined } & {
+    [key: string]: unknown;
+  }
+>;
+
+export type HttpClient<
+  transport extends HttpTransport = HttpTransport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  httpSchema extends HttpSchema | undefined = undefined,
+  extended extends Extended | undefined = Extended | undefined,
+> = HttpClient_Base<transport, chain, account, httpSchema> &
+  (extended extends Extended ? extended : unknown) & {
+    extend: <
+      const client extends Extended & ExactPartial<ExtendableProtectedActions>,
+    >(
+      fn: (
+        client: HttpClient<transport, chain, account, httpSchema, extended>,
+      ) => client,
+    ) => HttpClient<
+      transport,
+      chain,
+      account,
+      httpSchema,
+      Prettify<client> & (extended extends Extended ? extended : unknown)
+    >;
+  };
+
+export type CreateClientErrorType = ParseAccountErrorType | ErrorType;
+
+export function createHttpClient<
+  transport extends HttpTransport,
+  chain extends Chain | undefined = undefined,
+  accountOrAddress extends
+    | Account
+    | [Address, XOnlyPubKey]
+    | undefined = undefined,
+  httpSchema extends HttpSchema | undefined = undefined,
+>(
+  parameters: HttpClientConfig<transport, chain, accountOrAddress, httpSchema>,
+): Prettify<
+  HttpClient<
+    transport,
+    chain,
+    accountOrAddress extends [Address, XOnlyPubKey]
+      ? // TODO: this might not be required here
+        Prettify<JsonRpcAccount<accountOrAddress[0], accountOrAddress[1]>>
+      : accountOrAddress,
+    httpSchema
+  >
+>;
+
+export function createHttpClient(parameters: HttpClientConfig): HttpClient {
+  const {
+    chain,
+    key = "base",
+    name = "Base Client",
+    type = "base",
+  } = parameters;
+
+  const blockTime = chain?.blockTime ?? 10 * 60 * 1000;
+
+  const defaultPollingInterval = Math.min(
+    Math.max(Math.floor(blockTime / 2), 500),
+    4_000,
+  );
+  const pollingInterval = parameters.pollingInterval ?? defaultPollingInterval;
+  const cacheTime = parameters.cacheTime ?? pollingInterval;
+
+  const account = parameters.account
+    ? parseAccount(parameters.account)
+    : undefined;
+  const { config, request, value } = parameters.transport({
+    // account,
+    chain,
+    pollingInterval,
+  });
+  const transport = { ...config, ...value };
+
+  const client = {
+    account,
+    cacheTime,
+    chain,
+    key,
+    name,
+    pollingInterval,
+    request,
+    transport,
+    type,
+    uid: uid(),
+  };
+
+  function extend(base: typeof client) {
+    type ExtendFn = (base: typeof client) => unknown;
+    return (extendFn: ExtendFn) => {
+      const extended = extendFn(base) as Extended;
+      for (const key in client) delete extended[key];
+      const combined = { ...base, ...extended };
+      return Object.assign(combined, { extend: extend(combined as any) });
+    };
+  }
+
+  return Object.assign(client, { extend: extend(client) as any });
+}

package/src/sdk/clients/base/create-rpc-client.test.ts

@@ -0,0 +1,155 @@
+import { assertType, describe, expect, test, vi } from "vitest";
+import { signet } from "../../chains/definitions/signet.js";
+
+import type { RpcRequestFn, RpcSchema } from "../../types/rpc-schema.js";
+import { createRpcTransport } from "../transports/create-rpc-transport.js";
+import { createRpcClient } from "./create-rpc-client.js";
+import { httpRpc } from "../transports/http-rpc.js";
+import { custom } from "../transports/custom.js";
+test("creates", () => {
+  const mockTransport = () =>
+    createRpcTransport({
+      key: "mock",
+      name: "Mock Transport",
+      request: vi.fn(async () => null) as unknown as RpcRequestFn<RpcSchema>,
+      type: "mock",
+    });
+  const { uid, ...client } = createRpcClient({
+    transport: mockTransport,
+  });
+
+  assertType<RpcRequestFn<RpcSchema>>(client.request);
+
+  expect(uid).toBeDefined();
+  expect(client).toMatchInlineSnapshot(`
+    {
+      "account": undefined,
+      "cacheTime": 4000,
+      "chain": undefined,
+      "extend": [Function],
+      "key": "base",
+      "name": "Base Client",
+      "pollingInterval": 4000,
+      "request": [Function],
+      "transport": {
+        "key": "mock",
+        "methods": undefined,
+        "name": "Mock Transport",
+        "request": [MockFunction],
+        "retryCount": 3,
+        "retryDelay": 150,
+        "timeout": undefined,
+        "type": "mock",
+      },
+      "type": "base",
+    }
+  `);
+});
+
+describe("transports", () => {
+  test("http", () => {
+    const { uid, ...client } = createRpcClient({
+      chain: signet,
+
+      transport: httpRpc<RpcSchema>(),
+    });
+
+    expect(uid).toBeDefined();
+
+    expect(client).toMatchInlineSnapshot(`
+ {
+   "account": undefined,
+   "cacheTime": 4000,
+   "chain": {
+     "blockExplorers": {
+       "default": {
+         "apiUrl": "https://mempool.space/signet/api",
+         "name": "mempool.space",
+         "url": "https://mempool.space/signet",
+       },
+     },
+     "blockTime": 600000,
+     "contracts": {
+       "nativeToken": {
+         "blockHeight": 0,
+         "name": "token",
+         "txIndex": 0,
+       },
+     },
+     "fees": undefined,
+     "formatters": undefined,
+     "id": 0,
+     "name": "signet",
+     "nativeCurrency": {
+       "decimals": 18,
+       "name": "Kontor",
+       "symbol": "KOR",
+     },
+     "serializers": undefined,
+     "urls": {
+       "default": {
+         "bitcoinRpc": [
+           "https://signet.kontor.network:38332",
+         ],
+         "http": [
+           "https://signet.kontor.network:35000/api",
+         ],
+         "webSocket": [
+           "wss://signet.kontor.network:35000/ws",
+         ],
+       },
+     },
+   },
+   "extend": [Function],
+   "key": "base",
+   "name": "Base Client",
+   "pollingInterval": 4000,
+   "request": [Function],
+   "transport": {
+     "fetchOptions": undefined,
+     "key": "http",
+     "methods": undefined,
+     "name": "HTTP JSON-RPC",
+     "request": [Function],
+     "retryCount": 3,
+     "retryDelay": 150,
+     "timeout": 10000,
+     "type": "http-rpc",
+     "url": "https://signet.kontor.network:38332",
+   },
+   "type": "base",
+ }
+    `);
+  });
+});
+
+test("custom", () => {
+  const { uid, ...client } = createRpcClient({
+    transport: custom({ request: async () => null }),
+  });
+
+  expect(uid).toBeDefined();
+  expect(client).toMatchInlineSnapshot(`
+      {
+        "account": undefined,
+        "cacheTime": 4000,
+        "chain": undefined,
+        "extend": [Function],
+        "key": "base",
+        "name": "Base Client",
+        "pollingInterval": 4000,
+        "request": [Function],
+        "transport": {
+          "key": "custom",
+          "methods": undefined,
+          "name": "Custom Provider",
+          "request": [Function],
+          "retryCount": 3,
+          "retryDelay": 150,
+          "timeout": undefined,
+          "type": "custom",
+        },
+        "type": "base",
+      }
+    `);
+});

package/src/sdk/clients/base/create-rpc-client.ts

@@ -0,0 +1,195 @@
+import type { Prettify, ExactPartial } from "../../../wit/type-utils.js";
+import type { Account, JsonRpcAccount } from "../../accounts/types.js";
+import {
+  parseAccount,
+  type ParseAccountErrorType,
+} from "../../accounts/utils/parse-account.js";
+import type { Chain } from "../../types/chain.js";
+import type { Address, XOnlyPubKey } from "../../types/misc.js";
+import type { WalletActions } from "../decorators/wallet.js";
+import type { RpcTransport } from "../transports/create-rpc-transport.js";
+import { uid } from "../../utils/uid.js";
+import type { ErrorType } from "../../errors/utils.js";
+import type { RpcRequestFn, RpcSchema } from "../../types/rpc-schema.js";
+import type { PublicActions } from "../decorators/public.js";
+
+export type RpcClientConfig<
+  transport extends RpcTransport = RpcTransport,
+  chain extends Chain | undefined = Chain | undefined,
+  accountOrAddress extends Account | [Address, XOnlyPubKey] | undefined =
+    | Account
+    | [Address, XOnlyPubKey]
+    | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+> = {
+  /** The Account to use for the Client. This will be used for Actions that require an account as an argument. */
+  account?: accountOrAddress | Account | [Address, XOnlyPubKey] | undefined;
+  /**
+   * Time (in ms) that cached data will remain in memory.
+   * @default chain.blockTime / 3
+   */
+  cacheTime?: number | undefined;
+  /** Chain for the client. */
+  chain?: Chain | undefined | chain;
+  /** A key for the client. */
+  key?: string | undefined;
+  /** A name for the client. */
+  name?: string | undefined;
+  /**
+   * Frequency (in ms) for polling enabled actions & events.
+   * @default chain.blockTime / 3
+   */
+  pollingInterval?: number | undefined;
+  /** The RPC transport */
+  transport: transport;
+  /** The type of client. */
+  type?: string | undefined;
+  /**
+   * Typed JSON-RPC schema for the client.
+   */
+  rpcSchema?: rpcSchema | undefined;
+};
+
+type RpcClient_Base<
+  transport extends RpcTransport = RpcTransport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+> = {
+  /** The Account of the Client. */
+  account: account;
+  /** Time (in ms) that cached data will remain in memory. */
+  cacheTime: number;
+  /** Chain for the client. */
+  chain: chain;
+  /** A key for the client. */
+  key: string;
+  /** A name for the client. */
+  name: string;
+  /** Frequency (in ms) for polling enabled actions & events. Defaults to 4_000 milliseconds. */
+  pollingInterval: number;
+  /** Request function wrapped with friendly error handling */
+  // request: EIP1193RequestFn<
+  //   rpcSchema extends undefined ? EIP1474Methods : rpcSchema
+  // >
+  /** The RPC transport */
+  transport: ReturnType<transport>["config"] & ReturnType<transport>["value"];
+  /** The type of client. */
+  type: string;
+  /** A unique ID for the client. */
+  uid: string;
+
+  request: RpcRequestFn<rpcSchema extends undefined ? RpcSchema : rpcSchema>;
+};
+
+type ExtendableProtectedActions<
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+> = Pick<PublicActions<chain, account>, "sendRawTransaction"> &
+  Pick<WalletActions<chain, account>, "getAddresses">;
+
+export type RpcClient<
+  transport extends RpcTransport = RpcTransport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+  extended extends Extended | undefined = Extended | undefined,
+> = RpcClient_Base<transport, chain, account, rpcSchema> &
+  (extended extends Extended ? extended : unknown) & {
+    extend: <
+      const client extends Extended &
+        ExactPartial<ExtendableProtectedActions<chain, account>>,
+    >(
+      fn: (
+        client: RpcClient<transport, chain, account, rpcSchema, extended>,
+      ) => client,
+    ) => RpcClient<
+      transport,
+      chain,
+      account,
+      rpcSchema,
+      Prettify<client> & (extended extends Extended ? extended : unknown)
+    >;
+  };
+
+type Extended = Prettify<
+  // disallow redefining base properties
+  { [_ in keyof RpcClient_Base]?: undefined } & {
+    [key: string]: unknown;
+  }
+>;
+export type CreateClientErrorType = ParseAccountErrorType | ErrorType;
+
+export function createRpcClient<
+  transport extends RpcTransport,
+  chain extends Chain | undefined = undefined,
+  accountOrAddress extends
+    | Account
+    | [Address, XOnlyPubKey]
+    | undefined = undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+>(
+  parameters: RpcClientConfig<transport, chain, accountOrAddress, rpcSchema>,
+): Prettify<
+  RpcClient<
+    transport,
+    chain,
+    accountOrAddress extends [Address, XOnlyPubKey]
+      ? Prettify<JsonRpcAccount<accountOrAddress[0], accountOrAddress[1]>>
+      : accountOrAddress,
+    rpcSchema
+  >
+>;
+
+export function createRpcClient(parameters: RpcClientConfig): RpcClient {
+  const {
+    chain,
+    key = "base",
+    name = "Base Client",
+    type = "base",
+  } = parameters;
+
+  const blockTime = chain?.blockTime ?? 10 * 60 * 1000;
+
+  const defaultPollingInterval = Math.min(
+    Math.max(Math.floor(blockTime / 2), 500),
+    4_000,
+  );
+  const pollingInterval = parameters.pollingInterval ?? defaultPollingInterval;
+  const cacheTime = parameters.cacheTime ?? pollingInterval;
+
+  const account = parameters.account
+    ? parseAccount(parameters.account)
+    : undefined;
+  const { config, request, value } = parameters.transport({
+    // account,
+    chain,
+    pollingInterval,
+  });
+  const transport = { ...config, ...value };
+
+  const client = {
+    account,
+    cacheTime,
+    chain,
+    key,
+    name,
+    pollingInterval,
+    request,
+    transport,
+    type,
+    uid: uid(),
+  };
+
+  function extend(base: typeof client) {
+    type ExtendFn = (base: typeof client) => unknown;
+    return (extendFn: ExtendFn) => {
+      const extended = extendFn(base) as Extended;
+      for (const key in client) delete extended[key];
+      const combined = { ...base, ...extended };
+      return Object.assign(combined, { extend: extend(combined as any) });
+    };
+  }
+
+  return Object.assign(client, { extend: extend(client) as any });
+}

package/src/sdk/clients/create-public-client.test.ts

@@ -0,0 +1,124 @@
+import { assertType, expect, test, vi } from "vitest";
+import { createPublicClient } from "./create-public-client.js";
+import { createRpcTransport } from "./transports/create-rpc-transport.js";
+import type { BtcRpcSchema } from "../types/btc-rpc.js";
+import type { RpcRequestFn } from "../types/rpc-schema.js";
+import { signet } from "../chains/definitions/signet.js";
+
+const mockTransport = () =>
+  createRpcTransport({
+    key: "mock",
+    name: "Mock Transport",
+    request: vi.fn(() => null) as any,
+    type: "mock",
+  });
+
+test("creates", () => {
+  const { uid, ...client } = createPublicClient({
+    transport: mockTransport,
+  });
+
+  assertType<RpcRequestFn<BtcRpcSchema>>(client.request);
+
+  expect(uid).toBeDefined();
+
+  expect(client).toMatchInlineSnapshot(`
+    {
+      "account": undefined,
+      "cacheTime": 4000,
+      "chain": undefined,
+      "extend": [Function],
+      "key": "btc-rpc",
+      "name": "BTC-RPC Client",
+      "pollingInterval": 4000,
+      "request": [Function],
+      "sendRawTransaction": [Function],
+      "transport": {
+        "key": "mock",
+        "methods": undefined,
+        "name": "Mock Transport",
+        "request": [MockFunction],
+        "retryCount": 3,
+        "retryDelay": 150,
+        "timeout": undefined,
+        "type": "mock",
+      },
+      "type": "btc-rpc-client",
+    }
+  `);
+});
+
+test("with chain", () => {
+  const { uid, ...client } = createPublicClient({
+    transport: mockTransport,
+    chain: signet,
+  });
+
+  assertType<RpcRequestFn<BtcRpcSchema>>(client.request);
+
+  expect(uid).toBeDefined();
+
+  expect(client).toMatchInlineSnapshot(`
+ {
+   "account": undefined,
+   "cacheTime": 4000,
+   "chain": {
+     "blockExplorers": {
+       "default": {
+         "apiUrl": "https://mempool.space/signet/api",
+         "name": "mempool.space",
+         "url": "https://mempool.space/signet",
+       },
+     },
+     "blockTime": 600000,
+     "contracts": {
+       "nativeToken": {
+         "blockHeight": 0,
+         "name": "token",
+         "txIndex": 0,
+       },
+     },
+     "fees": undefined,
+     "formatters": undefined,
+     "id": 0,
+     "name": "signet",
+     "nativeCurrency": {
+       "decimals": 18,
+       "name": "Kontor",
+       "symbol": "KOR",
+     },
+     "serializers": undefined,
+     "urls": {
+       "default": {
+         "bitcoinRpc": [
+           "https://signet.kontor.network:38332",
+         ],
+         "http": [
+           "https://signet.kontor.network:35000/api",
+         ],
+         "webSocket": [
+           "wss://signet.kontor.network:35000/ws",
+         ],
+       },
+     },
+   },
+   "extend": [Function],
+   "key": "btc-rpc",
+   "name": "BTC-RPC Client",
+   "pollingInterval": 4000,
+   "request": [Function],
+   "sendRawTransaction": [Function],
+   "transport": {
+     "key": "mock",
+     "methods": undefined,
+     "name": "Mock Transport",
+     "request": [MockFunction],
+     "retryCount": 3,
+     "retryDelay": 150,
+     "timeout": undefined,
+     "type": "mock",
+   },
+   "type": "btc-rpc-client",
+ }
+ `);
+});