@kontor/kontor-sdk 1.0.0-alpha.39 → 1.0.0-alpha.40

package/src/sdk/utils/wit/codecs/contract-address.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { ContractAddressCodec } from "./contract-address.js";
+
+describe("ContractAddressCodec (i64 wire)", () => {
+  it("encodes string -> wave struct (raw asserted)", () => {
+    expect(ContractAddressCodec.encodeWave("foo_123_7")).toBe(
+      `{name: "foo", height: 123, tx_index: 7}`,
+    );
+  });
+
+  it("decodes wave struct -> string", () => {
+    expect(
+      ContractAddressCodec.decodeWave(
+        `{name: "foo", height: 123, tx_index: 7}`,
+      ),
+    ).toBe("foo_123_7");
+  });
+
+  it("supports negative i64 values (within JS safe integer range)", () => {
+    expect(
+      ContractAddressCodec.decodeWave(`{name: "foo", height: -1, tx_index: 0}`),
+    ).toBe("foo_-1_0");
+
+    expect(ContractAddressCodec.encodeWave("foo_-1_0")).toBe(
+      `{name: "foo", height: -1, tx_index: 0}`,
+    );
+  });
+
+  it("rejects i64 values beyond JS safe integer range", () => {
+    // 2^63-1 fits i64 but not JS safe int
+    expect(() =>
+      ContractAddressCodec.decodeWave(
+        `{name: "foo", height: 9223372036854775807, tx_index: 0}`,
+      ),
+    ).toThrow("height exceeds JS safe integer range");
+  });
+});

package/src/sdk/utils/wit/codecs/contract-address.ts

@@ -0,0 +1,114 @@
+import type { Codec } from "./types.js";
+import { stripOuter, splitTopLevelComma, splitTopLevelColon } from "./util.js";
+import { StringCodec } from "./string.js";
+import type { ResolvedRegister } from "../../../../wit/register.js";
+
+export type ContractAddress = ResolvedRegister["contractAddress"];
+
+type ContractAddressWave = {
+  name: string;
+  height: number; // safe JS number
+  tx_index: number; // safe JS number
+};
+
+const I64_MIN = -(1n << 63n);
+const I64_MAX = (1n << 63n) - 1n;
+
+function parseI64AsSafeNumber(expr: string, ctx: string): number {
+  const s = expr.trim().replace(/_/g, "");
+  if (!/^[+-]?\d+$/.test(s)) throw new Error(`invalid integer: ${ctx}`);
+
+  const bi = BigInt(s);
+  if (bi < I64_MIN || bi > I64_MAX) throw new Error(`${ctx} out of range`);
+
+  // ensure round-trip safe as number
+  const n = Number(bi);
+  if (!Number.isSafeInteger(n)) {
+    throw new Error(`${ctx} exceeds JS safe integer range`);
+  }
+  return n;
+}
+
+function encodeI64FromSafeNumber(n: number, ctx: string): string {
+  if (!Number.isFinite(n) || !Number.isInteger(n)) {
+    throw new Error(`invalid integer: ${ctx}`);
+  }
+  if (!Number.isSafeInteger(n)) {
+    throw new Error(`${ctx} exceeds JS safe integer range`);
+  }
+  const bi = BigInt(n);
+  if (bi < I64_MIN || bi > I64_MAX) throw new Error(`${ctx} out of range`);
+  return bi.toString(10);
+}
+
+function parseContractAddressWave(expr: string): ContractAddressWave {
+  const { inner, hadOuter } = stripOuter(expr, "{", "}");
+  if (!hadOuter) throw new Error(`invalid contract address: ${expr}`);
+
+  const inside = inner.trim();
+  if (!inside) throw new Error(`invalid contract address: ${expr}`);
+
+  const parts = splitTopLevelComma(inside);
+  const out: Partial<ContractAddressWave> = {};
+
+  for (const part of parts) {
+    const [k, v] = splitTopLevelColon(part);
+    switch (k) {
+      case "name":
+        out.name = StringCodec.decodeWave(v);
+        break;
+      case "height":
+        out.height = parseI64AsSafeNumber(v, "height");
+        break;
+      case "tx_index":
+        out.tx_index = parseI64AsSafeNumber(v, "tx_index");
+        break;
+      default:
+        throw new Error(`unexpected key "${k}" in contract address`);
+    }
+  }
+
+  if (out.name === undefined) throw new Error(`missing required key "name"`);
+  if (out.height === undefined)
+    throw new Error(`missing required key "height"`);
+  if (out.tx_index === undefined)
+    throw new Error(`missing required key "tx_index"`);
+
+  return out as ContractAddressWave;
+}
+
+// NOTE: This TS encoding is ambiguous if name contains "_".
+// If underscores are valid in contract names, switch to a different TS representation.
+function toDefaultString(a: ContractAddressWave): ContractAddress {
+  if (a.name.includes("_")) throw new Error(`contract name cannot contain "_"`);
+  return `${a.name}_${a.height}_${a.tx_index}` as ContractAddress;
+}
+
+function fromDefaultString(s: ContractAddress): ContractAddressWave {
+  const raw = String(s);
+  const parts = raw.split("_");
+  if (parts.length !== 3) throw new Error(`invalid contract address: ${raw}`);
+
+  const [name, heightStr, txIndexStr] = parts;
+  if (!name) throw new Error(`invalid contract address: ${raw}`);
+
+  const height = parseI64AsSafeNumber(heightStr!, "height");
+  const tx_index = parseI64AsSafeNumber(txIndexStr!, "tx_index");
+
+  return { name, height, tx_index };
+}
+
+export const ContractAddressCodec: Codec<ContractAddress> = {
+  decodeWave(expr: string): ContractAddress {
+    return toDefaultString(parseContractAddressWave(expr));
+  },
+
+  encodeWave(value: ContractAddress): string {
+    const a = fromDefaultString(value);
+
+    return `{name: ${StringCodec.encodeWave(a.name)}, height: ${encodeI64FromSafeNumber(
+      a.height,
+      "height",
+    )}, tx_index: ${encodeI64FromSafeNumber(a.tx_index, "tx_index")}}`;
+  },
+};

