@kontor/kontor-sdk 1.0.0-alpha.0

package/src/wit/wit-parser/parse-wit-parameter.test.ts

@@ -0,0 +1,136 @@
+import { expectTypeOf, expect, test } from "vitest";
+
+import { parseWitParameter } from "./parse-wit-parameter.js";
+import type { ParseWitParameter } from "./parse-wit-parameter.js";
+
+test("ParseWitParameter", () => {
+  expectTypeOf<ParseWitParameter<["arith-address: contract-address"]>>()
+    .toEqualTypeOf<{
+    name: "arith-address";
+    type: "contract-address";
+  }>;
+
+  expectTypeOf<
+    ParseWitParameter<
+      [
+        "record contract-address {  name: string, height: s64, tx-index: s64 }",
+        "arith-address: contract-address",
+      ]
+    >
+  >().toEqualTypeOf<{
+    readonly name: "arith-address";
+    readonly type: "tuple";
+    readonly components: readonly [
+      {
+        readonly name: "name";
+        readonly type: "string";
+      },
+      {
+        readonly name: "height";
+        readonly type: "s64";
+      },
+      {
+        readonly name: "tx-index";
+        readonly type: "s64";
+      },
+    ];
+  }>();
+
+  expectTypeOf<
+    ParseWitParameter<
+      [
+        "record contract-address {  name: string, height: s64, tx-index: s64 }",
+        "arith-address: result<contract-address, error>",
+      ]
+    >
+  >().toEqualTypeOf<{
+    readonly name: "arith-address";
+    readonly type: "result<tuple, error>";
+    readonly components: readonly [
+      {
+        readonly name: "name";
+        readonly type: "string";
+      },
+      {
+        readonly name: "height";
+        readonly type: "s64";
+      },
+      {
+        readonly name: "tx-index";
+        readonly type: "s64";
+      },
+    ];
+  }>();
+});
+
+test("parseWitParameter", () => {
+  expect(() => parseWitParameter(" ")).toThrowErrorMatchingInlineSnapshot(
+    `
+    [InvalidWitParameterError: Failed to parse Wit parameter.
+
+    Details: parseWitParameter(" ")
+    Version: kontor-2dk@1.0.0]
+  `,
+  );
+});
+
+test.each([
+  {
+    signature: "ctx: borrow<proc-context>",
+    expected: { name: "ctx", type: "borrow<proc-context>" },
+  },
+  {
+    signature: "arith-address: contract-address",
+    expected: { name: "arith-address", type: "contract-address" },
+  },
+  {
+    signature: [
+      "record contract-address {  name: string, height: s64, tx-index: s64 }",
+      "arith-address: contract-address",
+    ],
+    expected: {
+      name: "arith-address",
+      type: "tuple",
+      components: [
+        {
+          name: "name",
+          type: "string",
+        },
+        {
+          name: "height",
+          type: "s64",
+        },
+        {
+          name: "tx-index",
+          type: "s64",
+        },
+      ],
+    },
+  },
+  {
+    signature: [
+      "record contract-address {  name: string, height: s64, tx-index: s64 }",
+      "arith-address:  result<contract-address, error>",
+    ],
+    expected: {
+      name: "arith-address",
+      type: "result<tuple, error>",
+      components: [
+        {
+          name: "name",
+          type: "string",
+        },
+        {
+          name: "height",
+          type: "s64",
+        },
+        {
+          name: "tx-index",
+          type: "s64",
+        },
+      ],
+    },
+  },
+])("parseAbiParameter($signature)", ({ signature, expected }) => {
+  expect(parseWitParameter<string | string[]>(signature)).toEqual(expected);
+});

package/src/wit/wit-parser/parse-wit-parameter.ts

