@kontor/kontor-sdk 1.0.0-alpha.0

package/src/sdk/types/kontor.ts

@@ -0,0 +1,76 @@
+import type {
+  ResultResponse as ResultResponse_,
+  ViewExpr as ViewExpr_,
+  ComposeQuery as ComposeQuery_,
+  ComposeOutputs as ComposeOutputs_,
+  TransactionHex as TransactionHex_,
+  OpWithResult as OpWithResult_,
+  ViewResult as ViewResult_,
+  InstructionQuery as InstructionQuery_,
+  ParticipantScripts as ParticipantScripts_,
+} from "@kontor/kontor-ts";
+import type { ResolvedRegister } from "../../wit/register.js";
+
+import type { HttpSchemaEntry, HttpParameters } from "./http-schema.js";
+
+export type ResultResponse<T> = ResultResponse_<T>;
+
+export type ViewExpr = ViewExpr_;
+
+export type ViewResult = ViewResult_;
+
+export type ComposeQuery = ComposeQuery_;
+
+export type ComposeOutputs = ComposeOutputs_;
+
+export type TransactionHex = TransactionHex_;
+
+export type OpWithResult = OpWithResult_;
+
+export type InstructionQuery = InstructionQuery_;
+
+export type ParticipantScripts = ParticipantScripts_;
+
+export type KontorSchemaPublic = readonly [
+  HttpSchemaEntry<
+    "/contracts/:contractAddress",
+    "POST", // or "POST" - specify the HTTP method
+    HttpParameters<
+      // Path params with explicit order
+      readonly [
+        readonly ["contractAddress", ResolvedRegister["contractAddress"]],
+      ],
+      // Query params
+      never,
+      // body params
+      ViewExpr
+    >,
+    ResultResponse<ViewResult>
+  >,
+  HttpSchemaEntry<
+    "/transactions/compose",
+    "POST", // or "POST" - specify the HTTP method
+    HttpParameters<
+      // Path params with explicit order
+      never,
+      // Query params
+      never,
+      // body params
+      ComposeQuery
+    >,
+    ResultResponse<ComposeOutputs>
+  >,
+  HttpSchemaEntry<
+    "/transactions/inspect",
+    "POST", // or "POST" - specify the HTTP method
+    HttpParameters<
+      // Path params with explicit order
+      never,
+      // Query params
+      never,
+      // body params
+      TransactionHex
+    >,
+    ResultResponse<OpWithResult[]>
+  >,
+];

package/src/sdk/types/misc.ts

@@ -0,0 +1,60 @@
+export type ByteArray = Uint8Array;
+
+export type Address = string;
+
+// TODO: type helper to verify 32 bytes
+export type XOnlyPubKey = string;
+
+export type Hash = string;
+export type Hex = string;
+export type LogTopic = Hex | Hex[] | null;
+export type SignableMessage =
+  | string
+  | {
+      /** Raw data representation of the message. */
+      raw: Hex | ByteArray;
+    };
+
+export type UtxoId = string | { txid: string; vout: number };
+
+export namespace TransactionInput {
+  export type T = {
+    previous_output: string;
+    script_sig: string;
+    sequence: number;
+    witness: string[];
+    input: TransactionInput.T[];
+    output: TransactionOutput.T[];
+  };
+}
+
+export namespace TransactionOutput {
+  export type T = {
+    script_pubkey: string;
+    value: number;
+  };
+}
+
+export namespace Transaction {
+  export type T = {
+    version: number;
+    lock_time: number;
+    input: TransactionInput.T[];
+    output: TransactionOutput.T[];
+  };
+}
+
+export namespace TapLeafScript {
+  export type T = {
+    leafVersion: number;
+    script: string;
+    controlBlock: string;
+  };
+}
+
+export type BtcNetwork = {
+  bech32: string;
+  pubKeyHash: number;
+  scriptHash: number;
+  wif: number;
+};

package/src/sdk/types/rpc-schema.ts