package/src/sdk/utils/wit/codecs/index.ts

@@ -0,0 +1,20 @@
+export { BoolCodec } from "./bool.js";
+export { ListCodec } from "./list.js";
+export {
+  IntegerCodec,
+  DecimalCodec,
+  S8Codec,
+  S16Codec,
+  S32Codec,
+  S64Codec,
+  U8Codec,
+  U16Codec,
+  U32Codec,
+  U64Codec,
+} from "./numerics.js";
+
+export { OptionCodec } from "./option.js";
+export { ResultCodec } from "./result.js";
+export { StringCodec } from "./string.js";
+export { UnitCodec } from "./unit.js";
+export { ContractAddressCodec } from "./contract-address.js";

package/src/sdk/utils/wit/codecs/list.test-d.ts

@@ -0,0 +1,13 @@
+import { describe, it, expectTypeOf } from "vitest";
+import type { Codec } from "./types.js";
+import { ListCodec } from "./list.js";
+import { IntegerCodec } from "./numerics.js";
+
+describe("ListCodec types", () => {
+  it("preserves inner type T", () => {
+    const c = ListCodec(IntegerCodec);
+    expectTypeOf(c).toEqualTypeOf<Codec<bigint[]>>();
+    expectTypeOf(c.decodeWave).returns.toEqualTypeOf<bigint[]>();
+    expectTypeOf(c.encodeWave).parameter(0).toEqualTypeOf<bigint[]>();
+  });
+});

