@kontor/kontor-sdk 1.0.0-alpha.0

package/src/sdk/clients/transports/http.ts

@@ -0,0 +1,130 @@
+import {
+  UrlRequiredError,
+  type UrlRequiredErrorType,
+} from "../../errors/transport.js";
+import type { ErrorType } from "../../errors/utils.js";
+import type { HttpRequestFn, HttpSchema } from "../../types/http-schema.js";
+import { getHttpClient, type HttpClientOptions } from "../../utils/http.js";
+
+import {
+  type CreateTransportErrorType,
+  type HttpTransportConfig as HttpTransportConfig_,
+  type HttpTransport as HttpTransport_,
+  createHttpTransport,
+} from "./create-http-transport.js";
+
+export type HttpTransportConfig<
+  httpSchema extends HttpSchema | undefined = undefined,
+  // raw extends boolean = false,
+> = {
+  fetchFn?: HttpClientOptions["fetchFn"] | undefined;
+  /**
+   * Request configuration to pass to `fetch`.
+   * @link https://developer.mozilla.org/en-US/docs/Web/API/fetch
+   */
+  fetchOptions?: HttpClientOptions["fetchOptions"] | undefined;
+  /** A callback to handle the response from `fetch`. */
+  onFetchRequest?: HttpClientOptions["onRequest"] | undefined;
+  /** A callback to handle the response from `fetch`. */
+  onFetchResponse?: HttpClientOptions["onResponse"] | undefined;
+  /** The key of the HTTP transport. */
+  key?: HttpTransportConfig_["key"] | undefined;
+  /** Methods to include or exclude from executing RPC requests. */
+  // methods?: RpcTransportConfig["methods"] | undefined;
+  /** The name of the HTTP transport. */
+  name?: HttpTransportConfig_["name"] | undefined;
+  /** Whether to return JSON RPC errors as responses instead of throwing. */
+  // raw?: raw | boolean | undefined;
+  /** The max number of times to retry. */
+  retryCount?: HttpTransportConfig_["retryCount"] | undefined;
+  /** The base delay (in ms) between retries. */
+  retryDelay?: HttpTransportConfig_["retryDelay"] | undefined;
+  /** Typed JSON-RPC schema for the transport. */
+  httpSchema?: httpSchema | HttpSchema | undefined;
+  /** The timeout (in ms) for the HTTP request. Default: 10_000 */
+  timeout?: HttpTransportConfig_["timeout"] | undefined;
+};
+
+export type HttpTransport<
+  httpSchema extends HttpSchema | undefined = undefined,
+> = HttpTransport_<
+  "http",
+  {
+    fetchOptions?: HttpTransportConfig["fetchOptions"] | undefined;
+    url?: string | undefined;
+  },
+  HttpRequestFn<httpSchema>
+>;
+
+export type HttpTransportErrorType =
+  | CreateTransportErrorType
+  | UrlRequiredErrorType
+  | ErrorType;
+
+export function http<httpSchema extends HttpSchema | undefined = undefined>(
+  url?: string | undefined,
+  config: HttpTransportConfig<httpSchema> = {},
+): HttpTransport<httpSchema> {
+  const {
+    fetchFn,
+    fetchOptions,
+    key = "http",
+    name = "HTTP Transport",
+    onFetchRequest,
+    onFetchResponse,
+    retryDelay,
+  } = config;
+
+  return ({ chain, retryCount: retryCount_, timeout: timeout_ }) => {
+    const retryCount = config.retryCount ?? retryCount_;
+    const timeout = timeout_ ?? config.timeout ?? 10_000;
+    const url_ = url || chain?.urls.default.http[0];
+    if (!url_) throw new UrlRequiredError();
+
+    console.log(url_);
+
+    const httpClient = getHttpClient(url_, {
+      fetchFn,
+      fetchOptions,
+      onRequest: onFetchRequest,
+      onResponse: onFetchResponse,
+      timeout,
+    });
+
+    return createHttpTransport<"http", {}, HttpRequestFn<httpSchema>>(
+      {
+        key,
+        name,
+        async request({ route, method, path, query, body }) {
+          // TODO: unify BodyParams with other body type
+          const fn = async (
+            route: any,
+            method: any,
+            body: any,
+            path: any,
+            query: any,
+          ) =>
+            await httpClient.request({
+              route,
+              method,
+              body,
+              path,
+              query,
+            });
+
+          const result = await fn(route, method, body, path, query);
+
+          return result;
+        },
+        retryCount,
+        retryDelay,
+        timeout,
+        type: "http" as const,
+      },
+      {
+        fetchOptions,
+        url: url_,
+      },
+    );
+  };
+}