@@ -0,0 +1,61 @@
+import type { OneOf } from "../../wit/type-utils.js";
+
+/**
+ * Generic JSON-RPC schema entry.
+ */
+export type RpcSchemaEntry<
+  M extends string = string,
+  P = unknown,
+  R = unknown,
+> = {
+  readonly Method: M;
+  readonly Parameters?: P | undefined;
+  readonly ReturnType: R;
+};
+
+export type RpcSchema = readonly RpcSchemaEntry[];
+
+export type ExtractMethodEntry<
+  S extends RpcSchema,
+  M extends S[number]["Method"],
+> = Extract<S[number], { Method: M }>;
+
+export type RpcRequestFn<Schema extends RpcSchema | undefined> = <
+  S extends RpcSchema = Schema extends RpcSchema ? Schema : RpcSchema,
+  M extends S[number]["Method"] = S[number]["Method"],
+>(
+  args: Schema extends RpcSchema
+    ? {
+        method: M;
+        params: ExtractMethodEntry<S, M>["Parameters"];
+      }
+    : {
+        method: string;
+        params?: unknown;
+      },
+  options?: RpcRequestOptions | undefined,
+) => Promise<
+  Schema extends RpcSchema ? ExtractMethodEntry<S, M>["ReturnType"] : unknown
+>;
+
+export type RpcRequestOptions = {
+  /** Deduplicate in-flight requests. */
+  dedupe?: boolean | undefined;
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?:
+    | OneOf<
+        | {
+            include?: string[] | undefined;
+          }
+        | {
+            exclude?: string[] | undefined;
+          }
+      >
+    | undefined;
+  /** The base delay (in ms) between retries. */
+  retryDelay?: number | undefined;
+  /** The max number of times to retry. */
+  retryCount?: number | undefined;
+  /** Unique identifier for the request. */
+  uid?: string | undefined;
+};

package/src/sdk/types/rpc.ts

@@ -0,0 +1,40 @@
+type SuccessResult<result> = {
+  method?: undefined;
+  result: result;
+  error?: undefined;
+};
+type ErrorResult<error> = {
+  method?: undefined;
+  result?: undefined;
+  error: error;
+};
+
+export type RpcRequest = {
+  jsonrpc?: "2.0" | undefined;
+  method: string;
+  params?: any | undefined;
+  id?: number | null | undefined;
+};
+
+export type RpcResponse<result = any, error = any> = {
+  jsonrpc: `${number}`;
+  id: number;
+} & (SuccessResult<result> | ErrorResult<error>);
+// Subscription<result, error>);
+
+// type Subscription<result, error> = {
+//   method: "eth_subscription";
+//   error?: undefined;
+//   result?: undefined;
+//   params:
+//     | {
+//         subscription: string;
+//         result: result;
+//         error?: undefined;
+//       }
+//     | {
+//         subscription: string;
+//         result?: undefined;
+//         error: error;
+//       };
+// };

package/src/sdk/types/utils.ts

@@ -0,0 +1,11 @@
+export type MaybePromise<T> = T | Promise<T>;
+
+export type MaybeRequired<T, required extends boolean> = required extends true
+  ? ExactRequired<T>
+  : T;
+
+export type IsUndefined<T> = [undefined] extends [T] ? true : false;
+
+export type ExactRequired<type> = {
+  [P in keyof type]-?: Exclude<type[P], undefined>;
+};

package/src/sdk/types/wbip001.ts

