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

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

@@ -0,0 +1,399 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  IntegerCodec,
+  DecimalCodec,
+  U8Codec,
+  U16Codec,
+  U32Codec,
+  U64Codec,
+  S8Codec,
+  S16Codec,
+  S32Codec,
+  S64Codec,
+} from "./numerics.js";
+describe("numerics codecs", () => {
+  describe("IntegerCodec", () => {
+    it("decodes a positive integer wave struct", () => {
+      const v = IntegerCodec.decodeWave(
+        "{r0: 1, r1: 0, r2: 0, r3: 0, sign: plus}",
+      );
+      expect(v).toBe(1n);
+    });
+
+    it("decodes a negative integer wave struct", () => {
+      const v = IntegerCodec.decodeWave(
+        "{r0: 1, r1: 0, r2: 0, r3: 0, sign: minus}",
+      );
+      expect(v).toBe(-1n);
+    });
+
+    it("defaults r1..r3 to 0 when omitted", () => {
+      const v = IntegerCodec.decodeWave("{r0: 42, sign: plus}");
+      expect(v).toBe(42n);
+    });
+
+    it("accepts underscores in limb literals", () => {
+      const v = IntegerCodec.decodeWave("{r0: 1234, sign: plus}");
+      expect(v).toBe(1234n);
+    });
+
+    it("round-trips: decode -> encode -> decode", () => {
+      const wave = "{r0: 7, r1: 0, r2: 0, r3: 0, sign: plus}";
+      const js1 = IntegerCodec.decodeWave(wave);
+      const wave2 = IntegerCodec.encodeWave(js1);
+      const js2 = IntegerCodec.decodeWave(wave2);
+      expect(js2).toBe(js1);
+    });
+
+    it("round-trips large values within 128-bit magnitude", () => {
+      const values = [
+        0n,
+        1n,
+        -1n,
+        (1n << 32n) - 1n,
+        1n << 32n,
+        (1n << 96n) + 123n,
+        (1n << 127n) - 1n,
+        -((1n << 127n) - 1n),
+      ];
+
+      for (const v of values) {
+        const wave = IntegerCodec.encodeWave(v);
+        const decoded = IntegerCodec.decodeWave(wave);
+        expect(decoded).toBe(v);
+      }
+    });
+
+    it("throws on missing r0", () => {
+      expect(() => IntegerCodec.decodeWave("{sign: plus}")).toThrow(
+        'missing required key "r0"',
+      );
+    });
+
+    it("throws on missing sign", () => {
+      expect(() => IntegerCodec.decodeWave("{r0: 1}")).toThrow(
+        'missing required key "sign"',
+      );
+    });
+
+    it("throws on invalid sign", () => {
+      expect(() => IntegerCodec.decodeWave("{r0: 1, sign: PLUS}")).toThrow(
+        "invalid sign",
+      );
+    });
+
+    it("throws on invalid limb literal", () => {
+      expect(() => IntegerCodec.decodeWave("{r0: 1.2, sign: plus}")).toThrow(
+        "invalid integer for r0",
+      );
+    });
+
+    it("throws when limb is out of u32 range", () => {
+      const tooBig = (1n << 32n).toString(); // 2^32
+      expect(() =>
+        IntegerCodec.decodeWave(`{r0: ${tooBig}, sign: plus}`),
+      ).toThrow("r0 must be a u32");
+    });
+
+    it("throws on duplicate keys", () => {
+      expect(() =>
+        IntegerCodec.decodeWave("{r0: 1, r0: 2, sign: plus}"),
+      ).toThrow('duplicate key "r0"');
+    });
+
+    it("throws on unexpected keys", () => {
+      expect(() =>
+        IntegerCodec.decodeWave("{r0: 1, r9: 2, sign: plus}"),
+      ).toThrow('unexpected key "r9"');
+    });
+  });
+
+  describe("DecimalCodec", () => {
+    it("decodes a positive decimal wave struct into [coef, 18]", () => {
+      const v = DecimalCodec.decodeWave(
+        "{r0: 7, r1: 0, r2: 0, r3: 0, sign: plus}",
+      );
+      expect(v).toEqual([7n, 18]);
+    });
+
+    it("decodes a negative decimal wave struct", () => {
+      const v = DecimalCodec.decodeWave(
+        "{r0: 7, r1: 0, r2: 0, r3: 0, sign: minus}",
+      );
+      expect(v).toEqual([-7n, 18]);
+    });
+
+    it("defaults r1..r3 to 0 when omitted", () => {
+      const v = DecimalCodec.decodeWave("{r0: 123, sign: plus}");
+      expect(v).toEqual([123n, 18]);
+    });
+
+    it("accepts underscores in limb literals", () => {
+      const v = DecimalCodec.decodeWave("{r0: 1_234, sign: plus}");
+      expect(v).toEqual([1234n, 18]);
+    });
+
+    it("round-trips: decode -> encode -> decode", () => {
+      const wave = "{r0: 7, r1: 0, r2: 0, r3: 0, sign: plus}";
+      const js1 = DecimalCodec.decodeWave(wave);
+      const wave2 = DecimalCodec.encodeWave(js1);
+      const js2 = DecimalCodec.decodeWave(wave2);
+      expect(js2).toEqual(js1);
+    });
+
+    it("encodes by upscaling to 18 decimals", () => {
+      // [1, 0] => 1 * 10^18 in magnitude
+      const wave = DecimalCodec.encodeWave([1n, 0]);
+      const decoded = DecimalCodec.decodeWave(wave);
+      expect(decoded).toEqual([1n * 10n ** 18n, 18]);
+    });
+
+    it("throws on downscale requirement (scale > 18)", () => {
+      expect(() => DecimalCodec.encodeWave([1n, 19])).toThrow(
+        "cannot downscale",
+      );
+    });
+
+    it("throws on invalid sign", () => {
+      expect(() => DecimalCodec.decodeWave("{r0: 1, sign: nope}")).toThrow(
+        "invalid sign",
+      );
+    });
+
+    it("throws on invalid limb literal", () => {
+      expect(() => DecimalCodec.decodeWave("{r0: 1.2, sign: plus}")).toThrow(
+        "invalid integer for r0",
+      );
+    });
+
+    it("throws when limb is out of u64 range", () => {
+      const tooBig = (1n << 64n).toString(); // 2^64
+      expect(() =>
+        DecimalCodec.decodeWave(`{r0: ${tooBig}, sign: plus}`),
+      ).toThrow("r0 must be a u64");
+    });
+
+    it("throws on missing r0", () => {
+      expect(() => DecimalCodec.decodeWave("{sign: plus}")).toThrow(
+        'missing required key "r0"',
+      );
+    });
+
+    it("throws on missing sign", () => {
+      expect(() => DecimalCodec.decodeWave("{r0: 1}")).toThrow(
+        'missing required key "sign"',
+      );
+    });
+
+    it("throws on duplicate keys", () => {
+      expect(() =>
+        DecimalCodec.decodeWave("{r0: 1, r0: 2, sign: plus}"),
+      ).toThrow('duplicate key "r0"');
+    });
+
+    it("throws on unexpected keys", () => {
+      expect(() =>
+        DecimalCodec.decodeWave("{r0: 1, nope: 2, sign: plus}"),
+      ).toThrow('unexpected key "nope"');
+    });
+  });
+  describe("IntegerCodec.encodeWave", () => {
+    it("encodes 0", () => {
+      expect(IntegerCodec.encodeWave(0n)).toBe(
+        "{r0: 0, r1: 0, r2: 0, r3: 0, sign: plus}",
+      );
+    });
+
+    it("encodes 1 and -1", () => {
+      expect(IntegerCodec.encodeWave(1n)).toBe(
+        "{r0: 1, r1: 0, r2: 0, r3: 0, sign: plus}",
+      );
+      expect(IntegerCodec.encodeWave(-1n)).toBe(
+        "{r0: 1, r1: 0, r2: 0, r3: 0, sign: minus}",
+      );
+    });
+
+    it("encodes 2^32 (checks limb carry)", () => {
+      // 2^32 => r0 = 0, r1 = 1
+      expect(IntegerCodec.encodeWave(1n << 32n)).toBe(
+        "{r0: 0, r1: 1, r2: 0, r3: 0, sign: plus}",
+      );
+    });
+
+    it("encodes a value spanning multiple limbs", () => {
+      // r0=5, r1=4, r2=3, r3=2
+      const v = (2n << 96n) | (3n << 64n) | (4n << 32n) | 5n;
+
+      expect(IntegerCodec.encodeWave(v)).toBe(
+        "{r0: 5, r1: 4, r2: 3, r3: 2, sign: plus}",
+      );
+    });
+    describe("DecimalCodec.encodeWave", () => {
+      it("encodes [0, 18]", () => {
+        expect(DecimalCodec.encodeWave([0n, 18])).toBe(
+          "{r0: 0, r1: 0, r2: 0, r3: 0, sign: plus}",
+        );
+      });
+
+      it("encodes sign for negative coefficients", () => {
+        expect(DecimalCodec.encodeWave([-7n, 18])).toBe(
+          "{r0: 7, r1: 0, r2: 0, r3: 0, sign: minus}",
+        );
+      });
+
+      it("upscales smaller scales to 18 and encodes limbs", () => {
+        // [1,0] => 1 * 10^18
+        // 10^18 in hex is 0x0de0b6b3a7640000 which fits in r0 (u64)
+        expect(DecimalCodec.encodeWave([1n, 0])).toBe(
+          "{r0: 1000000000000000000, r1: 0, r2: 0, r3: 0, sign: plus}",
+        );
+      });
+
+      it("encodes a decimal spanning multiple 64-bit limbs", () => {
+        // magnitude = (r3<<192) | (r2<<128) | (r1<<64) | r0
+        const wave = "{r0: 5, r1: 4, r2: 3, r3: 2, sign: plus}";
+        const decoded = DecimalCodec.decodeWave(wave);
+        expect(DecimalCodec.encodeWave(decoded)).toBe(wave);
+      });
+    });
+  });
+});
+
+describe("numerics: fixed-width integer codecs", () => {
+  it("returns number for <=32-bit and bigint for 64-bit", () => {
+    expect(typeof U8Codec.decodeWave("1")).toBe("number");
+    expect(typeof U16Codec.decodeWave("1")).toBe("number");
+    expect(typeof U32Codec.decodeWave("1")).toBe("number");
+
+    expect(typeof S8Codec.decodeWave("-1")).toBe("number");
+    expect(typeof S16Codec.decodeWave("-1")).toBe("number");
+    expect(typeof S32Codec.decodeWave("-1")).toBe("number");
+
+    expect(typeof U64Codec.decodeWave("1")).toBe("bigint");
+    expect(typeof S64Codec.decodeWave("-1")).toBe("bigint");
+  });
+
+  it("accepts underscores in wave literals", () => {
+    expect(U16Codec.decodeWave("65_535")).toBe(65535);
+    expect(U64Codec.decodeWave("18_446_744_073_709_551_615")).toBe(
+      18446744073709551615n,
+    );
+  });
+
+  describe("unsigned bounds", () => {
+    it("u8", () => {
+      expect(U8Codec.decodeWave("0")).toBe(0);
+      expect(U8Codec.decodeWave("255")).toBe(255);
+
+      expect(() => U8Codec.decodeWave("-1")).toThrow("u8 out of range");
+      expect(() => U8Codec.decodeWave("256")).toThrow("u8 out of range");
+
+      expect(U8Codec.encodeWave(0)).toBe("0");
+      expect(U8Codec.encodeWave(255)).toBe("255");
+      expect(() => U8Codec.encodeWave(256)).toThrow("u8 out of range");
+    });
+
+    it("u16", () => {
+      expect(U16Codec.decodeWave("0")).toBe(0);
+      expect(U16Codec.decodeWave("65535")).toBe(65535);
+
+      expect(() => U16Codec.decodeWave("-1")).toThrow("u16 out of range");
+      expect(() => U16Codec.decodeWave("65536")).toThrow("u16 out of range");
+
+      expect(U16Codec.encodeWave(65535)).toBe("65535");
+    });
+
+    it("u32", () => {
+      expect(U32Codec.decodeWave("0")).toBe(0);
+      expect(U32Codec.decodeWave("4294967295")).toBe(4294967295);
+
+      expect(() => U32Codec.decodeWave("-1")).toThrow("u32 out of range");
+      expect(() => U32Codec.decodeWave("4294967296")).toThrow(
+        "u32 out of range",
+      );
+
+      expect(U32Codec.encodeWave(4294967295)).toBe("4294967295");
+    });
+
+    it("u64", () => {
+      expect(U64Codec.decodeWave("0")).toBe(0n);
+      expect(U64Codec.decodeWave("18446744073709551615")).toBe(
+        18446744073709551615n,
+      );
+
+      expect(() => U64Codec.decodeWave("-1")).toThrow("u64 out of range");
+      expect(() => U64Codec.decodeWave("18446744073709551616")).toThrow(
+        "u64 out of range",
+      );
+
+      expect(U64Codec.encodeWave(18446744073709551615n)).toBe(
+        "18446744073709551615",
+      );
+    });
+  });
+
+  describe("signed bounds", () => {
+    it("s8", () => {
+      expect(S8Codec.decodeWave("-128")).toBe(-128);
+      expect(S8Codec.decodeWave("127")).toBe(127);
+
+      expect(() => S8Codec.decodeWave("-129")).toThrow("s8 out of range");
+      expect(() => S8Codec.decodeWave("128")).toThrow("s8 out of range");
+    });
+
+    it("s16", () => {
+      expect(S16Codec.decodeWave("-32768")).toBe(-32768);
+      expect(S16Codec.decodeWave("32767")).toBe(32767);
+
+      expect(() => S16Codec.decodeWave("-32769")).toThrow("s16 out of range");
+      expect(() => S16Codec.decodeWave("32768")).toThrow("s16 out of range");
+    });
+
+    it("s32", () => {
+      expect(S32Codec.decodeWave("-2147483648")).toBe(-2147483648);
+      expect(S32Codec.decodeWave("2147483647")).toBe(2147483647);
+
+      expect(() => S32Codec.decodeWave("-2147483649")).toThrow(
+        "s32 out of range",
+      );
+      expect(() => S32Codec.decodeWave("2147483648")).toThrow(
+        "s32 out of range",
+      );
+    });
+
+    it("s64", () => {
+      expect(S64Codec.decodeWave("-9223372036854775808")).toBe(
+        -9223372036854775808n,
+      );
+      expect(S64Codec.decodeWave("9223372036854775807")).toBe(
+        9223372036854775807n,
+      );
+
+      expect(() => S64Codec.decodeWave("-9223372036854775809")).toThrow(
+        "s64 out of range",
+      );
+      expect(() => S64Codec.decodeWave("9223372036854775808")).toThrow(
+        "s64 out of range",
+      );
+    });
+  });
+
+  it("throws on non-integer literals", () => {
+    expect(() => U32Codec.decodeWave("1.2")).toThrow("invalid integer: u32");
+    expect(() => S16Codec.decodeWave("NaN")).toThrow("invalid integer: s16");
+    expect(() => U64Codec.decodeWave("1e3")).toThrow("invalid integer: u64");
+  });
+
+  it("round-trips", () => {
+    const nums = [0, 1, 255, 65535, 12345];
+    for (const n of nums) {
+      expect(U16Codec.decodeWave(U16Codec.encodeWave(n))).toBe(n);
+    }
+
+    const bigs = [0n, 1n, 10n, 18446744073709551615n];
+    for (const b of bigs) {
+      expect(U64Codec.decodeWave(U64Codec.encodeWave(b))).toBe(b);
+    }
+  });
+});

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