@@ -0,0 +1,82 @@
+import type { Error_ } from "../error.js";
+import type { WitParameter } from "../wit.js";
+import type { Narrow } from "../narrow.js";
+import type { Filter } from "../type-utils.js";
+import { InvalidWitParameterError } from "./core/errors/wit-parameter.js";
+import { parseRecords } from "./core/records.js";
+import { isRecordSignature } from "./core/signatures.js";
+import type { ParseRecords } from "./core/types/records.js";
+import type { IsRecordSignature } from "./core/types/signatures.js";
+import type { ParseWitParameter as ParseWitParameter_ } from "./core/types/utils.js";
+import { parseWitParameter as parseWitParameter_ } from "./core/utils.js";
+
+export type ParseWitParameter<
+  param extends string | readonly string[] | readonly unknown[],
+> =
+  | (param extends string
+      ? param extends ""
+        ? never
+        : string extends param
+          ? WitParameter
+          : // TODO: pass options here?
+            ParseWitParameter_<param>
+      : never)
+  | (param extends readonly string[]
+      ? string[] extends param
+        ? WitParameter // Return generic AbiParameter item since type was no inferrable
+        : ParseRecords<param> extends infer records
+          ? {
+              [key in keyof param]: param[key] extends string
+                ? IsRecordSignature<param[key]> extends true
+                  ? never
+                  : ParseWitParameter_<param[key], { records: records }>
+                : never;
+            } extends infer mapped extends readonly unknown[]
+            ? Filter<mapped, never>[0] extends infer result
+              ? result extends undefined
+                ? never
+                : result
+              : never
+            : never
+          : never
+      : never);
+
+export function parseWitParameter<
+  param extends string | readonly string[] | readonly unknown[],
+>(
+  param: Narrow<param> &
+    (
+      | (param extends string
+          ? param extends ""
+            ? Error_<"Empty string is not allowed.">
+            : unknown
+          : never)
+      | (param extends readonly string[]
+          ? param extends readonly [] // empty array
+            ? Error_<"At least one parameter required.">
+            : string[] extends param
+              ? unknown
+              : unknown // TODO: Validate param string
+          : never)
+    ),
+): ParseWitParameter<param> {
+  let witParameter: WitParameter | undefined;
+  if (typeof param === "string")
+    witParameter = parseWitParameter_(param, {}) as ParseWitParameter<param>;
+  else {
+    const records = parseRecords(param as readonly string[]);
+    const length = param.length as number;
+    for (let i = 0; i < length; i++) {
+      const signature = (param as readonly string[])[i]!;
+      if (isRecordSignature(signature)) continue;
+      witParameter = parseWitParameter_(signature, {
+        records: records,
+      });
+      break;
+    }
+  }
+
+  if (!witParameter) throw new InvalidWitParameterError({ param });
+
+  return witParameter as ParseWitParameter<param>;
+}

package/src/wit/wit-parser/parse-wit.test.ts