@@ -0,0 +1,108 @@
+// bip.ts (or wbip.ts)
+
+import type { SigHash } from "@scure/btc-signer";
+import type { Prettify } from "../../wit/type-utils.js";
+import type { RpcSchema, RpcSchemaEntry, RpcRequestFn } from "./rpc-schema.js";
+
+type RpcResult<T> = { result: T };
+
+/* -------------------------------------------------------------------------- */
+/*                               BTC data types                               */
+/* -------------------------------------------------------------------------- */
+
+export type BtcAddressType =
+  | "p2pkh"
+  | "p2sh"
+  | "p2wpkh-p2sh"
+  | "p2wpkh"
+  | "p2tr";
+
+export type BtcAddressPurpose = "change" | "ordinals" | string;
+
+export interface GetAddressesParams {
+  count: number;
+  types: string[];
+  purposes: string[];
+}
+
+export type GetAddressesReturnType = RpcResult<{
+  addresses: {
+    address: string;
+    type?: BtcAddressType | string;
+    purpose?: BtcAddressPurpose;
+    publicKey?: string;
+  }[];
+}>;
+
+export interface SignMessageParams {
+  message: string;
+  // Spec leaves this a bit loose (`address?: {}`); we tighten to string | unknown for now.
+  address?: string | Record<string, unknown>;
+}
+
+export type SignMessageReturnType = RpcResult<{
+  signature: string;
+  messageHash?: string;
+  address?: string;
+}>;
+
+/* -------------------------------------------------------------------------- */
+/*                                WBIP005 schema                              */
+/* -------------------------------------------------------------------------- */
+
+// WBIP005 — Default Bitcoin Methods
+// https://…/wbips/WBIP005.md (from the repo bundle)
+export type WBIP005 = readonly [
+  // getAddresses
+  RpcSchemaEntry<"getAddresses", GetAddressesParams, GetAddressesReturnType>,
+  // signMessage
+  RpcSchemaEntry<"signMessage", SignMessageParams, SignMessageReturnType>,
+];
+
+/* -------------------------------------------------------------------------- */
+/*                                WBIP006 schema                              */
+/* -------------------------------------------------------------------------- */
+
+export type SignPsbtParams = {
+  psbt: string;
+  signInputs: // this is technically optional but required here for simplicity
+  | number[]
+    | {
+        index: number;
+        address?: string;
+        publicKey?: string;
+        allowedSighash?: SigHash[];
+      }[];
+
+  broadcast: boolean; // in the spec this param is `finalize` but people seem to use broadcast
+};
+
+export type SignPsbtReturnType = RpcResult<{
+  psbt: string; // TODO: This isn't technically part of the spec
+  txid: string;
+}>;
+
+// WBIP006 — PSBT
+export type WBIP006 = readonly [
+  RpcSchemaEntry<"signPsbt", SignPsbtParams, SignPsbtReturnType>,
+];
+
+/* -------------------------------------------------------------------------- */
+/*                         Aggregated WBIP001 “surface”                        */
+/* -------------------------------------------------------------------------- */
+
+export type WBIP001Schema = [...WBIP005, ...WBIP006];
+
+/* -------------------------------------------------------------------------- */
+/*                             Typed request function                          */
+/* -------------------------------------------------------------------------- */
+export type WBIP001RequestFn<
+  Schema extends RpcSchema | undefined = WBIP001Schema,
+> = RpcRequestFn<Schema>;
+/* -------------------------------------------------------------------------- */
+/*                               Provider shape                                */
+/* -------------------------------------------------------------------------- */
+
+export type WBIP001Provider = Prettify<{
+  request: WBIP001RequestFn<WBIP001Schema>;
+}>;

package/src/sdk/utils/build-http-request.ts

@@ -0,0 +1,67 @@
+// sdk/utils/build-http-request.ts
+import { buildRequest, type BaseRequestOptions } from "./build-request.js";
+import type {
+  HttpRequestFn,
+  HttpSchema,
+  HttpRequestOptions,
+} from "../types/http-schema.js";
+import {
+  HttpRequestError,
+  type HttpRequestErrorType,
+} from "../errors/request.js";
+import type { WithRetryErrorType } from "./promise/with-retry.js";
+
+export type HttpRequestErrorUnion = WithRetryErrorType | HttpRequestErrorType;
+
+export function buildHttpRequest<
+  Request extends (args: any) => Promise<any>,
+  Schema extends HttpSchema | undefined = undefined,
+>(request: Request, options: HttpRequestOptions = {}): HttpRequestFn<Schema> {
+  const { routes, ...baseOptions } = options;
+
+  const genericRequest = buildRequest<any, any, Request>(request, {
+    dedupe: baseOptions.dedupe,
+    retryDelay: baseOptions.retryDelay,
+    retryCount: baseOptions.retryCount,
+    uid: baseOptions.uid,
+    shouldRetry: ({ error }) => (error ? shouldRetryHttp(error) : false),
+  });
+
+  return async (args: any, overrideOptions: HttpRequestOptions = {}) => {
+    const { routes: overrideRoutes, ...overrideBase } = overrideOptions;
+    const effectiveRoutes = overrideRoutes ?? routes;
+
+    if (effectiveRoutes) {
+      const { route } = args;
+      if (effectiveRoutes.exclude?.includes(route))
+        throw new Error("route not supported");
+      if (effectiveRoutes.include && !effectiveRoutes.include.includes(route))
+        throw new Error("route not supported");
+    }
+
+    const baseOverrideOptions: BaseRequestOptions = {
+      dedupe: overrideBase.dedupe,
+      retryDelay: overrideBase.retryDelay,
+      retryCount: overrideBase.retryCount,
+      uid: overrideBase.uid,
+    };
+
+    return genericRequest(args, baseOverrideOptions);
+  };
+}
+
+/** HTTP-specific retry heuristic. */
+function shouldRetryHttp(error: Error) {
+  if (error instanceof HttpRequestError && error.status) {
+    if (error.status === 403) return true;
+    if (error.status === 408) return true;
+    if (error.status === 413) return true;
+    if (error.status === 429) return true;
+    if (error.status === 500) return true;
+    if (error.status === 502) return true;
+    if (error.status === 503) return true;
+    if (error.status === 504) return true;
+    return false;
+  }
+  return true;
+}