package/src/sdk/contracts/wits.ts

@@ -0,0 +1,36 @@
+import type { ResolvedRegister } from "../../wit/register.js";
+import { parseWit } from "../../wit/wit-parser/parse-wit.js";
+
+type ContractExport = {
+  raw: readonly string[];
+  wit: ReturnType<typeof parseWit>;
+  address: ResolvedRegister["contractAddress"];
+};
+
+const nativeTokenRaw = [
+  "record balance { acc: string, amt: decimal }",
+  "record transfer { src: string, dst: string, amt: decimal }",
+  "record burn { src: string, amt: decimal }",
+  "record mint { dst: string, amt: decimal }",
+
+  "export issuance: func(ctx: borrow<core-context>, amt: decimal) -> result<mint, error>;",
+  "export hold: func(ctx: borrow<core-context>, amt: decimal) -> result<transfer, error>;",
+  "export release: func(ctx: borrow<core-context>, burn-amt: decimal) -> result<burn, error>;",
+  "export init: func(ctx: borrow<proc-context>);",
+  "export mint: func(ctx: borrow<proc-context>, amt: decimal) -> result<mint, error>;",
+  "export burn: func(ctx: borrow<proc-context>, amt: decimal) -> result<burn, error>;",
+  "export transfer: func(ctx: borrow<proc-context>, dst: string, amt: decimal) -> result<transfer, error>;",
+  "export balance: func(ctx: borrow<view-context>, acc: string) -> option<decimal>;",
+  "export balances: func(ctx: borrow<view-context>) -> list<balance>;",
+  "export total-supply: func(ctx: borrow<view-context>) -> decimal;",
+  "export attach: func(ctx: borrow<proc-context>, vout: u64, amt: decimal) -> result<transfer, error>;",
+  "export detach: func(ctx: borrow<proc-context>) -> result<transfer, error>;",
+] as const;
+
+const nativeTokenWit = parseWit(nativeTokenRaw);
+
+export const nativeToken: ContractExport = {
+  raw: nativeTokenRaw,
+  wit: nativeTokenWit,
+  address: "token_0_0",
+};

package/src/sdk/errors/address.ts

@@ -0,0 +1,16 @@
+import { BaseError } from "./base.js";
+
+export type InvalidAddressErrorType = InvalidAddressError & {
+  name: "InvalidAddressError";
+};
+export class InvalidAddressError extends BaseError {
+  constructor({ address }: { address: string }) {
+    super(`Address "${address}" is invalid.`, {
+      metaMessages: [
+        "- Address must be a hex value of 20 bytes (40 hex characters).",
+        "- Address must match its checksum counterpart.",
+      ],
+      name: "InvalidAddressError",
+    });
+  }
+}

package/src/sdk/errors/base.ts