package/src/sdk/utils/wit/codecs/list.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+
+import { ListCodec } from "./list.js";
+import { IntegerCodec } from "./numerics.js";
+
+describe("ListCodec", () => {
+  const ListOfInt = ListCodec(IntegerCodec);
+
+  it("decodes and encodes empty list", () => {
+    expect(ListOfInt.decodeWave("[]")).toEqual([]);
+    expect(ListOfInt.decodeWave("[   ]")).toEqual([]);
+
+    expect(ListOfInt.encodeWave([])).toBe("[]");
+  });
+
+  it("decodes list of nested wave structs", () => {
+    const wave =
+      "[{r0: 1, r1: 0, r2: 0, r3: 0, sign: plus}, {r0: 2, r1: 0, r2: 0, r3: 0, sign: minus}]";
+
+    expect(ListOfInt.decodeWave(wave)).toEqual([1n, -2n]);
+  });
+
+  it("encodes list using the inner codec canonical encoding", () => {
+    expect(ListOfInt.encodeWave([1n, -2n])).toBe(
+      "[{r0: 1, r1: 0, r2: 0, r3: 0, sign: plus}, {r0: 2, r1: 0, r2: 0, r3: 0, sign: minus}]",
+    );
+  });
+
+  it("round-trips: decode -> encode -> decode", () => {
+    const wave =
+      "[{r0: 123, r1: 0, r2: 0, r3: 0, sign: plus}, {r0: 0, r1: 0, r2: 0, r3: 0, sign: plus}]";
+
+    const js1 = ListOfInt.decodeWave(wave);
+    const wave2 = ListOfInt.encodeWave(js1);
+    const js2 = ListOfInt.decodeWave(wave2);
+
+    expect(js2).toEqual(js1);
+    expect(wave2).toBe(wave);
+  });
+
+  it("throws on non-list input", () => {
+    expect(() => ListOfInt.decodeWave("none")).toThrow("invalid list: none");
+    expect(() => ListOfInt.decodeWave("{r0: 1}")).toThrow(
+      "invalid list: {r0: 1}",
+    );
+  });
+
+  it("handles commas inside nested structures (does not split incorrectly)", () => {
+    // Each element is an integer *struct* which itself contains commas.
+    const wave =
+      "[{r0: 7, r1: 0, r2: 0, r3: 0, sign: plus}, {r0: 8, r1: 0, r2: 0, r3: 0, sign: plus}]";
+
+    expect(ListOfInt.decodeWave(wave)).toEqual([7n, 8n]);
+  });
+});

package/src/sdk/utils/wit/codecs/list.ts