@@ -0,0 +1,200 @@
+import { expectTypeOf, describe, expect, test } from "vitest";
+
+import type { ParseWit } from "./parse-wit.js";
+import { parseWit } from "./parse-wit.js";
+
+test("ParseWit (types)", () => {
+  // type-level assertions
+
+  expectTypeOf<
+    ParseWit<
+      [
+        "record contract-address {  name: string, height: s64, tx-index: s64 }",
+        "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>;",
+      ]
+    >
+  >().toEqualTypeOf<
+    readonly [
+      {
+        readonly name: "fib";
+        readonly type: "function";
+        readonly context: "proc";
+        readonly inputs: readonly [
+          {
+            readonly name: "arith-address";
+            readonly type: "tuple";
+            readonly components: readonly [
+              { readonly name: "name"; readonly type: "string" },
+              { readonly name: "height"; readonly type: "s64" },
+              { readonly name: "tx-index"; readonly type: "s64" },
+            ];
+          },
+          { readonly name: "n"; readonly type: "u64" },
+        ];
+        readonly outputs: readonly [{ readonly type: "u64" }];
+      },
+      {
+        readonly name: "fib-of-sub";
+        readonly type: "function";
+        readonly context: "proc";
+        readonly inputs: readonly [
+          {
+            readonly name: "arith-address";
+            readonly type: "tuple";
+
+            readonly components: readonly [
+              { readonly name: "name"; readonly type: "string" },
+              { readonly name: "height"; readonly type: "s64" },
+              { readonly name: "tx-index"; readonly type: "s64" },
+            ];
+          },
+          { readonly name: "x"; readonly type: "string" },
+          { readonly name: "y"; readonly type: "string" },
+        ];
+        readonly outputs: readonly [{ readonly type: "result<u64, error>" }];
+      },
+      {
+        readonly name: "cached-values";
+        readonly type: "function";
+        readonly context: "view";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{ readonly type: "list<u64>" }];
+      },
+    ]
+  >();
+
+  expectTypeOf<
+    ParseWit<
+      [
+        "record contract-address {  name: string, height: s64, tx-index: s64 }",
+        "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>;",
+      ]
+    >
+  >().toEqualTypeOf<
+    readonly [
+      {
+        readonly name: "fib";
+        readonly type: "function";
+        readonly context: "proc";
+        readonly inputs: readonly [
+          {
+            readonly name: "arith-address";
+            readonly type: "tuple";
+            readonly components: readonly [
+              { readonly name: "name"; readonly type: "string" },
+              { readonly name: "height"; readonly type: "s64" },
+              { readonly name: "tx-index"; readonly type: "s64" },
+            ];
+          },
+          { readonly name: "n"; readonly type: "u64" },
+        ];
+        readonly outputs: readonly [{ readonly type: "u64" }];
+      },
+      {
+        readonly name: "fib-of-sub";
+        readonly type: "function";
+        readonly context: "proc";
+        readonly inputs: readonly [
+          {
+            readonly name: "arith-address";
+            readonly type: "tuple";
+
+            readonly components: readonly [
+              { readonly name: "name"; readonly type: "string" },
+              { readonly name: "height"; readonly type: "s64" },
+              { readonly name: "tx-index"; readonly type: "s64" },
+            ];
+          },
+          { readonly name: "x"; readonly type: "string" },
+          { readonly name: "y"; readonly type: "string" },
+        ];
+        readonly outputs: readonly [{ readonly type: "result<u64, error>" }];
+      },
+      {
+        readonly name: "cached-values";
+        readonly type: "function";
+        readonly context: "view";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{ readonly type: "list<u64>" }];
+      },
+    ]
+  >();
+});
+
+describe("parseWit (runtime)", () => {
+  test("parses proc + view functions and strips ctx from inputs", () => {
+    const input = [
+      // TODO: build in record defs should be defined under the hood
+      "record contract-address {  name: string, height: s64, tx-index: s64 }",
+      "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>;",
+      "export return-option: func(ctx: borrow<view-context>) -> option<u64>;",
+    ] as const;
+
+    const out = parseWit(input);
+
+    expect(out).toEqual([
+      {
+        name: "fib",
+        type: "function",
+        context: "proc",
+        inputs: [
+          {
+            name: "arith-address",
+            type: "tuple",
+            components: [
+              { name: "name", type: "string" },
+              { name: "height", type: "s64" },
+              { name: "tx-index", type: "s64" },
+            ],
+          },
+          { name: "n", type: "u64" },
+        ],
+        outputs: [{ type: "u64" }],
+      },
+      {
+        name: "fib-of-sub",
+        type: "function",
+        context: "proc",
+        inputs: [
+          {
+            name: "arith-address",
+            type: "tuple",
+
+            components: [
+              { name: "name", type: "string" },
+              { name: "height", type: "s64" },
+              { name: "tx-index", type: "s64" },
+            ],
+          },
+          { name: "x", type: "string" },
+          { name: "y", type: "string" },
+        ],
+        outputs: [
+          {
+            type: "result<u64, error>",
+          },
+        ],
+      },
+      {
+        name: "cached-values",
+        type: "function",
+        context: "view",
+        inputs: [],
+        outputs: [{ type: "list<u64>" }],
+      },
+      {
+        name: "return-option",
+        type: "function",
+        context: "view",
+        inputs: [],
+        outputs: [{ type: "option<u64>" }],
+      },
+    ]);
+  });
+});

package/src/wit/wit-parser/parse-wit.ts