@@ -0,0 +1,98 @@
+const version = "1.0.0"; // TODO: Replace with actual version or import from package.json
+
+type ErrorConfig = {
+  getDocsUrl?: ((args: BaseErrorParameters) => string | undefined) | undefined;
+  version?: string | undefined;
+};
+
+let errorConfig: ErrorConfig = {
+  getDocsUrl: ({
+    docsBaseUrl,
+    docsPath = "",
+    docsSlug,
+  }: BaseErrorParameters) =>
+    docsPath
+      ? `${docsBaseUrl ?? "https://docs.kontor.network"}${docsPath}${
+          docsSlug ? `#${docsSlug}` : ""
+        }`
+      : undefined,
+  version: `kontor-sdk@${version}`,
+};
+
+export function setErrorConfig(config: ErrorConfig) {
+  errorConfig = config;
+}
+
+type BaseErrorParameters = {
+  cause?: BaseError | Error | undefined;
+  details?: string | undefined;
+  docsBaseUrl?: string | undefined;
+  docsPath?: string | undefined;
+  docsSlug?: string | undefined;
+  metaMessages?: string[] | undefined;
+  name?: string | undefined;
+};
+
+export type BaseErrorType = BaseError & { name: "BaseError" };
+export class BaseError extends Error {
+  details: string;
+  docsPath?: string | undefined;
+  metaMessages?: string[] | undefined;
+  shortMessage: string;
+  version: string;
+
+  override name = "BaseError";
+
+  constructor(shortMessage: string, args: BaseErrorParameters = {}) {
+    const details = (() => {
+      if (args.cause instanceof BaseError) return args.cause.details;
+      if (args.cause?.message) return args.cause.message;
+      return args.details!;
+    })();
+    const docsPath = (() => {
+      if (args.cause instanceof BaseError)
+        return args.cause.docsPath || args.docsPath;
+      return args.docsPath;
+    })();
+    const docsUrl = errorConfig.getDocsUrl?.({ ...args, docsPath });
+
+    const message = [
+      shortMessage || "An error occurred.",
+      "",
+      ...(args.metaMessages ? [...args.metaMessages, ""] : []),
+      ...(docsUrl ? [`Docs: ${docsUrl}`] : []),
+      ...(details ? [`Details: ${details}`] : []),
+      ...(errorConfig.version ? [`Version: ${errorConfig.version}`] : []),
+    ].join("\n");
+
+    super(message, args.cause ? { cause: args.cause } : undefined);
+
+    this.details = details;
+    this.docsPath = docsPath;
+    this.metaMessages = args.metaMessages;
+    this.name = args.name ?? this.name;
+    this.shortMessage = shortMessage;
+    this.version = version;
+  }
+
+  walk(): Error;
+  walk(fn: (err: unknown) => boolean): Error | null;
+  walk(fn?: any): any {
+    return walk(this, fn);
+  }
+}
+
+function walk(
+  err: unknown,
+  fn?: ((err: unknown) => boolean) | undefined,
+): unknown {
+  if (fn?.(err)) return err;
+  if (
+    err &&
+    typeof err === "object" &&
+    "cause" in err &&
+    err.cause !== undefined
+  )
+    return walk(err.cause, fn);
+  return fn ? null : err;
+}

package/src/sdk/errors/request.ts

@@ -0,0 +1,134 @@
+import { stringify } from "../utils/stringify.js";
+
+import { BaseError } from "./base.js";
+import { getUrl } from "./utils.js";
+
+export type HttpRequestErrorType = HttpRequestError & {
+  name: "HttpRequestError";
+};
+export class HttpRequestError extends BaseError {
+  body?: { [x: string]: unknown } | { [y: string]: unknown }[] | undefined;
+  headers?: Headers | undefined;
+  status?: number | undefined;
+  url: string;
+
+  constructor({
+    body,
+    cause,
+    details,
+    headers,
+    status,
+    url,
+  }: {
+    body?: { [x: string]: unknown } | { [y: string]: unknown }[] | undefined;
+    cause?: Error | undefined;
+    details?: string | undefined;
+    headers?: Headers | undefined;
+    status?: number | undefined;
+    url: string;
+  }) {
+    super("HTTP request failed.", {
+      cause,
+      details,
+      metaMessages: [
+        status && `Status: ${status}`,
+        `URL: ${getUrl(url)}`,
+        body && `Request body: ${stringify(body)}`,
+      ].filter(Boolean) as string[],
+      name: "HttpRequestError",
+    });
+    this.body = body;
+    this.headers = headers;
+    this.status = status;
+    this.url = url;
+  }
+}
+
+export type WebSocketRequestErrorType = WebSocketRequestError & {
+  name: "WebSocketRequestError";
+};
+export class WebSocketRequestError extends BaseError {
+  constructor({
+    body,
+    cause,
+    details,
+    url,
+  }: {
+    body?: { [key: string]: unknown } | undefined;
+    cause?: Error | undefined;
+    details?: string | undefined;
+    url: string;
+  }) {
+    super("WebSocket request failed.", {
+      cause,
+      details,
+      metaMessages: [
+        `URL: ${getUrl(url)}`,
+        body && `Request body: ${stringify(body)}`,
+      ].filter(Boolean) as string[],
+      name: "WebSocketRequestError",
+    });
+  }
+}
+
+export type RpcRequestErrorType = RpcRequestError & {
+  name: "RpcRequestError";
+};
+export class RpcRequestError extends BaseError {
+  code: number;
+  data?: unknown;
+
+  constructor({
+    body,
+    error,
+    url,
+  }: {
+    body: { [x: string]: unknown } | { [y: string]: unknown }[];
+    error: { code: number; data?: unknown; message: string };
+    url: string;
+  }) {
+    super("RPC Request failed.", {
+      cause: error as any,
+      details: error.message,
+      metaMessages: [`URL: ${getUrl(url)}`, `Request body: ${stringify(body)}`],
+      name: "RpcRequestError",
+    });
+    this.code = error.code;
+    this.data = error.data;
+  }
+}
+
+export type SocketClosedErrorType = SocketClosedError & {
+  name: "SocketClosedError";
+};
+export class SocketClosedError extends BaseError {
+  constructor({
+    url,
+  }: {
+    url?: string | undefined;
+  } = {}) {
+    super("The socket has been closed.", {
+      metaMessages: [url && `URL: ${getUrl(url)}`].filter(Boolean) as string[],
+      name: "SocketClosedError",
+    });
+  }
+}
+
+export type TimeoutErrorType = TimeoutError & {
+  name: "TimeoutError";
+};
+export class TimeoutError extends BaseError {
+  constructor({
+    body,
+    url,
+  }: {
+    body: { [x: string]: unknown } | { [y: string]: unknown }[];
+    url: string;
+  }) {
+    super("The request took too long to respond.", {
+      details: "The request timed out.",
+      metaMessages: [`URL: ${getUrl(url)}`, `Request body: ${stringify(body)}`],
+      name: "TimeoutError",
+    });
+  }
+}

package/src/sdk/errors/rpc.ts

@@ -0,0 +1,65 @@
+import { BaseError } from "./base.js";
+import { RpcRequestError } from "./request.js";
+
+const unknownErrorCode = -1;
+export type RpcErrorCode =
+  | -1
+  | -32700 // Parse error
+  | -32600 // Invalid request
+  | -32601 // Method not found
+  | -32602 // Invalid params
+  | -32603 // Internal error
+  | -32000 // Invalid input
+  | -32001 // Resource not found
+  | -32002 // Resource unavailable
+  | -32003 // Transaction rejected
+  | -32004 // Method not supported
+  | -32005 // Limit exceeded
+  | -32006 // JSON-RPC version not supported
+  | -32042; // Method not found
+
+type RpcErrorOptions<code extends number = RpcErrorCode> = {
+  code?: code | (number & {}) | undefined;
+  docsPath?: string | undefined;
+  metaMessages?: string[] | undefined;
+  name?: string | undefined;
+  shortMessage: string;
+};
+
+export class RpcError<code_ extends number = RpcErrorCode> extends BaseError {
+  code: code_ | (number & {});
+
+  constructor(
+    cause: Error,
+    {
+      code,
+      docsPath,
+      metaMessages,
+      name,
+      shortMessage,
+    }: RpcErrorOptions<code_>,
+  ) {
+    super(shortMessage, {
+      cause,
+      docsPath,
+      metaMessages:
+        metaMessages || (cause as { metaMessages?: string[] })?.metaMessages,
+      name: name || "RpcError",
+    });
+    this.name = name || cause.name;
+    this.code = (
+      cause instanceof RpcRequestError ? cause.code : (code ?? unknownErrorCode)
+    ) as code_;
+  }
+}
+export type UnknownRpcErrorType = UnknownRpcError & {
+  name: "UnknownRpcError";
+};
+export class UnknownRpcError extends RpcError {
+  constructor(cause: Error) {
+    super(cause, {
+      name: "UnknownRpcError",
+      shortMessage: "An unknown RPC error occurred.",
+    });
+  }
+}

package/src/sdk/errors/transport.ts

@@ -0,0 +1,16 @@
+import { BaseError } from "./base.js";
+
+export type UrlRequiredErrorType = UrlRequiredError & {
+  name: "UrlRequiredError";
+};
+export class UrlRequiredError extends BaseError {
+  constructor() {
+    super(
+      "No URL was provided to the Transport. Please provide a valid RPC URL to the Transport.",
+      {
+        docsPath: "/docs/clients/intro",
+        name: "UrlRequiredError",
+      },
+    );
+  }
+}

package/src/sdk/errors/utils.ts

@@ -0,0 +1,3 @@
+export type ErrorType<name extends string = "Error"> = Error & { name: name };
+
+export const getUrl = (url: string) => url;

package/src/sdk/errors/version.ts

@@ -0,0 +1 @@
+export const version = "1.0.0";

package/src/sdk/errors/wit.ts

@@ -0,0 +1,36 @@
+import { BaseError } from "./base.js";
+
+export type WitEncodingLengthMismatchErrorType =
+  WitEncodingLengthMismatchError & {
+    name: "WitEncodingLengthMismatchError";
+  };
+export class WitEncodingLengthMismatchError extends BaseError {
+  constructor({
+    expectedLength,
+    givenLength,
+  }: {
+    expectedLength: number;
+    givenLength: number;
+  }) {
+    super(
+      [
+        "WIT encoding params/values length mismatch.",
+        `Expected length (params): ${expectedLength}`,
+        `Given length (values): ${givenLength}`,
+      ].join("\n"),
+      { name: "WitEncodingLengthMismatchError" },
+    );
+  }
+}
+
+export class InvalidWitEncodingTypeError extends BaseError {
+  constructor(type: string, { docsPath }: { docsPath: string }) {
+    super(
+      [
+        `Type "${type}" is not a valid encoding type.`,
+        "Please provide a valid WIT type.",
+      ].join("\n"),
+      { docsPath, name: "InvalidWitEncodingType" },
+    );
+  }
+}

package/src/sdk/test/e2e.test.ts

@@ -0,0 +1,87 @@
+import { test } from "vitest";
+// import { procContract } from "./proc-contract.js";
+import { parseWit } from "../../wit/wit-parser/parse-wit.js";
+import { createPublicClient as createKontorPublicClient } from "../clients/kontor/create-public-client.js";
+import { http } from "../clients/transports/http.js";
+import { mnemonicToAccount } from "../accounts/mnemonic-to-account.js";
+import { createWalletClient as createKontorWalletClient } from "../clients/kontor/create-wallet-client.js";
+import { custom } from "../clients/transports/custom.js";
+import { Transaction } from "@scure/btc-signer";
+import { hex } from "@scure/base";
+import { signet } from "../chains/definitions/signet.js";
+
+export const nativeTokenRaw = [
+  "record balance { acc: string, amt: decimal }",
+  "record transfer { src: string, dst: string, amt: decimal }",
+  "record burn { src: string, amt: decimal }",
+  "record mint { dst: string, amt: decimal }",
+
+  "export issuance: func(ctx: borrow<core-context>, amt: decimal) -> result<mint, error>;",
+  "export hold: func(ctx: borrow<core-context>, amt: decimal) -> result<transfer, error>;",
+  "export release: func(ctx: borrow<core-context>, burn-amt: decimal) -> result<burn, error>;",
+  "export init: func(ctx: borrow<proc-context>);",
+  "export mint: func(ctx: borrow<proc-context>, amt: decimal) -> result<mint, error>;",
+  "export burn: func(ctx: borrow<proc-context>, amt: decimal) -> result<burn, error>;",
+  "export transfer: func(ctx: borrow<proc-context>, dst: string, amt: decimal) -> result<transfer, error>;",
+  "export balance: func(ctx: borrow<view-context>, acc: string) -> option<decimal>;",
+  "export balances: func(ctx: borrow<view-context>) -> list<balance>;",
+  "export total-supply: func(ctx: borrow<view-context>) -> decimal;",
+  "export attach: func(ctx: borrow<proc-context>, vout: u64, amt: decimal) -> result<transfer, error>;",
+  "export detach: func(ctx: borrow<proc-context>) -> result<transfer, error>;",
+] as const;
+
+export const wit = parseWit(nativeTokenRaw);
+
+test("e2e kontor wallet client", async () => {
+  const account = mnemonicToAccount(process.env.TEST_MNEMONIC!);
+
+  const kontorPublicClient = createKontorPublicClient({
+    transport: http("https://signet-staging.kontor.network:35000/api"),
+    account,
+  });
+
+  const kontorWalletClient = createKontorWalletClient({
+    account,
+    // TODO: transport is not used for local account.
+    transport: custom({
+      request: async (_args: any) => null,
+    }),
+  });
+
+  const res = await kontorPublicClient.procContract({
+    wit: wit,
+    // TODO: add optional account override
+
+    functionName: "mint", // functin name is only valid if it's got a proc-context
+    contractAddress: "token_0_0",
+    args: [[7n, 18]],
+    satsPerVByte: 1,
+    utxos: [
+      "57f1f46857ab12e20f32ecaac780b4096b0951458e15ab08e2ce0992f0521323:0",
+    ],
+    gas: 10n,
+  });
+
+  // @ts-ignore
+  const commit_: Transaction = await kontorWalletClient.signCommit({
+    account: account,
+    chain: signet,
+    psbt: res.result.commit_psbt_hex,
+  });
+
+  const reveal: Transaction = await kontorWalletClient.signReveal({
+    account: account,
+    chain: signet,
+    psbt: res.result.reveal_psbt_hex,
+    parcipantScripts: res.result.per_participant,
+  });
+
+  const revealExtracted = reveal.extract();
+
+  const op = await kontorPublicClient.inspect({
+    hex: hex.encode(revealExtracted),
+  });
+
+  console.log(JSON.stringify(op.result[0]!.op));
+  //
+});

package/src/sdk/types/account.ts

@@ -0,0 +1,41 @@
+import type { Prettify } from "../../wit/type-utils.js";
+import type { Account, JsonRpcAccount } from "../accounts/types.js";
+import type { Address, XOnlyPubKey } from "../types/misc.js";
+import type { IsUndefined, MaybeRequired } from "./utils.js";
+
+type AddressAndXOnly = [Address, XOnlyPubKey];
+
+export type ParseAccount<
+  accountOrAddress extends Account | AddressAndXOnly | null | undefined =
+    | Account
+    | AddressAndXOnly
+    | null
+    | undefined,
+> = accountOrAddress extends AddressAndXOnly
+  ? Prettify<JsonRpcAccount<accountOrAddress[0], accountOrAddress[1]>>
+  : accountOrAddress;
+
+export type { HDKey } from "@scure/bip32";
+
+export type GetAccountParameter<
+  account extends Account | undefined = Account | undefined,
+  accountOverride extends Account | [Address, XOnlyPubKey] | undefined =
+    | Account
+    | [Address, XOnlyPubKey],
+  required extends boolean = true,
+  nullish extends boolean = false,
+> = MaybeRequired<
+  {
+    account?:
+      | accountOverride
+      | Account
+      | [Address, XOnlyPubKey]
+      | (nullish extends true ? null : never)
+      | undefined;
+  },
+  IsUndefined<account> extends true
+    ? required extends true
+      ? true
+      : false
+    : false
+>;