@kontor/kontor-sdk 1.0.0-alpha.0

package/src/wit/utils.ts

@@ -0,0 +1,297 @@
+import type { Error_ } from "./error.js";
+import type {
+  WitStateMutability,
+  Wit,
+  MBits,
+  WitInt,
+  WitList,
+  WitType,
+  TypedDataParameter,
+  TypedData,
+  WitParameterKind,
+  WitParameter,
+  WitTuple,
+  TypedDataType,
+  WitOption,
+  WitResult,
+} from "./wit.js";
+import type { ResolvedRegister } from "./register.js";
+import type { Merge, Pretty } from "./type-utils.js";
+
+export type IsWit<wit> = wit extends Wit ? true : false;
+
+export type ExtractWitFunctions<
+  wit extends Wit,
+  witFuncContext extends WitStateMutability = WitStateMutability,
+> = Extract<wit[number], { type: "function"; context: witFuncContext }>;
+
+export type ExtractWitFunctionNames<
+  wit extends Wit,
+  witFuncContext extends WitStateMutability = WitStateMutability,
+> = ExtractWitFunctions<wit, witFuncContext>["name"];
+
+export type ExtractWitFunction<
+  wit extends Wit,
+  functionName extends ExtractWitFunctionNames<wit>,
+  witFuncContext extends WitStateMutability = WitStateMutability,
+> = Extract<ExtractWitFunctions<wit, witFuncContext>, { name: functionName }>;
+
+type NoBits = "";
+type GreaterThan48Bits = Exclude<MBits, 8 | 16 | 32 | NoBits>;
+type LessThanOrEqualTo48Bits = Exclude<MBits, GreaterThan48Bits | NoBits>;
+
+// TODO: move these somewhere sane
+export type Option<T> = { kind: "none" } | { kind: "some"; value: T };
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+export type WitTypeToPrimitiveType<witType extends WitType> =
+  // TODO: audit above
+  // > = witType extends SolidityBytes
+  //   ? // If PrimitiveTypeLookup is missing key values from WirType,
+  //     // there will be an error on this property access
+  //     PrimitiveTypeLookup[witType][witParameterKind]
+  PrimitiveTypeLookup[witType];
+
+interface PrimitiveTypeLookup
+  extends WitIntMap,
+    WitListMap,
+    WitOptionMap,
+    WitResultMap {
+  bool: boolean;
+  address: string;
+  // TODO: rename to record
+  string: string;
+  tuple: Record<string, unknown>;
+  error: unknown;
+  integer: ResolvedRegister["bigIntType"];
+  decimal: ResolvedRegister["decimalType"];
+  unit: void;
+  "contract-address": ResolvedRegister["contractAddress"];
+}
+
+type WitIntMap = {
+  [_ in WitInt]: _ extends `${
+    | "u"
+    | "s"}${infer bits extends keyof BitsTypeLookup}`
+    ? BitsTypeLookup[bits]
+    : never;
+};
+
+type WitListMap = { [_ in WitList]: readonly unknown[] };
+
+type WitOptionMap = { [_ in WitOption]: Option<unknown> };
+
+// TODO: change string to error type
+type WitResultMap = { [_ in WitResult]: Result<unknown, string> };
+
+type BitsTypeLookup = {
+  [key in MBits]: ResolvedRegister[key extends LessThanOrEqualTo48Bits
+    ? "intType"
+    : "bigIntType"];
+};
+
+// TODO: add record / option
+type WitBasicType = Exclude<
+  WitType,
+  WitTuple | WitList | WitResult | WitOption
+>;
+
+export type WitParametersToPrimitiveTypes<
+  witParameters extends readonly WitParameter[],
+  witParameterKind extends WitParameterKind = WitParameterKind,
+> = Pretty<{
+  // TODO: Convert to labeled tuple so parameter names show up in autocomplete
+  // e.g. [foo: string, bar: string]
+  // https://github.com/microsoft/TypeScript/issues/44939
+  [key in keyof witParameters]: WitParameterToPrimitiveType<
+    witParameters[key],
+    witParameterKind
+  >;
+}>;
+
+export type WitParameterToPrimitiveType<
+  witParameter extends WitParameter | { name: string; type: unknown },
+  witParameterKind extends WitParameterKind = WitParameterKind,
+> =
+  // 1. Basic type (non-tuple, non-list) – uses PrimitiveTypeLookup (ints, bool, string, option<string>, result<u64,error>, etc.)
+  witParameter["type"] extends WitBasicType
+    ? WitTypeToPrimitiveType<witParameter["type"]>
+    : // 2. Explicit tuple with components
+      witParameter extends {
+          type: WitTuple;
+          components: infer components extends readonly WitParameter[];
+        }
+      ? WitComponentsToPrimitiveType<components, witParameterKind>
+      : // 3. list<...>
+        MaybeExtractListParameterType<
+            witParameter["type"]
+          > extends infer head extends string
+        ? WitListToPrimitiveType<witParameter, witParameterKind, head>
+        : // 4. option<...>
+          MaybeExtractOptionParameterType<
+              witParameter["type"]
+            > extends infer inner extends string
+          ? WitOptionToPrimitiveType<witParameter, witParameterKind, inner>
+          : // 5. result<Ok, Err>
+            MaybeExtractResultParameterType<witParameter["type"]> extends [
+                infer ok extends string,
+                infer _err extends string,
+              ]
+            ? WitResultToPrimitiveType<witParameter, witParameterKind, ok>
+            : // 6. Fallback / error
+              ResolvedRegister["strictWitType"] extends true
+              ? Error_<`Unknown type '${witParameter["type"] & string}'.`>
+              : witParameter extends { components: Error_<string> }
+                ? witParameter["components"]
+                : unknown;
+
+type MaybeExtractListParameterType<T> = T extends `list<${infer Inner}>`
+  ? Inner
+  : undefined;
+
+type MaybeExtractOptionParameterType<T> = T extends `option<${infer Inner}>`
+  ? Inner
+  : undefined;
+
+type MaybeExtractResultParameterType<T> =
+  T extends `result<${infer Ok}, ${infer Err}>` ? [Ok, Err] : undefined;
+
+type WitListToPrimitiveType<
+  witParameter extends WitParameter | { name: string; type: unknown },
+  witParameterKind extends WitParameterKind,
+  head extends string,
+> = readonly WitParameterToPrimitiveType<
+  Merge<witParameter, { type: head }>,
+  witParameterKind
+>[];
+
+type WitOptionToPrimitiveType<
+  witParameter extends WitParameter | { name: string; type: unknown },
+  witParameterKind extends WitParameterKind,
+  inner extends string,
+> = Option<
+  WitParameterToPrimitiveType<
+    Merge<witParameter, { type: inner }>,
+    witParameterKind
+  >
+>;
+
+type WitResultToPrimitiveType<
+  witParameter extends WitParameter | { name: string; type: unknown },
+  witParameterKind extends WitParameterKind,
+  ok extends string,
+  // TODO: error always treated as a string for now
+  // err extends string,
+> = Result<
+  WitParameterToPrimitiveType<
+    Merge<witParameter, { type: ok }>,
+    witParameterKind
+  >,
+  string
+>;
+type WitComponentsToPrimitiveType<
+  components extends readonly WitParameter[],
+  witParameterKind extends WitParameterKind,
+> = components extends readonly []
+  ? []
+  : // Compare the original set of names to a "validated"
+    // set where each name is coerced to a string and undefined|"" are excluded
+    components[number]["name"] extends Exclude<
+        components[number]["name"] & string,
+        undefined | ""
+      >
+    ? // If all the original names are present, all tuple parameters are named so return as object
+      {
+        [component in components[number] as component["name"] & {}]: WitParameterToPrimitiveType<
+          component,
+          witParameterKind
+        >;
+      }
+    : // Otherwise, has unnamed tuple parameters so return as array
+      {
+        [key in keyof components]: WitParameterToPrimitiveType<
+          components[key],
+          witParameterKind
+        >;
+      };
+
+export type TypedDataToPrimitiveTypes<
+  typedData extends TypedData,
+  witParameterKind extends WitParameterKind = WitParameterKind,
+  keyReferences extends { [_: string]: unknown } | unknown = unknown,
+> = {
+  [key in keyof typedData]: {
+    // Map over typed data values and turn into key-value pairs
+    [key2 in typedData[key][number] as key2["name"]]: key2["type"] extends key // 1. Eliminate self-referencing structs
+      ? Error_<`Cannot convert self-referencing struct '${key2["type"]}' to primitive type.`>
+      : key2["type"] extends keyof typedData // 2. Check if type is struct
+        ? key2["type"] extends keyof keyReferences
+          ? Error_<`Circular reference detected. '${key2["type"]}' is a circular reference.`>
+          : TypedDataToPrimitiveTypes<
+              Exclude<typedData, key>,
+              witParameterKind,
+              keyReferences & { [_ in key2["type"] | key]: true }
+            >[key2["type"]]
+        : // 3. Check if type is array of structs
+          key2["type"] extends `${infer type extends keyof typedData &
+              string}[${infer tail}]`
+          ? WitParameterToPrimitiveType<
+              {
+                name: key2["name"];
+                type: `tuple[${tail}]`;
+                components: _TypedDataParametersToWitParameters<
+                  typedData[type],
+                  typedData,
+                  keyReferences & { [_ in type | key]: true }
+                >;
+              },
+              witParameterKind
+            >
+          : key2["type"] extends TypedDataType // 4. Known type to convert
+            ? WitParameterToPrimitiveType<key2, witParameterKind>
+            : Error_<`Cannot convert unknown type '${key2["type"]}' to primitive type.`>;
+  };
+  // Ensure the result is "Prettied"
+} & unknown;
+
+type _TypedDataParametersToWitParameters<
+  typedDataParameters extends readonly TypedDataParameter[],
+  typedData extends TypedData,
+  keyReferences extends { [_: string]: unknown } | unknown = unknown,
+> = {
+  [key in keyof typedDataParameters]: typedDataParameters[key] extends infer typedDataParameter extends
+    {
+      name: string;
+      type: unknown;
+    }
+    ? // 1. Check if type is record
+      typedDataParameter["type"] extends keyof typedData & string
+      ? {
+          name: typedDataParameter["name"];
+          type: "tuple";
+          components: typedDataParameter["type"] extends keyof keyReferences
+            ? Error_<`Circular reference detected. '${typedDataParameter["type"]}' is a circular reference.`>
+            : _TypedDataParametersToWitParameters<
+                typedData[typedDataParameter["type"]],
+                typedData,
+                keyReferences & { [_ in typedDataParameter["type"]]: true }
+              >;
+        }
+      : // 2. Check if type is array of structs
+        typedDataParameter["type"] extends `${infer type extends
+            keyof typedData & string}[${infer tail}]`
+        ? {
+            name: typedDataParameter["name"];
+            type: `tuple[${tail}]`;
+            components: type extends keyof keyReferences
+              ? Error_<`Circular reference detected. '${typedDataParameter["type"]}' is a circular reference.`>
+              : _TypedDataParametersToWitParameters<
+                  typedData[type],
+                  typedData,
+                  keyReferences & { [_ in type]: true }
+                >;
+          }
+        : // 3. Type is already ABI parameter
+          typedDataParameter
+    : never;
+};