@@ -1,154 +1,25 @@
-import type {
-  WaveExpr,
-  CodecConstructor,
-  CodecInstance,
-  CodecJs,
-  CodecInst,
-  CodecWave,
-} from "./types.js";
-
-// The JS-side shape we expose for list<T>
-export type ListJs<T> = T[];
-
-/**
- * Instance that represents a decoded list<Inner> value.
- *
- * Generic parameterization is on the *inner codec constructor* so that
- * the JS type of this list instance is always ListJs<CodecJs<InnerC>>.
- */
-export class ListCodecFactory<
-  InnerC extends CodecConstructor<unknown, CodecInstance<unknown>, unknown>,
-> implements CodecInstance<ListJs<CodecJs<InnerC>>>
-{
-  constructor(
-    private readonly innerCodec: InnerC,
-    public readonly data: string[], // array of wave expressions for each element
-  ) {}
-
-  toWave(): WaveExpr {
-    // Convert array of inner wave expressions back to array syntax
-    const innerWaves = this.data.join(", ");
-    return `[${innerWaves}]` as WaveExpr;
-  }
-
-  toJs(): ListJs<CodecJs<InnerC>> {
-    // Decode each element using the inner codec
-    return this.data.map((innerWave) => {
-      // 1) parse inner WaveExpr → inner WaveData
-      const innerWaveData = this.innerCodec.parseWave(
-        innerWave,
-      ) as CodecWave<InnerC>;
-
-      // 2) WaveData → inner instance
-      const innerInst = this.innerCodec.fromKontor(
-        innerWaveData,
-      ) as CodecInst<InnerC>;
-
-      // 3) instance → JS
-      return innerInst.toJs() as CodecJs<InnerC>;
-    });
-  }
-
-  // ----- Static factory to build a typed list<T> codec constructor -----
-
-  static create<
-    InnerC extends CodecConstructor<unknown, CodecInstance<unknown>, unknown>,
-  >(
-    innerCodec: InnerC,
-  ): CodecConstructor<
-    // JS type this codec produces:
-    ListJs<CodecJs<InnerC>>,
-    // instance type:
-    ListCodecFactory<InnerC>,
-    // wave data type (array of inner wave strings):
-    string[]
-  > {
-    // Class expression implements the static methods required by CodecConstructor
-    class ListCodecClass implements CodecInstance<ListJs<CodecJs<InnerC>>> {
-      // Internally forward all instance behavior to ListCodecFactory
-      private readonly _impl: ListCodecFactory<InnerC>;
-
-      constructor(data: string[]) {
-        this._impl = new ListCodecFactory(innerCodec, data);
-      }
-
-      toWave(): WaveExpr {
-        return this._impl.toWave();
+import type { Codec } from "./types.js";
+import { stripOuter, splitTopLevelComma } from "./util.js";
+
+export function ListCodec<T>(inner: Codec<T>): Codec<T[]> {
+  return {
+    decodeWave(expr: string): T[] {
+      const t = expr.trim();
+      if (t === "[]") return [];
+
+      const { inner: inside, hadOuter } = stripOuter(t, "[", "]");
+      if (!hadOuter) {
+        throw new Error(`invalid list: ${expr}`);
       }
+      if (inside.trim() === "") return [];
 
-      toJs(): ListJs<CodecJs<InnerC>> {
-        return this._impl.toJs();
-      }
-
-      // ----- Static methods required by CodecConstructor -----
-
-      static fromJs(value: ListJs<CodecJs<InnerC>>): ListCodecClass {
-        // Convert JS array to array of wave expressions
-        const waveArray = value.map((item) => {
-          const innerInst = innerCodec.fromJs(item as any);
-          return innerInst.toWave();
-        });
-        return new ListCodecClass(waveArray);
-      }
-
-      static fromKontor(data: string[]): ListCodecClass {
-        return new ListCodecClass(data);
-      }
-
-      static parseWave(expr: string): string[] {
-        // Parse array syntax: "[item1, item2, ...]"
-        const trimmed = expr.trim();
-
-        // Empty array
-        if (trimmed === "[]") {
-          return [];
-        }
-
-        // Remove brackets
-        if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
-          throw new Error(`Expected array syntax [...], got: ${expr}`);
-        }
-
-        const inner = trimmed.slice(1, -1).trim();
-        if (inner === "") {
-          return [];
-        }
-
-        // Split by commas at the top level (respecting nested structures)
-        const items: string[] = [];
-        let depth = 0;
-        let current = "";
-
-        for (let i = 0; i < inner.length; i++) {
-          const char = inner[i];
-
-          if (char === "{" || char === "[" || char === "(") {
-            depth++;
-            current += char;
-          } else if (char === "}" || char === "]" || char === ")") {
-            depth--;
-            current += char;
-          } else if (char === "," && depth === 0) {
-            items.push(current.trim());
-            current = "";
-          } else {
-            current += char;
-          }
-        }
-
-        // Add last item
-        if (current.trim()) {
-          items.push(current.trim());
-        }
-
-        return items;
-      }
-    }
+      const parts = splitTopLevelComma(inside);
+      return parts.map((p) => inner.decodeWave(p));
+    },
 
-    return ListCodecClass as unknown as CodecConstructor<
-      ListJs<CodecJs<InnerC>>,
-      ListCodecFactory<InnerC>,
-      string[]
-    >;
-  }
+    encodeWave(value: T[]): string {
+      const items = value.map((v) => inner.encodeWave(v)).join(", ");
+      return `[${items}]`;
+    },
+  };
 }