package/src/sdk/utils/build-request.ts

@@ -0,0 +1,75 @@
+import { HttpRequestError } from "../errors/request.js";
+import { withDedupe } from "./promise/with-dedupe.js";
+import { withRetry } from "./promise/with-retry.js";
+
+// TODO: move to helper
+export const stringify: typeof JSON.stringify = (value, replacer, space) =>
+  JSON.stringify(
+    value,
+    (key, value_) => {
+      const value = typeof value_ === "bigint" ? value_.toString() : value_;
+      return typeof replacer === "function" ? replacer(key, value) : value;
+    },
+    space,
+  );
+
+export type BaseRequestOptions = {
+  dedupe?: boolean | undefined;
+  retryDelay?: number | undefined;
+  retryCount?: number | undefined;
+  uid?: string | undefined;
+  shouldRetry?: ((args: { error: Error | undefined }) => boolean) | undefined;
+};
+
+export type GenericRequestFn<Args, Result> = (
+  args: Args,
+  overrideOptions?: BaseRequestOptions,
+) => Promise<Result>;
+
+export function buildRequest<
+  Args,
+  Result,
+  RequestFn extends (args: Args) => Promise<Result>,
+>(
+  request: RequestFn,
+  options: BaseRequestOptions = {},
+): GenericRequestFn<Args, Result> {
+  return async (args, overrideOptions = {}) => {
+    const {
+      dedupe = false,
+      retryDelay = 150,
+      retryCount = 3,
+      uid,
+      shouldRetry = () => true,
+    } = { ...options, ...overrideOptions };
+
+    const requestId = dedupe ? `${uid}.${stringify(args)}` : undefined;
+
+    return withDedupe(
+      () =>
+        withRetry(
+          async () => {
+            try {
+              return await request(args);
+            } catch (err) {
+              // Let the caller decide the error wrapper.
+              throw err;
+            }
+          },
+          {
+            delay: ({ count, error }) => {
+              if (error && error instanceof HttpRequestError) {
+                const retryAfter = error?.headers?.get("Retry-After");
+                if (retryAfter?.match(/\d/))
+                  return Number.parseInt(retryAfter, 10) * 1000;
+              }
+              return ~~(1 << count) * retryDelay;
+            },
+            retryCount,
+            shouldRetry,
+          },
+        ),
+      { enabled: dedupe, id: requestId },
+    );
+  };
+}

package/src/sdk/utils/build-rpc-request.ts