package/src/wit/version.ts

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

package/src/wit/wit-parser/core/errors/signature.ts

@@ -0,0 +1,39 @@
+import { BaseError } from "../../../error.js";
+import type { WitItemType } from "../../../wit.js";
+
+export class InvalidSignatureError extends BaseError {
+  override name = "InvalidSignatureError";
+
+  constructor({
+    signature,
+    type,
+  }: {
+    signature: string;
+    type: WitItemType | "record";
+  }) {
+    super(`Invalid ${type} signature.`, {
+      details: signature,
+    });
+  }
+}
+
+export class UnknownSignatureError extends BaseError {
+  override name = "UnknownSignatureError";
+
+  constructor({ signature }: { signature: string }) {
+    super("Unknown signature.", {
+      details: signature,
+    });
+  }
+}
+
+export class InvalidRecordSignatureError extends BaseError {
+  override name = "InvalidStructSignatureError";
+
+  constructor({ signature }: { signature: string }) {
+    super("Invalid record signature.", {
+      details: signature,
+      metaMessages: ["No properties exist."],
+    });
+  }
+}

package/src/wit/wit-parser/core/errors/splitParameters.ts

@@ -0,0 +1,16 @@
+import { BaseError } from "../../../error.js";
+
+export class InvalidGenericDepthError extends BaseError {
+  override name = "InvalidGenericDepthError";
+
+  constructor({ current, depth }: { current: string; depth: number }) {
+    super("Unbalanced angle brackets.", {
+      metaMessages: [
+        `"${current.trim()}" has too many ${
+          depth > 0 ? "opening" : "closing"
+        } brackets.`,
+      ],
+      details: `Depth "${depth}"`,
+    });
+  }
+}