@@ -0,0 +1,65 @@
+import type { Wit } from "../wit.js";
+
+import type { Filter } from "../type-utils.js";
+import type { Error_ } from "../error.js";
+
+import { isRecordSignature } from "./core/signatures.js";
+import { parseRecords } from "./core/records.js";
+import { parseSignature } from "./core/utils.js";
+import type { Signatures } from "./core/types/signatures.js";
+import type { ParseRecords } from "./core/types/records.js";
+import type { ParseSignature } from "./core/types/utils.js";
+
+/**
+ * Parses human-readable ABI into JSON {@link Abi}
+ *
+ * @param signatures - Human-readable ABI
+ * @returns Parsed {@link Abi}
+ *
+ * @example
+ * type Result = ParseAbi<
+ *   // ^? type Result = readonly [{ name: "balanceOf"; type: "function"; stateMutability:...
+ *   [
+ *     'function balanceOf(address owner) view returns (uint256)',
+ *     'event Transfer(address indexed from, address indexed to, uint256 amount)',
+ *   ]
+ * >
+ */
+export type ParseWit<signatures extends readonly string[]> =
+  string[] extends signatures
+    ? Wit // If `T` was not able to be inferred (e.g. just `string[]`), return `Abi`
+    : signatures extends readonly string[]
+      ? signatures extends Signatures<signatures> // Validate signatures
+        ? ParseRecords<signatures> extends infer structs
+          ? {
+              [key in keyof signatures]: signatures[key] extends string
+                ? ParseSignature<signatures[key], structs>
+                : never;
+            } extends infer mapped extends readonly unknown[]
+            ? Filter<mapped, never> extends infer result
+              ? result extends readonly []
+                ? never
+                : result
+              : never
+            : never
+          : never
+        : never
+      : never;
+
+export function parseWit<const signatures extends readonly string[]>(
+  signatures: signatures["length"] extends 0
+    ? Error_<"At least one signature required">
+    : Signatures<signatures> extends signatures
+      ? signatures
+      : Signatures<signatures>,
+): ParseWit<signatures> {
+  const structs = parseRecords(signatures as readonly string[]);
+  const wit = [];
+  const length = signatures.length as number;
+  for (let i = 0; i < length; i++) {
+    const signature = (signatures as readonly string[])[i]!;
+    if (isRecordSignature(signature)) continue;
+    wit.push(parseSignature(signature, structs));
+  }
+  return wit as unknown as ParseWit<signatures>;
+}

package/src/wit/wit.test.ts

@@ -0,0 +1,8 @@
+import { assertType, test } from "vitest";
+
+import type { WitError } from "./wit.js";
+
+//TODO: fill this out
+test("Wit Types", () => {
+  assertType<WitError>("error");
+});

package/src/wit/wit.ts