@@ -0,0 +1,94 @@
+// utils/build-rpc-request.ts
+import { BaseError } from "../errors/base.js";
+import {
+  HttpRequestError,
+  type HttpRequestErrorType,
+} from "../errors/request.js";
+import { UnknownRpcError } from "../errors/rpc.js";
+import type {
+  RpcRequestFn,
+  RpcSchema,
+  RpcRequestOptions,
+} from "../types/rpc-schema.js";
+import { buildRequest, type BaseRequestOptions } from "./build-request.js";
+import { type WithRetryErrorType } from "./promise/with-retry.js";
+
+export type RpcRequestErrorType = WithRetryErrorType | HttpRequestErrorType;
+
+export function buildRpcRequest<
+  Request extends (args: any) => Promise<any>,
+  rpcSchema extends RpcSchema | undefined = undefined,
+>(request: Request, options: RpcRequestOptions = {}): RpcRequestFn<rpcSchema> {
+  const { methods, ...baseOptions } = options;
+
+  // Build the generic retry+dedupe wrapper, but inject RPC-specific `shouldRetry`.
+  const genericRequest = buildRequest<any, any, Request>(request, {
+    dedupe: baseOptions.dedupe,
+    retryDelay: baseOptions.retryDelay,
+    retryCount: baseOptions.retryCount,
+    uid: baseOptions.uid,
+    shouldRetry: ({ error }) => (error ? shouldRetry(error) : false),
+  });
+
+  return async (args: any, overrideOptions: RpcRequestOptions = {}) => {
+    const { methods: overrideMethods, ...overrideBase } = overrideOptions;
+    const effectiveMethods = overrideMethods ?? methods;
+
+    if (effectiveMethods) {
+      const { method } = args;
+      if (effectiveMethods.exclude?.includes(method))
+        throw new Error("method not supported");
+      if (
+        effectiveMethods.include &&
+        !effectiveMethods.include.includes(method)
+      )
+        throw new Error("method not supported");
+    }
+
+    const baseOverrideOptions: BaseRequestOptions = {
+      dedupe: overrideBase.dedupe,
+      retryDelay: overrideBase.retryDelay,
+      retryCount: overrideBase.retryCount,
+      uid: overrideBase.uid,
+    };
+
+    try {
+      return await genericRequest(args, baseOverrideOptions);
+    } catch (err_) {
+      // Map non-BaseError → UnknownRpcError at the RPC layer.
+      if (err_ instanceof BaseError) throw err_;
+      throw new UnknownRpcError(err_ as Error);
+    }
+  };
+}
+
+// TODO: refine
+/** @internal */
+export function shouldRetry(error: Error) {
+  if ("code" in error && typeof (error as any).code === "number") {
+    // if ((error as any).code === -1) return true; // Unknown error
+    // if (error.code === LimitExceededRpcError.code) return true;
+    // if (error.code === InternalRpcError.code) return true;
+    return false;
+  }
+  if (error instanceof HttpRequestError && error.status) {
+    // Forbidden
+    if (error.status === 403) return true;
+    // Request Timeout
+    if (error.status === 408) return true;
+    // Request Entity Too Large
+    if (error.status === 413) return true;
+    // Too Many Requests
+    if (error.status === 429) return true;
+    // Internal Server Error
+    if (error.status === 500) return true;
+    // Bad Gateway
+    if (error.status === 502) return true;
+    // Service Unavailable
+    if (error.status === 503) return true;
+    // Gateway Timeout
+    if (error.status === 504) return true;
+    return false;
+  }
+  return true;
+}

package/src/sdk/utils/chain/defineChain.ts

@@ -0,0 +1,13 @@
+import type { Assign, Prettify } from "../../../wit/type-utils.js";
+import type { Chain } from "../../types/chain.js";
+
+export function defineChain<const chain extends Chain>(
+  chain: chain,
+): Prettify<Assign<Chain<undefined>, chain>> {
+  return {
+    formatters: undefined,
+    fees: undefined,
+    serializers: undefined,
+    ...chain,
+  } as Assign<Chain<undefined>, chain>;
+}

package/src/sdk/utils/encoding/to-hex.ts

@@ -0,0 +1,36 @@
+import type { ErrorType } from "../../errors/utils.js";
+import type { ByteArray, Hex } from "../../types/misc.js";
+
+const hexes = /*#__PURE__*/ Array.from({ length: 256 }, (_v, i) =>
+  i.toString(16).padStart(2, "0"),
+);
+export type ToHexErrorType =
+  | BytesToHexErrorType
+  | StringToHexErrorType
+  | ErrorType;
+
+export function toHex(value: string | ByteArray): Hex {
+  if (typeof value === "string") {
+    return stringToHex(value);
+  }
+  return bytesToHex(value);
+}
+export type BoolToHexErrorType = ErrorType;
+
+export type BytesToHexErrorType = ErrorType;
+export function bytesToHex(value: ByteArray): Hex {
+  let string = "";
+  for (let i = 0; i < value.length; i++) {
+    //@ts-ignore
+    string += hexes[value[i]];
+  }
+  const hex = `0x${string}` as const;
+  return hex;
+}
+export type StringToHexErrorType = BytesToHexErrorType | ErrorType;
+//
+const encoder = new TextEncoder();
+export function stringToHex(value_: string): Hex {
+  const value = encoder.encode(value_);
+  return bytesToHex(value);
+}