package/src/wit/wit-parser/core/errors/wit-parameter.ts

@@ -0,0 +1,21 @@
+import { BaseError } from "../../../error.js";
+
+export class InvalidWitParameterError extends BaseError {
+  override name = "InvalidWitParameterError";
+
+  constructor({ param }: { param: string | object }) {
+    super("Failed to parse Wit parameter.", {
+      details: `parseWitParameter(${JSON.stringify(param, null, 2)})`,
+    });
+  }
+}
+export class WitProtectedKeywordError extends BaseError {
+  override name = "WitProtectedKeywordError";
+
+  constructor({ param, name }: { param: string; name: string }) {
+    super("Invalid Wit parameter.", {
+      details: param,
+      metaMessages: [`"${name}" is a protected Wit keyword`],
+    });
+  }
+}

package/src/wit/wit-parser/core/records.test.ts

@@ -0,0 +1,59 @@
+import { expect, test } from "vitest";
+import { parseRecords } from "./records.js";
+
+test("parse records", () => {
+  expect(
+    parseRecords([
+      "record contract-address {  name: string, height: s64, tx-index: s64 }",
+      "record token-pair {  a: contract-address, b: contract-address }",
+    ]),
+  ).toEqual({
+    "contract-address": [
+      { name: "name", type: "string" },
+      { name: "height", type: "s64" },
+      { name: "tx-index", type: "s64" },
+    ],
+    "token-pair": [
+      {
+        type: "tuple",
+        name: "a",
+        components: [
+          { name: "name", type: "string" },
+          { name: "height", type: "s64" },
+          { name: "tx-index", type: "s64" },
+        ],
+      },
+      {
+        type: "tuple",
+        name: "b",
+        components: [
+          { name: "name", type: "string" },
+          { name: "height", type: "s64" },
+          { name: "tx-index", type: "s64" },
+        ],
+      },
+    ],
+  });
+});
+
+test("generic", () => {
+  expect(parseRecords(["record generic {  values: list<string> }"])).toEqual({
+    generic: [{ name: "values", type: "list<string>" }],
+  });
+});
+
+test("generic", () => {
+  expect(
+    parseRecords([
+      "record contract-address {  name: string, height: s64, tx-index: s64 }",
+      "record generic {  values: list<contract-address> }",
+    ]),
+  ).toEqual({
+    "contract-address": [
+      { type: "string", name: "name" },
+      { type: "s64", name: "height" },
+      { type: "s64", name: "tx-index" },
+    ],
+    generic: [{ name: "values", type: "list<contract-address>" }],
+  });
+});