@@ -0,0 +1,166 @@
+import type { ResolvedRegister } from "./register.js";
+
+import type { Pretty } from "./type-utils.js";
+
+export type MBits = 8 | 16 | 32 | 64;
+
+// TODO: maybe don't even rely on ResolvedRegister...
+export type Address = ResolvedRegister["addressType"];
+
+// TODO: audit all of these ( e.g i don't think WitContractAddress is used )
+export type WitContractAddress = "contract-address";
+export type WitInteger = "integer";
+export type WitDecimal = "decimal";
+
+// export type WitViewContext = "borrow<view-context>";
+//
+//
+//
+// export type WitFunc = "func";
+
+// todo: maybe we should just rename this to record
+export type WitTuple = "tuple";
+export type WitError = "error";
+export type WitUnit = "_";
+
+export type WitBool = "bool";
+export type WitSInt = `s${MBits}`;
+export type WitUInt = `u${MBits}`;
+// export type WitFloat = "f32" | "f64";
+export type WitString = "string";
+// export type WitChar = "char";
+
+export type WitInt = WitSInt | WitUInt;
+
+// TODO: fixed range array
+
+type _BuildOptionTypes<T extends string> = `option<${T}>`;
+export type WitOptionWithoutTuple = _BuildOptionTypes<
+  | WitBool
+  | WitSInt
+  | WitUInt
+  // WitFloat |
+  | WitString
+  | WitDecimal
+  | WitInteger
+  | WitUnit
+  // | WitChar
+>;
+
+export type WitOptionWithTuple = _BuildOptionTypes<WitTuple>;
+
+export type WitOptionWithList = _BuildOptionTypes<WitList>;
+
+export type WitOption =
+  | WitOptionWithoutTuple
+  | WitOptionWithTuple
+  | WitOptionWithList;
+
+type _BuildResultTypes<T extends string> = `result<${T}, error>`;
+
+export type WitResultWithoutTuple = _BuildResultTypes<
+  | WitBool
+  | WitSInt
+  | WitUInt
+  // WitFloat |
+  | WitString
+  | WitOption
+  | WitInteger
+  | WitDecimal
+  | WitUnit
+
+  // | WitChar
+>;
+export type WitResultWithTuple = _BuildResultTypes<WitTuple>;
+
+export type WitResultWithList = _BuildResultTypes<WitList>;
+
+export type WitResult =
+  | WitResultWithoutTuple
+  | WitResultWithTuple
+  | WitResultWithList;
+
+// todo: add option / decimal
+type _BuildListTypes<T extends string> = `list<${T}>`;
+export type WitListWithoutTuple = _BuildListTypes<
+  | WitBool
+  | WitSInt
+  | WitUInt
+  // WitFloat |
+  | WitString
+  | WitInteger
+  | WitDecimal
+  | WitUnit
+  // | WitChar
+>;
+
+export type WitListWithTuple = _BuildListTypes<WitTuple>;
+
+export type WitList = WitListWithoutTuple | WitListWithTuple;
+
+// TODO: this is a misnomer now
+export type WitStateMutability = "view" | "proc" | "core";
+
+export type WitParameterKind = "inputs" | "outputs";
+
+export type WitType =
+  | WitContractAddress
+  // | WitProcContext
+  // | WitViewContext
+  // | WitFunc
+  | WitTuple
+  | WitResult
+  | WitError
+  | WitBool
+  | WitSInt
+  | WitUInt
+  // | WitFloat
+  | WitString
+  | WitInteger
+  | WitDecimal
+  // | WitChar
+  | WitList
+  | WitOption;
+
+// TODO: audit this behavior
+type ResolvedWitType = ResolvedRegister["strictWitType"] extends true
+  ? WitType
+  : string;
+
+// TODO: audit internal type, is it used anywhere?
+export type WitInternalType = ResolvedWitType | `record ${string}`;
+
+export type WitParameter = Pretty<{
+  type: string;
+  name?: string | undefined;
+  internalType?: WitInternalType | undefined;
+  components?: readonly WitParameter[];
+}>;
+
+export type WitItemType = "func";
+
+export type WitFunction = {
+  type: "function";
+  name: string;
+  inputs: readonly WitParameter[];
+  outputs: readonly WitParameter[];
+  payable?: boolean | undefined;
+  context: WitStateMutability;
+};
+
+export type Wit = readonly WitFunction[];
+
+// TODO: refine, maybe add result / option
+export type TypedDataType = Exclude<WitType, WitTuple | WitListWithTuple>;
+
+export type TypedDataParameter = {
+  name: string;
+  type: TypedDataType | keyof TypedData | `${keyof TypedData}[${string | ""}]`;
+};
+
+export type TypedData = Pretty<
+  Record<string, readonly TypedDataParameter[]> & {
+    // Disallow `TypedDataType` as key names (e.g. `address`)
+    [_ in TypedDataType]?: never;
+  }
+>;

package/test/globalSetup.ts

@@ -0,0 +1,16 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setup } from "@arktype/attest";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export default function () {
+	return setup({
+		benchErrorOnThresholdExceeded: true,
+		tsconfig: resolve(__dirname, "../tsconfig.json"),
+	});
+}
+
+// biome-ignore lint/performance/noBarrelFile: <explanation>
+export { teardown } from "@arktype/attest";

package/test/src/wits.ts

@@ -0,0 +1,23 @@
+import { parseWit } from "../../src/wit/wit-parser/parse-wit.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 nativeToken = parseWit(nativeTokenRaw);