@@ -0,0 +1,304 @@
+// numerics.ts
+import { stripOuter, splitTopLevelComma, splitTopLevelColon } from "./util.js";
+import type { Codec } from "./types.js";
+
+type Decimal = [bigint, number];
+
+const TARGET_SCALE = 18;
+
+const U32_MAX = (1n << 32n) - 1n;
+const U64_MAX = (1n << 64n) - 1n;
+
+/* -------------------------------------------------------------------------- */
+/* Utils                                                                      */
+/* -------------------------------------------------------------------------- */
+
+function assertU32(x: bigint, ctx: string): bigint {
+  if (x < 0n || x > U32_MAX) {
+    throw new Error(`${ctx} must be a u32`);
+  }
+  return x;
+}
+
+function assertU64(x: bigint, ctx: string): bigint {
+  if (x < 0n || x > U64_MAX) {
+    throw new Error(`${ctx} must be a u64`);
+  }
+  return x;
+}
+
+function parseBigIntLiteral(expr: string, ctx: string): bigint {
+  const normalized = expr.trim().replace(/_/g, "");
+  if (!/^[+-]?\d+$/.test(normalized)) {
+    throw new Error(`invalid integer for ${ctx}: "${expr}"`);
+  }
+  return BigInt(normalized);
+}
+
+function parseIntNumberWave(expr: string, ctx: string): number {
+  const s = expr.trim().replace(/_/g, "");
+  if (!/^[+-]?\d+$/.test(s)) throw new Error(`invalid integer: ${ctx}`);
+  const n = Number(s);
+  if (!Number.isFinite(n) || !Number.isInteger(n))
+    throw new Error(`invalid integer: ${ctx}`);
+  return n;
+}
+
+function parseIntBigWave(expr: string, ctx: string): bigint {
+  const s = expr.trim().replace(/_/g, "");
+  if (!/^[+-]?\d+$/.test(s)) throw new Error(`invalid integer: ${ctx}`);
+  return BigInt(s);
+}
+
+function pow10n(n: number): bigint {
+  let p = 1n;
+  for (let i = 0; i < n; i++) p *= 10n;
+  return p;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Fixed-width integer scalars                                                */
+/* -------------------------------------------------------------------------- */
+
+const U8_MIN = 0;
+const U8_MAX_N = 255;
+
+const U16_MIN = 0;
+const U16_MAX_N = 65535;
+
+const U32_MIN = 0;
+const U32_MAX_N = 4294967295;
+
+const S8_MIN = -128;
+const S8_MAX_N = 127;
+
+const S16_MIN = -32768;
+const S16_MAX_N = 32767;
+
+const S32_MIN = -2147483648;
+const S32_MAX_N = 2147483647;
+
+const U64_MAX_B = (1n << 64n) - 1n;
+const S64_MIN_B = -(1n << 63n);
+const S64_MAX_B = (1n << 63n) - 1n;
+
+function makeNumberIntCodec(
+  name: string,
+  min: number,
+  max: number,
+): Codec<number> {
+  return {
+    decodeWave(expr: string): number {
+      const n = parseIntNumberWave(expr, name);
+      if (n < min || n > max) throw new Error(`${name} out of range`);
+      return n;
+    },
+    encodeWave(value: number): string {
+      if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new Error(`${name} out of range`);
+      }
+      if (value < min || value > max) throw new Error(`${name} out of range`);
+      return String(value);
+    },
+  };
+}
+
+function makeBigIntCodec(
+  name: string,
+  min: bigint,
+  max: bigint,
+): Codec<bigint> {
+  return {
+    decodeWave(expr: string): bigint {
+      const n = parseIntBigWave(expr, name);
+      if (n < min || n > max) throw new Error(`${name} out of range`);
+      return n;
+    },
+    encodeWave(value: bigint): string {
+      if (value < min || value > max) throw new Error(`${name} out of range`);
+      return value.toString(10);
+    },
+  };
+}
+
+// Unsigned
+export const U8Codec = makeNumberIntCodec("u8", U8_MIN, U8_MAX_N);
+export const U16Codec = makeNumberIntCodec("u16", U16_MIN, U16_MAX_N);
+export const U32Codec = makeNumberIntCodec("u32", U32_MIN, U32_MAX_N);
+export const U64Codec = makeBigIntCodec("u64", 0n, U64_MAX_B);
+
+// Signed
+export const S8Codec = makeNumberIntCodec("s8", S8_MIN, S8_MAX_N);
+export const S16Codec = makeNumberIntCodec("s16", S16_MIN, S16_MAX_N);
+export const S32Codec = makeNumberIntCodec("s32", S32_MIN, S32_MAX_N);
+export const S64Codec = makeBigIntCodec("s64", S64_MIN_B, S64_MAX_B);
+
+/* -------------------------------------------------------------------------- */
+/* Integer (struct limbs)                                                     */
+/* -------------------------------------------------------------------------- */
+
+type IntegerWave = {
+  r0: bigint;
+  r1: bigint;
+  r2: bigint;
+  r3: bigint;
+  sign: "plus" | "minus";
+};
+
+function parseIntegerWave(expr: string): IntegerWave {
+  const { inner } = stripOuter(expr, "{", "}");
+  if (!inner) throw new Error("empty integer expression");
+
+  const parts = splitTopLevelComma(inner);
+  const seen = new Set<string>();
+
+  const out: Partial<IntegerWave> = { r1: 0n, r2: 0n, r3: 0n };
+
+  for (const part of parts) {
+    const [k, v] = splitTopLevelColon(part);
+    if (seen.has(k)) throw new Error(`duplicate key "${k}"`);
+    seen.add(k);
+
+    switch (k) {
+      case "r0":
+      case "r1":
+      case "r2":
+      case "r3":
+        (out as any)[k] = assertU32(parseBigIntLiteral(v, k), k);
+        break;
+      case "sign":
+        if (v !== "plus" && v !== "minus") {
+          throw new Error(`invalid sign "${v}"`);
+        }
+        out.sign = v;
+        break;
+      default:
+        throw new Error(`unexpected key "${k}"`);
+    }
+  }
+
+  if (out.r0 === undefined) throw new Error(`missing required key "r0"`);
+  if (!out.sign) throw new Error(`missing required key "sign"`);
+
+  return out as IntegerWave;
+}
+
+function integerWaveToJs(w: IntegerWave): bigint {
+  const value = (w.r3 << 96n) | (w.r2 << 64n) | (w.r1 << 32n) | w.r0;
+  return w.sign === "minus" ? -value : value;
+}
+
+function integerJsToWave(v: bigint): IntegerWave {
+  const sign = v < 0n ? "minus" : "plus";
+  const abs = v < 0n ? -v : v;
+
+  return {
+    r0: abs & U32_MAX,
+    r1: (abs >> 32n) & U32_MAX,
+    r2: (abs >> 64n) & U32_MAX,
+    r3: (abs >> 96n) & U32_MAX,
+    sign,
+  };
+}
+
+export const IntegerCodec: Codec<bigint> = {
+  decodeWave(expr: string) {
+    return integerWaveToJs(parseIntegerWave(expr));
+  },
+
+  encodeWave(value: bigint) {
+    const w = integerJsToWave(value);
+    return `{r0: ${w.r0}, r1: ${w.r1}, r2: ${w.r2}, r3: ${w.r3}, sign: ${w.sign}}`;
+  },
+};
+
+/* -------------------------------------------------------------------------- */
+/* Decimal (struct limbs)                                                     */
+/* -------------------------------------------------------------------------- */
+
+type DecimalWave = {
+  r0: bigint;
+  r1: bigint;
+  r2: bigint;
+  r3: bigint;
+  sign: "plus" | "minus";
+};
+
+function parseDecimalWave(expr: string): DecimalWave {
+  const { inner } = stripOuter(expr, "{", "}");
+  if (!inner) throw new Error("empty decimal expression");
+
+  const parts = splitTopLevelComma(inner);
+  const seen = new Set<string>();
+
+  const out: Partial<DecimalWave> = { r1: 0n, r2: 0n, r3: 0n };
+
+  for (const part of parts) {
+    const [k, v] = splitTopLevelColon(part);
+    if (seen.has(k)) throw new Error(`duplicate key "${k}"`);
+    seen.add(k);
+
+    switch (k) {
+      case "r0":
+      case "r1":
+      case "r2":
+      case "r3":
+        (out as any)[k] = assertU64(parseBigIntLiteral(v, k), k);
+        break;
+      case "sign":
+        if (v !== "plus" && v !== "minus") {
+          throw new Error(`invalid sign "${v}"`);
+        }
+        out.sign = v;
+        break;
+      default:
+        throw new Error(`unexpected key "${k}"`);
+    }
+  }
+
+  if (out.r0 === undefined) throw new Error(`missing required key "r0"`);
+  if (!out.sign) throw new Error(`missing required key "sign"`);
+
+  return out as DecimalWave;
+}
+
+function decimalWaveToJs(w: DecimalWave): Decimal {
+  const mag = (w.r3 << 192n) | (w.r2 << 128n) | (w.r1 << 64n) | w.r0;
+
+  const signed = w.sign === "minus" ? -mag : mag;
+  return [signed, TARGET_SCALE];
+}
+
+function decimalJsToWave([coef, scale]: Decimal): DecimalWave {
+  if (scale > TARGET_SCALE) {
+    throw new Error(
+      `cannot downscale decimal from ${scale} to ${TARGET_SCALE}`,
+    );
+  }
+
+  const sign = coef < 0n ? "minus" : "plus";
+  const abs = coef < 0n ? -coef : coef;
+  const scaled = abs * pow10n(TARGET_SCALE - scale);
+
+  const r0 = scaled & U64_MAX;
+  const r1 = (scaled >> 64n) & U64_MAX;
+  const r2 = (scaled >> 128n) & U64_MAX;
+  const r3 = (scaled >> 192n) & U64_MAX;
+
+  if (scaled >> 256n !== 0n) {
+    throw new Error("decimal magnitude does not fit in 256 bits");
+  }
+
+  return { r0, r1, r2, r3, sign };
+}
+
+export const DecimalCodec: Codec<Decimal> = {
+  decodeWave(expr: string) {
+    return decimalWaveToJs(parseDecimalWave(expr));
+  },
+
+  encodeWave(value: Decimal) {
+    const w = decimalJsToWave(value);
+    return `{r0: ${w.r0}, r1: ${w.r1}, r2: ${w.r2}, r3: ${w.r3}, sign: ${w.sign}}`;
+  },
+};