package/src/wit/wit-parser/core/records.ts

@@ -0,0 +1,101 @@
+import type { WitParameter } from "../../wit.js";
+import { execTyped, isGenericRegex } from "../../regex.js";
+import {
+  InvalidRecordSignatureError,
+  InvalidSignatureError,
+} from "./errors/signature.js";
+import { execRecordSignature, isRecordSignature } from "./signatures.js";
+import type { RecordLookup } from "./types/records.js";
+import { parseWitParameter } from "./utils.js";
+
+export function parseRecords(signatures: readonly string[]) {
+  const shallowRecords: RecordLookup = {};
+  const signaturesLength = signatures.length;
+
+  for (let i = 0; i < signaturesLength; i++) {
+    const signature = signatures[i]!;
+    if (!isRecordSignature(signature)) continue;
+
+    const match = execRecordSignature(signature);
+    if (!match) throw new InvalidSignatureError({ signature, type: "record" });
+
+    const properties = match.properties.split(",");
+
+    const components: WitParameter[] = [];
+
+    const propertiesLength = properties.length;
+    for (let k = 0; k < propertiesLength; k++) {
+      const property = properties[k]!;
+      const trimmed = property.trim();
+      if (!trimmed) continue;
+      const witParameter = parseWitParameter(trimmed, {
+        type: "record",
+      });
+      components.push(witParameter);
+    }
+
+    if (!components.length)
+      throw new InvalidRecordSignatureError({ signature });
+    shallowRecords[match.name] = components;
+  }
+
+  const resolvedRecords: RecordLookup = {};
+  const entries = Object.entries(shallowRecords);
+  const entriesLength = entries.length;
+  for (let i = 0; i < entriesLength; i++) {
+    const [name, parameters] = entries[i]!;
+    resolvedRecords[name] = resolveRecords(parameters, shallowRecords);
+  }
+
+  return resolvedRecords;
+}
+
+// TODO: move?
+// e.g. "list<u8>", "option<signer>", "result<integer, error>", "borrow<proc-context>"
+
+export function isGeneric(type: string): boolean {
+  return isGenericRegex.test(type.trim());
+}
+
+// e.g. "string", "list<u8>", "option<signer>", "result<integer, error>", "borrow<proc-context>"
+const witTypeRegex =
+  /^(?:(?<wrapper>borrow|own)\s*<\s*)?(?<base>[a-zA-Z$_][a-zA-Z0-9$_-]*)(?:\s*<(?<inner>[\s\S]+)>)?\s*(?:>)?$/;
+
+function resolveRecords(
+  witParameters: readonly (WitParameter & { indexed?: true })[],
+  records: RecordLookup,
+  ancestors = new Set<string>(),
+) {
+  const components: WitParameter[] = [];
+  for (const witParameter of witParameters) {
+    const m = execTyped<{
+      wrapper?: string;
+      base?: string;
+      inner?: string;
+    }>(witTypeRegex, witParameter.type);
+
+    // TODO: add custom error
+    if (!m?.base) throw new Error(`Invalid WIT type: ${witParameter.type}`);
+
+    const base = m.base;
+    // If it's a named record, expand it into a tuple of its fields.
+    if (base in records) {
+      // TODO: add custom error
+      if (ancestors.has(base)) throw new Error("Circular reference detected.");
+      components.push({
+        ...witParameter,
+        type: "tuple", // normalize records -> tuple
+        components: resolveRecords(
+          records[base] ?? [],
+          records,
+          new Set([...ancestors, base]),
+        ),
+      });
+      continue;
+    }
+
+    // Otherwise, just pass it through (builtins, generics, etc.)
+    components.push(witParameter);
+  }
+  return components;
+}

package/src/wit/wit-parser/core/signatures.test.ts

@@ -0,0 +1,64 @@
+import { expect, test, describe } from "vitest";
+
+import { execFunctionSignature, isFunctionSignature } from "./signatures.js";
+
+describe("isFunctionSignature", () => {
+  test.each([
+    "export fib: func(ctx: borrow<proc-context>, arith-address: contract-address, n: u64) -> u64;",
+
+    "export fib-of-sub: func(ctx: borrow<proc-context>, arith-address: contract-address, x: string, y: string) -> result<u64, error>;",
+
+    "export cached-values: func(ctx: borrow<view-context>) -> list<u64>;",
+  ])("%s -> %s", (input) => {
+    expect(isFunctionSignature(input)).toBe(true);
+  });
+});
+
+describe("execFunctionSignature", () => {
+  test.each([
+    {
+      input:
+        "export fib: func(ctx: borrow<proc-context>, arith-address: contract-address, n: u64) -> u64;",
+      expected: {
+        name: "fib",
+        type: "proc",
+        parameters:
+          "ctx: borrow<proc-context>, arith-address: contract-address, n: u64",
+        returns: "u64",
+      },
+    },
+    {
+      input:
+        "export fib-of-sub: func(ctx: borrow<proc-context>, arith-address: contract-address, x: string, y: string) -> result<u64, error>;",
+      expected: {
+        name: "fib-of-sub",
+        type: "proc",
+        parameters:
+          "ctx: borrow<proc-context>, arith-address: contract-address, x: string, y: string",
+        returns: "result<u64, error>",
+      },
+    },
+    {
+      input:
+        "export cached-values: func(ctx: borrow<view-context>) -> list<u64>;",
+      expected: {
+        name: "cached-values",
+        type: "view",
+        parameters: "ctx: borrow<view-context>",
+        returns: "list<u64>",
+      },
+    },
+    {
+      input:
+        "export cached-values: func(ctx: borrow<core-context>) -> list<u64>;",
+      expected: {
+        name: "cached-values",
+        type: "core",
+        parameters: "ctx: borrow<core-context>",
+        returns: "list<u64>",
+      },
+    },
+  ])("%s", ({ input, expected }) => {
+    expect(execFunctionSignature(input)).toStrictEqual(expected);
+  });
+});

package/src/wit/wit-parser/core/signatures.ts

@@ -0,0 +1,52 @@
+import { execTyped } from "../../regex.js";
+
+const errorSignatureRegex =
+  /^error (?<name>[a-zA-Z$_][a-zA-Z0-9$_]*)\((?<parameters>.*?)\)$/;
+export function isErrorSignature(signature: string) {
+  return errorSignatureRegex.test(signature);
+}
+export function execErrorSignature(signature: string) {
+  return execTyped<{ name: string; parameters: string }>(
+    errorSignatureRegex,
+    signature,
+  );
+}
+
+const witFnSignatureRegex =
+  /^export\s+(?<name>[a-z][a-z0-9-]*)\s*:\s*func\s*\(\s*ctx\s*:\s*borrow<(?<ctx>proc-context|view-context|core-context)>\s*(?:,\s*(?<rest>.*?))?\)\s*(?:->\s*(?<returns>[^;]+))?;\s*$/;
+
+export function isFunctionSignature(signature: string) {
+  return witFnSignatureRegex.test(signature);
+}
+
+export function execFunctionSignature(signature: string) {
+  const m = witFnSignatureRegex.exec(signature);
+  if (!m || !m.groups) return null;
+
+  const name = m.groups.name!;
+  const ctx = m.groups.ctx as "proc-context" | "view-context" | "core-context";
+  const type =
+    ctx === "proc-context" ? "proc" : ctx == "view-context" ? "view" : "core";
+
+  const rest = (m.groups.rest ?? "").trim();
+  const parameters =
+    rest.length > 0 ? `ctx: borrow<${ctx}>, ${rest}` : `ctx: borrow<${ctx}>`;
+
+  const returns = (m.groups.returns ?? "").trim() || undefined;
+
+  return { name, type, parameters, returns };
+}
+
+const witRecordSignatureRegex =
+  /^record\s+(?<name>[a-zA-Z$_][a-zA-Z0-9$_-]*)\s*\{(?<properties>[\s\S]*?)\}$/;
+
+export function isRecordSignature(signature: string) {
+  return witRecordSignatureRegex.test(signature);
+}
+
+export function execRecordSignature(signature: string) {
+  return execTyped<{
+    name: string;
+    properties: string;
+  }>(witRecordSignatureRegex, signature);
+}