@sig-net/midnight-serde 0.12.0

package/README.md

@@ -0,0 +1,106 @@
+# @sig-net/midnight-serde
+
+TypeScript twin of Compact's builtin `serialize<T, N>` / `deserialize<T, N>`
+pair (CompactStandardLibrary). Produce bytes off-chain that a contract reads
+with one `deserialize<T, N>` call, and decode bytes a contract produced with
+`serialize<T, N>`. Zero runtime dependencies.
+
+Every claim is pinned byte-for-byte against COMPILED circuits: the fixture
+contract in [`tests/fixtures/serde-fixtures.compact`](tests/fixtures/serde-fixtures.compact)
+wraps the builtins over structs exercising all supported types and combos, and
+the tests assert twin/circuit equality in both directions. A second,
+independent oracle backs the serialize direction: `toBinaryRepr` from
+`@midnight-ntwrk/compact-runtime` (test-only, never a runtime dependency)
+must agree with the twin on every shape, including the shapes compactc cannot
+compile `serialize<T, N>` for.
+
+## Use
+
+Describe the Compact type as a descriptor tree, then encode/decode values.
+Declare descriptors `as const satisfies CompactType` and the value types are
+INFERRED from the descriptor (`CompactValueOf<T>`), both in and out, so no
+casts and no hand-written interfaces:
+
+```ts
+import { compactSerialize, compactDeserialize, type CompactType } from "@sig-net/midnight-serde";
+
+// Compact: struct Result { ok: Boolean; amount: Uint<128>; }
+const RESULT = {
+  kind: "struct",
+  fields: [
+    { name: "ok", type: { kind: "boolean" } },
+    { name: "amount", type: { kind: "uint", bits: 128 } },
+  ],
+} as const satisfies CompactType;
+
+// serialize<Result, 128> twin: packed value at the start, zero-padded to 128.
+// The value parameter is compile-time checked against the descriptor.
+const bytes = compactSerialize(RESULT, { ok: true, amount: 4242n }, 128);
+
+// deserialize<Result, 128> twin.
+const value = compactDeserialize(RESULT, bytes);
+//    ^? { ok: boolean; amount: bigint }
+```
+
+A descriptor widened to `CompactType` still works and degrades to the loose
+`CompactValue` union.
+
+## Types and layout
+
+Fields and elements pack in declaration order, little-endian, natural widths,
+no gaps, no length prefixes. Every serializable Compact type has a descriptor
+kind (`Opaque<...>` is the one exclusion: compactc itself rejects it as "not
+a serializable type"):
+
+| Compact type | Descriptor | Packed width | Value type |
+| --- | --- | --- | --- |
+| `Boolean` | `{ kind: 'boolean' }` | 1 byte (0x00/0x01) | `boolean` |
+| `Uint<w>` (sized) | `{ kind: 'uint', bits: w }` | ceil(w / 8), w at most 248 | `bigint` |
+| `Uint<0..n>` (bounded) | `{ kind: 'uint', bound: n }` | byte length of n - 1 | `bigint` |
+| `Field` | `{ kind: 'field' }` | 32 bytes, value below the Fr modulus | `bigint` |
+| `Bytes<n>` | `{ kind: 'bytes', length: n }` | n, raw | `Uint8Array` |
+| enum | `{ kind: 'enum', variants: k }` | byte length of k - 1 | `number` (index) |
+| `Vector<n, T>` | `{ kind: 'vector', length: n, element }` | n elements, unprefixed | `T[]` |
+| `[T1, ..., Tn]` (tuple) | `{ kind: 'tuple', elements }` | elements back to back | TS tuple |
+| struct | `{ kind: 'struct', fields }` | fields back to back | plain object |
+
+The `Uint<0..n>` upper bound is EXCLUSIVE, per the language reference: the
+values are 0 to n - 1, so `Uint<0..1000>` is 2 bytes and `Uint<8>` is the same
+type as `Uint<0..256>`. An enum is `Uint<0..variants>` under the hood. That
+width rule makes some legal types ZERO bytes wide: `Uint<0..1>`,
+single-variant enums, `Bytes<0>`, `Vector<0, T>`, the empty tuple and the
+empty struct all occupy no space (circuit-pinned).
+
+`serialize<T, N>` places the packed value at the start of `Bytes<N>` and
+zero-pads on the right. N below the packed size is a compile error in Compact
+and a thrown error here.
+
+## Divergences from the circuit
+
+Both are strict-by-default on DECODE, and both are pinned by tests. Bytes a
+circuit produced never trigger either one, since `serialize<T, N>` only ever
+writes zero padding and 0x00/0x01 booleans:
+
+- **Padding:** the circuit ignores bytes in the padding region entirely, the
+  twin rejects non-zero padding. Pass `{ ignorePadding: true }` to
+  `compactDeserialize` to mirror the circuit exactly.
+- **Booleans:** the circuit decodes ANY byte other than 0x01 as `false`
+  (0x02..0xff included), the twin rejects bytes above 1.
+
+Everything else mirrors the circuit exactly, including rejections:
+out-of-range bounded Uint, enum and Field encodings throw in-circuit and
+throw here (all pinned by the tests).
+
+Known compactc 0.33 limits (pinned by the tests): `serialize<T, N>` crashes
+the COMPILER on vectors of structs, vectors of vectors, and struct nesting
+deeper than one level. `deserialize<T, N>` handles all of those, so contracts
+can still READ such payloads from off-chain encoders. Tuples are unaffected:
+`serialize<[Pair, Boolean], N>` compiles fine.
+
+## Develop
+
+```bash
+yarn compile   # compile the fixture contract (needed before test/build)
+yarn test      # pin the twin against the compiled circuits + toBinaryRepr
+yarn build     # typecheck + emit ./dist for publishing
+```

package/dist/deserialize.d.ts

@@ -0,0 +1,13 @@
+import type { CompactType, CompactValueOf } from './types.ts';
+export interface CompactDeserializeOptions {
+    /** Skip the all-zero check on bytes after the packed value (circuit behaviour). */
+    ignorePadding?: boolean;
+}
+/**
+ * Inverse of `compactSerialize`: decode the packed prefix of `bytes`.
+ *
+ * The return type is derived from the descriptor (see `CompactValueOf`), so a
+ * literal descriptor yields a fully typed value with no cast at the call site.
+ */
+export declare function compactDeserialize<const T extends CompactType>(type: T, bytes: Uint8Array, options?: CompactDeserializeOptions): CompactValueOf<T>;
+//# sourceMappingURL=deserialize.d.ts.map

package/dist/deserialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialize.d.ts","sourceRoot":"","sources":["../src/deserialize.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAgB,cAAc,EAAE,MAAM,YAAY,CAAC;AAI5E,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,WAAW,EAC5D,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,yBAA8B,GACtC,cAAc,CAAC,CAAC,CAAC,CAiBnB"}

package/dist/deserialize.js

@@ -0,0 +1,140 @@
+// Byte-exact twin of Compact's builtin `deserialize<T, N>` from
+// CompactStandardLibrary, pinned against compiled circuits by tests/.
+//
+// Two deliberate divergences from the circuit, both strict-by-default
+// (garbage in a buffer means corruption or mis-framing, and failing loudly
+// off-chain is the safer default):
+//   - PADDING: the circuit IGNORES bytes in the padding region entirely
+//     (pinned by tests), while this decoder rejects non-zero padding. Pass
+//     `{ ignorePadding: true }` to mirror the circuit.
+//   - BOOLEANS: the circuit decodes ANY byte other than 0x01 as false, so
+//     0x02..0xff all quietly become false (pinned by tests), while this
+//     decoder rejects bytes above 1.
+// Circuit-produced bytes never trigger either divergence: `serialize<T, N>`
+// only writes zero padding and 0x00/0x01 booleans.
+//
+// Everything else mirrors the circuit exactly, including its rejections: the
+// descriptor is fully validated (src/validate.ts) and the input buffer
+// type-checked before any decoding, and out-of-range Uint, enum and Field
+// encodings all throw exactly where the circuit throws (pinned by tests).
+import { FIELD_MODULUS } from "./types.js";
+import { packedSize, uintBound, uintName } from "./serialize.js";
+import { assertCompactType, assertUnreachable } from "./validate.js";
+/**
+ * Inverse of `compactSerialize`: decode the packed prefix of `bytes`.
+ *
+ * The return type is derived from the descriptor (see `CompactValueOf`), so a
+ * literal descriptor yields a fully typed value with no cast at the call site.
+ */
+export function compactDeserialize(type, bytes, options = {}) {
+    assertCompactType(type);
+    if (!(bytes instanceof Uint8Array)) {
+        throw new Error('bytes must be a Uint8Array');
+    }
+    const [value, consumed] = decodeFrom(bytes, 0, type, 'value');
+    if (!options.ignorePadding) {
+        for (let i = consumed; i < bytes.length; i++) {
+            if (bytes[i] !== 0) {
+                throw new Error(`non-zero padding byte 0x${bytes[i].toString(16)} at offset ${i} ` +
+                    `(pass ignorePadding to mirror the circuit, which reads only the packed prefix)`);
+            }
+        }
+    }
+    return value;
+}
+function decodeFrom(bytes, offset, type, label) {
+    const need = packedSize(type);
+    if (offset + need > bytes.length) {
+        throw new Error(`${label}: needs ${need} bytes at offset ${offset}, buffer has ${bytes.length}`);
+    }
+    switch (type.kind) {
+        case 'boolean': {
+            const b = bytes[offset];
+            // Stricter than the circuit, which decodes any byte != 0x01 as false
+            // (see the header comment).
+            if (b > 1)
+                throw new Error(`${label}: invalid boolean byte 0x${b.toString(16)}`);
+            return [b === 1, offset + 1];
+        }
+        case 'uint': {
+            const bound = uintBound(type);
+            const size = packedSize(type);
+            const value = readUintLE(bytes, offset, size);
+            // Mirrors the circuit, which rejects encodings at or above the bound
+            // (pinned by tests via the bounded fixture; only reachable for sized
+            // uints when the width is not byte-aligned).
+            if (value >= bound) {
+                throw new Error(`${label}: encoding ${value} exceeds ${uintName(type)}`);
+            }
+            return [value, offset + size];
+        }
+        case 'field': {
+            const value = readUintLE(bytes, offset, 32);
+            // The circuit rejects out-of-range Field encodings at runtime too
+            // (pinned by tests): mirror it.
+            if (value >= FIELD_MODULUS) {
+                throw new Error(`${label}: encoding ${value} is not below the Field modulus`);
+            }
+            return [value, offset + 32];
+        }
+        case 'bytes':
+            return [bytes.slice(offset, offset + type.length), offset + type.length];
+        case 'enum': {
+            const size = packedSize(type);
+            const value = readUintLE(bytes, offset, size);
+            // Mirrors the circuit's variant-index range check (pinned by tests).
+            if (value >= BigInt(type.variants)) {
+                throw new Error(`${label}: encoding ${value} exceeds the last variant index ${type.variants - 1}`);
+            }
+            return [Number(value), offset + size];
+        }
+        case 'vector': {
+            const elements = [];
+            let cursor = offset;
+            for (let i = 0; i < type.length; i++) {
+                const [element, next] = decodeFrom(bytes, cursor, type.element, `${label}[${i}]`);
+                elements.push(element);
+                cursor = next;
+            }
+            return [elements, cursor];
+        }
+        case 'tuple': {
+            const elements = [];
+            let cursor = offset;
+            type.elements.forEach((element, i) => {
+                const [decoded, next] = decodeFrom(bytes, cursor, element, `${label}[${i}]`);
+                elements.push(decoded);
+                cursor = next;
+            });
+            return [elements, cursor];
+        }
+        case 'struct': {
+            const value = {};
+            let cursor = offset;
+            for (const field of type.fields) {
+                const [fieldValue, next] = decodeFrom(bytes, cursor, field.type, `${label}.${field.name}`);
+                // defineProperty, not assignment: a field named '__proto__' is a
+                // legal Compact identifier, and plain assignment would hit the
+                // prototype setter and silently drop it.
+                Object.defineProperty(value, field.name, {
+                    value: fieldValue,
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+                cursor = next;
+            }
+            return [value, cursor];
+        }
+        default:
+            return assertUnreachable(type, label);
+    }
+}
+function readUintLE(bytes, offset, size) {
+    let v = 0n;
+    for (let i = size - 1; i >= 0; i--) {
+        v = (v << 8n) | BigInt(bytes[offset + i]);
+    }
+    return v;
+}
+//# sourceMappingURL=deserialize.js.map

package/dist/deserialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialize.js","sourceRoot":"","sources":["../src/deserialize.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { FIELD_MODULUS, MAX_UINT_BITS, MAX_UINT_BOUND, type CompactBooleanType, type CompactUintType, type CompactSizedUintType, type CompactBoundedUintType, type CompactFieldType, type CompactBytesType, type CompactEnumType, type CompactVectorType, type CompactTupleType, type CompactStructType, type CompactType, type CompactValue, type CompactValueOf, } from './types.ts';
+export { compactSerialize, compactSerializedSize } from './serialize.ts';
+export { assertCompactType, isCompactType } from './validate.ts';
+export { compactDeserialize, type CompactDeserializeOptions, } from './deserialize.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { FIELD_MODULUS, MAX_UINT_BITS, MAX_UINT_BOUND, } from "./types.js";
+export { compactSerialize, compactSerializedSize } from "./serialize.js";
+export { assertCompactType, isCompactType } from "./validate.js";
+export { compactDeserialize, } from "./deserialize.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,GAcf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,kBAAkB,GAEnB,MAAM,kBAAkB,CAAC"}

package/dist/serialize.d.ts

@@ -0,0 +1,22 @@
+import type { CompactType, CompactUintType, CompactValueOf } from './types.ts';
+/** The EXCLUSIVE upper bound of a uint descriptor, whichever form it uses. */
+export declare function uintBound(type: CompactUintType): bigint;
+/**
+ * Packed byte size of an ALREADY-VALIDATED descriptor. Package-internal: the
+ * public {@link compactSerializedSize} validates first.
+ */
+export declare function packedSize(type: CompactType): number;
+/** Packed byte size of a type, before `serialize<T, N>`'s right zero-padding. */
+export declare function compactSerializedSize(type: CompactType): number;
+/**
+ * Byte-exact twin of `serialize<T, padTo>(value)`. With `padTo` omitted the
+ * packed value is returned unpadded, matching `serialize<T, packedSize>`.
+ *
+ * The value parameter is typed from the descriptor (see `CompactValueOf`), so
+ * a literal descriptor gets compile-time checking of the value shape, and the
+ * same shape is enforced again at runtime.
+ */
+export declare function compactSerialize<const T extends CompactType>(type: T, value: CompactValueOf<T>, padTo?: number): Uint8Array;
+/** Display name of a uint descriptor in its own declaration form. */
+export declare function uintName(type: CompactUintType): string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAgB,cAAc,EAAE,MAAM,YAAY,CAAC;AAc7F,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAIvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAqBpD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAG/D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,CAAC,SAAS,WAAW,EAC1D,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACxB,KAAK,CAAC,EAAE,MAAM,GACb,UAAU,CAeZ;AA8GD,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAItD"}

package/dist/serialize.js

@@ -0,0 +1,206 @@
+// Byte-exact twin of Compact's builtin `serialize<T, N>` from
+// CompactStandardLibrary, pinned against compiled circuits by tests/.
+//
+// Layout rules (compactc 0.33 / language 0.25):
+//   - struct fields and tuple elements are packed in declaration order, no
+//     alignment gaps
+//   - every value is little-endian at its NATURAL width (see src/types.ts);
+//     bounded uints and enums are as wide as their largest legal value, which
+//     makes `Uint<0..1>` and single-variant enums ZERO bytes wide
+//   - `serialize<T, N>` places the packed value at the START of `Bytes<N>` and
+//     zero-pads on the right; N below the packed size is a compile error, and
+//     this module throws on the same condition.
+//
+// Compact is a strict protocol, so this module is too: every public entry
+// point runs the full recursive descriptor validation (src/validate.ts)
+// before touching a byte, every value is range- and shape-checked at runtime,
+// and every switch has a throwing backstop for anything that slips past the
+// type system.
+import { FIELD_MODULUS } from "./types.js";
+import { assertCompactType, assertUnreachable } from "./validate.js";
+/** Byte length of the largest legal value, given the EXCLUSIVE bound. 0 for a bound of 1. */
+function widthOfBound(bound) {
+    let max = bound - 1n;
+    let width = 0;
+    while (max > 0n) {
+        width++;
+        max >>= 8n;
+    }
+    return width;
+}
+/** The EXCLUSIVE upper bound of a uint descriptor, whichever form it uses. */
+export function uintBound(type) {
+    return 'bits' in type && type.bits !== undefined
+        ? 1n << BigInt(type.bits)
+        : BigInt(type.bound);
+}
+/**
+ * Packed byte size of an ALREADY-VALIDATED descriptor. Package-internal: the
+ * public {@link compactSerializedSize} validates first.
+ */
+export function packedSize(type) {
+    switch (type.kind) {
+        case 'boolean':
+            return 1;
+        case 'uint':
+            return widthOfBound(uintBound(type));
+        case 'field':
+            return 32;
+        case 'bytes':
+            return type.length;
+        case 'enum':
+            return widthOfBound(BigInt(type.variants));
+        case 'vector':
+            return type.length * packedSize(type.element);
+        case 'tuple':
+            return type.elements.reduce((sum, e) => sum + packedSize(e), 0);
+        case 'struct':
+            return type.fields.reduce((sum, f) => sum + packedSize(f.type), 0);
+        default:
+            return assertUnreachable(type, 'packedSize');
+    }
+}
+/** Packed byte size of a type, before `serialize<T, N>`'s right zero-padding. */
+export function compactSerializedSize(type) {
+    assertCompactType(type);
+    return packedSize(type);
+}
+/**
+ * Byte-exact twin of `serialize<T, padTo>(value)`. With `padTo` omitted the
+ * packed value is returned unpadded, matching `serialize<T, packedSize>`.
+ *
+ * The value parameter is typed from the descriptor (see `CompactValueOf`), so
+ * a literal descriptor gets compile-time checking of the value shape, and the
+ * same shape is enforced again at runtime.
+ */
+export function compactSerialize(type, value, padTo) {
+    assertCompactType(type);
+    if (padTo !== undefined && (!Number.isInteger(padTo) || padTo < 0)) {
+        throw new Error(`padTo must be a non-negative integer, got ${String(padTo)}`);
+    }
+    const size = packedSize(type);
+    const total = padTo ?? size;
+    if (total < size) {
+        throw new Error(`padTo ${total} is below the packed size ${size} (a compile error in Compact too)`);
+    }
+    const out = new Uint8Array(total);
+    encodeInto(out, 0, type, value, 'value');
+    return out;
+}
+function encodeInto(out, offset, type, value, label) {
+    switch (type.kind) {
+        case 'boolean': {
+            if (typeof value !== 'boolean')
+                throw new Error(`${label}: expected boolean`);
+            out[offset] = value ? 1 : 0;
+            return offset + 1;
+        }
+        case 'uint': {
+            if (typeof value !== 'bigint')
+                throw new Error(`${label}: expected bigint`);
+            const bound = uintBound(type);
+            const size = widthOfBound(bound);
+            if (value >= bound) {
+                throw new Error(`${label}: value ${value} exceeds ${uintName(type)}`);
+            }
+            writeUintLE(out, offset, value, size, label);
+            return offset + size;
+        }
+        case 'field': {
+            if (typeof value !== 'bigint')
+                throw new Error(`${label}: expected bigint`);
+            if (value >= FIELD_MODULUS) {
+                throw new Error(`${label}: value ${value} is not below the Field modulus`);
+            }
+            writeUintLE(out, offset, value, 32, label);
+            return offset + 32;
+        }
+        case 'bytes': {
+            if (!(value instanceof Uint8Array))
+                throw new Error(`${label}: expected Uint8Array`);
+            if (value.length !== type.length) {
+                throw new Error(`${label}: expected exactly ${type.length} bytes, got ${value.length}`);
+            }
+            out.set(value, offset);
+            return offset + type.length;
+        }
+        case 'enum': {
+            // Matches the generated bindings: enum values are numbers (the index).
+            if (typeof value !== 'number' || !Number.isInteger(value)) {
+                throw new Error(`${label}: expected an integer number (enum variant index)`);
+            }
+            const size = widthOfBound(BigInt(type.variants));
+            if (value < 0 || value >= type.variants) {
+                throw new Error(`${label}: variant index ${value} is outside 0..${type.variants - 1}`);
+            }
+            writeUintLE(out, offset, BigInt(value), size, label);
+            return offset + size;
+        }
+        case 'vector': {
+            if (!Array.isArray(value))
+                throw new Error(`${label}: expected array`);
+            if (value.length !== type.length) {
+                throw new Error(`${label}: expected exactly ${type.length} elements, got ${value.length}`);
+            }
+            let cursor = offset;
+            value.forEach((element, i) => {
+                cursor = encodeInto(out, cursor, type.element, element, `${label}[${i}]`);
+            });
+            return cursor;
+        }
+        case 'tuple': {
+            if (!Array.isArray(value))
+                throw new Error(`${label}: expected array (tuple)`);
+            if (value.length !== type.elements.length) {
+                throw new Error(`${label}: expected exactly ${type.elements.length} elements, got ${value.length}`);
+            }
+            let cursor = offset;
+            type.elements.forEach((element, i) => {
+                cursor = encodeInto(out, cursor, element, value[i], `${label}[${i}]`);
+            });
+            return cursor;
+        }
+        case 'struct': {
+            if (typeof value !== 'object' ||
+                value === null ||
+                Array.isArray(value) ||
+                value instanceof Uint8Array) {
+                throw new Error(`${label}: expected an object`);
+            }
+            let cursor = offset;
+            for (const field of type.fields) {
+                // Own-property lookup: field names like 'toString' or '__proto__'
+                // are legal Compact identifiers and must not resolve through the
+                // JS prototype chain.
+                if (!Object.hasOwn(value, field.name)) {
+                    throw new Error(`${label}: missing field '${field.name}'`);
+                }
+                const fieldValue = value[field.name];
+                cursor = encodeInto(out, cursor, field.type, fieldValue, `${label}.${field.name}`);
+            }
+            return cursor;
+        }
+        default:
+            return assertUnreachable(type, label);
+    }
+}
+/** Display name of a uint descriptor in its own declaration form. */
+export function uintName(type) {
+    return 'bits' in type && type.bits !== undefined
+        ? `Uint<${type.bits}>`
+        : `Uint<0..${type.bound}>`;
+}
+function writeUintLE(out, offset, value, size, label) {
+    if (value < 0n) {
+        throw new Error(`${label}: negative values cannot be Compact-serialized (got ${value})`);
+    }
+    if (value >> BigInt(size * 8) !== 0n) {
+        throw new Error(`${label}: value ${value} does not fit in ${size} bytes`);
+    }
+    let v = value;
+    for (let i = 0; i < size; i++) {
+        out[offset + i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+}
+//# sourceMappingURL=serialize.js.map

package/dist/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The BLS12-381 scalar field modulus. A Compact `Field` value must be below
+ * it. Matches `maxField + 1n` exported by @midnight-ntwrk/compact-runtime.
+ */
+export declare const FIELD_MODULUS = 52435875175126190479447740508185965837690552500527637822603658699938581184513n;
+/** Maximum `Uint` width accepted by compactc 0.33 (bits). */
+export declare const MAX_UINT_BITS = 248;
+/**
+ * Maximum EXCLUSIVE bound of a Compact `Uint<0..n>`: 2^248, i.e. one above
+ * the language reference's maximum Uint value 256^31 - 1.
+ */
+export declare const MAX_UINT_BOUND: bigint;
+/** Compact `Boolean`: 1 byte, 0x00 or 0x01. */
+export interface CompactBooleanType {
+    readonly kind: 'boolean';
+}
+/** Compact `Uint<bits>` (sized): ceil(bits / 8) bytes little-endian, bits 1..248. */
+export interface CompactSizedUintType {
+    readonly kind: 'uint';
+    readonly bits: number;
+}
+/**
+ * Compact `Uint<0..bound>` (bounded): values 0 (inclusive) to `bound`
+ * EXCLUSIVE, per the language reference. Width is the byte length of
+ * `bound - 1`, so `Uint<0..1000>` is 2 bytes and `Uint<0..1>` is ZERO bytes
+ * (both circuit-pinned). A number `bound` must be a safe integer; use a
+ * bigint beyond 2^53.
+ */
+export interface CompactBoundedUintType {
+    readonly kind: 'uint';
+    readonly bound: number | bigint;
+}
+/**
+ * A Compact unsigned integer, in either declaration form. `Uint<w>` is the
+ * same type as `Uint<0..2^w>`, so `{ bits: w }` and `{ bound: 1n << w }`
+ * describe identical layouts and ranges.
+ */
+export type CompactUintType = CompactSizedUintType | CompactBoundedUintType;
+/** Compact `Field`: 32 bytes little-endian, value below {@link FIELD_MODULUS}. */
+export interface CompactFieldType {
+    readonly kind: 'field';
+}
+/** Compact `Bytes<length>`: raw bytes, copied verbatim. `Bytes<0>` is legal. */
+export interface CompactBytesType {
+    readonly kind: 'bytes';
+    readonly length: number;
+}
+/**
+ * A Compact enum: the variant INDEX packed exactly like
+ * `Uint<0..variants>`, i.e. byte length of `variants - 1` (one byte up to
+ * 256 variants, ZERO bytes for a single-variant enum; circuit-pinned).
+ * Values are numbers, matching the generated contract bindings.
+ */
+export interface CompactEnumType {
+    readonly kind: 'enum';
+    readonly variants: number;
+}
+/**
+ * Compact `Vector<length, element>`: elements back to back, no length
+ * prefix. `Vector<0, T>` is legal and zero bytes wide.
+ */
+export interface CompactVectorType {
+    readonly kind: 'vector';
+    readonly length: number;
+    readonly element: CompactType;
+}
+/**
+ * A Compact tuple `[T1, ..., Tn]`: elements packed in order, no gaps, no
+ * prefix, exactly like a struct without field names. `Vector<n, T>` is the
+ * homogeneous special case. Values are TypeScript arrays/tuples, matching
+ * the generated contract bindings. The empty tuple `[]` is legal and zero
+ * bytes wide.
+ */
+export interface CompactTupleType {
+    readonly kind: 'tuple';
+    readonly elements: readonly CompactType[];
+}
+/**
+ * A Compact struct: fields packed in declaration order, no gaps, flattened.
+ * A struct with no fields is legal and zero bytes wide.
+ */
+export interface CompactStructType {
+    readonly kind: 'struct';
+    readonly fields: readonly {
+        readonly name: string;
+        readonly type: CompactType;
+    }[];
+}
+export type CompactType = CompactBooleanType | CompactUintType | CompactFieldType | CompactBytesType | CompactEnumType | CompactVectorType | CompactTupleType | CompactStructType;
+/**
+ * The TypeScript value shapes descriptors map to, matching the generated
+ * contract bindings: `Boolean` is boolean, `Uint`/`Field` are bigint, an
+ * enum is a number (the variant index), `Bytes` is Uint8Array, `Vector` and
+ * tuples are arrays, a struct is a plain object.
+ */
+export type CompactValue = boolean | bigint | number | Uint8Array | CompactValue[] | {
+    [field: string]: CompactValue;
+};
+/**
+ * The precise TypeScript value type of a descriptor. Declare descriptors
+ * `as const satisfies CompactType` (or as a plain literal) and both
+ * `compactSerialize` and `compactDeserialize` type their values exactly:
+ *
+ * ```ts
+ * const RESULT = {
+ *   kind: "struct",
+ *   fields: [
+ *     { name: "ok", type: { kind: "boolean" } },
+ *     { name: "amount", type: { kind: "uint", bits: 128 } },
+ *   ],
+ * } as const satisfies CompactType;
+ *
+ * const value = compactDeserialize(RESULT, bytes);
+ * //    ^? { ok: boolean; amount: bigint }
+ * ```
+ *
+ * A descriptor WIDENED to `CompactType` degrades gracefully to
+ * {@link CompactValue}.
+ */
+/**
+ * Maps a tuple of descriptors to the tuple of their value types. A separate
+ * alias with its own type parameter so the mapped type is homomorphic (an
+ * inline `keyof T['elements']` would map method keys too, not just indices).
+ */
+type CompactTupleValueOf<E extends readonly CompactType[]> = number extends E['length'] ? CompactValue[] : {
+    -readonly [I in keyof E]: CompactValueOf<E[I]>;
+};
+export type CompactValueOf<T extends CompactType> = T extends CompactBooleanType ? boolean : T extends CompactUintType | CompactFieldType ? bigint : T extends CompactEnumType ? number : T extends CompactBytesType ? Uint8Array : T extends CompactVectorType ? CompactValueOf<T['element']>[] : T extends CompactTupleType ? CompactTupleValueOf<T['elements']> : T extends CompactStructType ? {
+    -readonly [F in T['fields'][number] as F['name']]: CompactValueOf<F['type']>;
+} : never;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,22 @@
+// Type descriptors for Compact circuit types, the runtime mirror of what a
+// contract declares at compile time. A descriptor tree fully determines the
+// byte layout of Compact's builtin `serialize<T, N>` / `deserialize<T, N>`
+// pair, so off-chain code can produce or consume the exact bytes a circuit
+// reads or writes.
+//
+// Coverage: every serializable Compact type has a descriptor kind. The only
+// exclusion is `Opaque<...>`, which compactc itself rejects with
+// "Opaque<...> is not a serializable type".
+/**
+ * The BLS12-381 scalar field modulus. A Compact `Field` value must be below
+ * it. Matches `maxField + 1n` exported by @midnight-ntwrk/compact-runtime.
+ */
+export const FIELD_MODULUS = 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001n;
+/** Maximum `Uint` width accepted by compactc 0.33 (bits). */
+export const MAX_UINT_BITS = 248;
+/**
+ * Maximum EXCLUSIVE bound of a Compact `Uint<0..n>`: 2^248, i.e. one above
+ * the language reference's maximum Uint value 256^31 - 1.
+ */
+export const MAX_UINT_BOUND = 1n << 248n;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,mBAAmB;AACnB,EAAE;AACF,4EAA4E;AAC5E,iEAAiE;AACjE,4CAA4C;AAE5C;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,mEAAmE,CAAC;AAEtE,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,IAAI,IAAI,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+import type { CompactType } from './types.ts';
+/**
+ * Assert that `type` is a structurally valid {@link CompactType}, recursively.
+ * Rejects unknown kinds, unexpected extra keys (typo protection), out-of-range
+ * widths and lengths, empty or duplicate struct field names, and any
+ * non-object node. Error messages carry the path to the offending node.
+ */
+export declare function assertCompactType(type: unknown, label?: string): asserts type is CompactType;
+/** Boolean form of {@link assertCompactType}. */
+export declare function isCompactType(type: unknown): type is CompactType;
+/**
+ * Exhaustiveness backstop for descriptor switches. Statically `value` is
+ * `never` (every kind handled); at runtime it still throws on anything that
+ * slipped past validation instead of falling through to undefined behaviour.
+ */
+export declare function assertUnreachable(value: never, label: string): never;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,SAAS,GACb,OAAO,CAAC,IAAI,IAAI,WAAW,CA8H7B;AAED,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,WAAW,CAOhE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAGpE"}

package/dist/validate.js

@@ -0,0 +1,155 @@
+// Strict runtime validation of CompactType descriptors. TypeScript checks
+// descriptors at compile time, but descriptors can also arrive from plain JS,
+// JSON, or casts, and Compact is a strict protocol: a malformed descriptor
+// must throw immediately with a path to the offending node, never produce
+// bytes. Every public entry point of this package validates its descriptor
+// through here before doing any work.
+import { MAX_UINT_BITS, MAX_UINT_BOUND } from "./types.js";
+/** The exact keys allowed on each descriptor kind: extra keys are rejected. */
+const KIND_KEYS = {
+    boolean: ['kind'],
+    uint: ['kind', 'bits', 'bound'],
+    field: ['kind'],
+    bytes: ['kind', 'length'],
+    enum: ['kind', 'variants'],
+    vector: ['kind', 'length', 'element'],
+    tuple: ['kind', 'elements'],
+    struct: ['kind', 'fields'],
+};
+function assertNonNegativeInteger(value, label) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative integer, got ${String(value)}`);
+    }
+}
+/**
+ * Assert that `type` is a structurally valid {@link CompactType}, recursively.
+ * Rejects unknown kinds, unexpected extra keys (typo protection), out-of-range
+ * widths and lengths, empty or duplicate struct field names, and any
+ * non-object node. Error messages carry the path to the offending node.
+ */
+export function assertCompactType(type, label = 'type') {
+    if (typeof type !== 'object' || type === null || Array.isArray(type)) {
+        throw new Error(`${label}: descriptor must be a plain object`);
+    }
+    const record = type;
+    const kind = record.kind;
+    // Object.hasOwn, not `in`: `in` walks the prototype chain, so kinds like
+    // 'toString' would slip past and die later with a confusing TypeError.
+    if (typeof kind !== 'string' || !Object.hasOwn(KIND_KEYS, kind)) {
+        throw new Error(`${label}: unknown descriptor kind ${JSON.stringify(kind)} ` +
+            `(expected 'boolean' | 'uint' | 'field' | 'bytes' | 'enum' | 'vector' | 'tuple' | 'struct')`);
+    }
+    for (const key of Object.keys(record)) {
+        if (!KIND_KEYS[kind].includes(key)) {
+            throw new Error(`${label}: unexpected key '${key}' on a '${kind}' descriptor`);
+        }
+    }
+    switch (kind) {
+        case 'boolean':
+        case 'field':
+            return;
+        case 'uint': {
+            const hasBits = record.bits !== undefined;
+            const hasBound = record.bound !== undefined;
+            if (hasBits === hasBound) {
+                throw new Error(`${label}: a uint descriptor needs exactly one of 'bits' (sized Uint<w>) ` +
+                    `or 'bound' (bounded Uint<0..n>)`);
+            }
+            if (hasBits) {
+                const bits = record.bits;
+                if (typeof bits !== 'number' ||
+                    !Number.isInteger(bits) ||
+                    bits < 1 ||
+                    bits > MAX_UINT_BITS) {
+                    throw new Error(`${label}: uint bits must be an integer in 1..${MAX_UINT_BITS}, got ${String(bits)}`);
+                }
+                return;
+            }
+            const bound = record.bound;
+            if (typeof bound === 'number' && !Number.isSafeInteger(bound)) {
+                throw new Error(`${label}: a number uint bound must be a safe integer (use a bigint ` +
+                    `beyond 2^53), got ${String(bound)}`);
+            }
+            if (typeof bound !== 'number' && typeof bound !== 'bigint') {
+                throw new Error(`${label}: uint bound must be a number or bigint, got ${String(bound)}`);
+            }
+            if (BigInt(bound) < 1n || BigInt(bound) > MAX_UINT_BOUND) {
+                throw new Error(`${label}: uint bound must be in 1..2^248 (the bound is EXCLUSIVE, ` +
+                    `matching Uint<0..n>), got ${String(bound)}`);
+            }
+            return;
+        }
+        case 'bytes':
+            assertNonNegativeInteger(record.length, `${label}: bytes length`);
+            return;
+        case 'enum': {
+            const variants = record.variants;
+            if (typeof variants !== 'number' || !Number.isSafeInteger(variants) || variants < 1) {
+                throw new Error(`${label}: enum variants must be a positive integer, got ${String(variants)}`);
+            }
+            return;
+        }
+        case 'vector':
+            assertNonNegativeInteger(record.length, `${label}: vector length`);
+            assertCompactType(record.element, `${label}.element`);
+            return;
+        case 'tuple': {
+            const elements = record.elements;
+            if (!Array.isArray(elements)) {
+                throw new Error(`${label}: tuple elements must be an array`);
+            }
+            elements.forEach((element, i) => {
+                assertCompactType(element, `${label}.elements[${i}]`);
+            });
+            return;
+        }
+        case 'struct': {
+            const fields = record.fields;
+            if (!Array.isArray(fields)) {
+                throw new Error(`${label}: struct fields must be an array`);
+            }
+            const seen = new Set();
+            fields.forEach((field, i) => {
+                const fieldLabel = `${label}.fields[${i}]`;
+                if (typeof field !== 'object' || field === null || Array.isArray(field)) {
+                    throw new Error(`${fieldLabel}: field must be a plain object`);
+                }
+                const fieldRecord = field;
+                for (const key of Object.keys(fieldRecord)) {
+                    if (key !== 'name' && key !== 'type') {
+                        throw new Error(`${fieldLabel}: unexpected key '${key}' on a struct field`);
+                    }
+                }
+                if (typeof fieldRecord.name !== 'string' || fieldRecord.name.length === 0) {
+                    throw new Error(`${fieldLabel}: field name must be a non-empty string`);
+                }
+                if (seen.has(fieldRecord.name)) {
+                    throw new Error(`${fieldLabel}: duplicate field name '${fieldRecord.name}'`);
+                }
+                seen.add(fieldRecord.name);
+                assertCompactType(fieldRecord.type, `${fieldLabel}.type`);
+            });
+            return;
+        }
+    }
+}
+/** Boolean form of {@link assertCompactType}. */
+export function isCompactType(type) {
+    try {
+        assertCompactType(type);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Exhaustiveness backstop for descriptor switches. Statically `value` is
+ * `never` (every kind handled); at runtime it still throws on anything that
+ * slipped past validation instead of falling through to undefined behaviour.
+ */
+export function assertUnreachable(value, label) {
+    const kind = value?.kind;
+    throw new Error(`${label}: unhandled descriptor kind ${JSON.stringify(kind)}`);
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sig-net/midnight-serde",
+  "version": "0.12.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sig-net/midnight-integration",
+    "directory": "packages/midnight-serde"
+  },
+  "type": "module",
+  "description": "TypeScript twin of Compact's builtin serialize<T, N> / deserialize<T, N> byte layout, pinned byte-for-byte against compiled circuits.",
+  "//exports": "Local dev consumes raw TS source. `publishConfig.exports` below swaps this to the emitted ./dist at publish time, so npm consumers get JS + .d.ts while the monorepo keeps resolving to src.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "compile": "compact compile --skip-zk --feature-zkir-v3 tests/fixtures/serde-fixtures.compact tests/fixtures/managed",
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.build.json",
+    "prepack": "yarn build",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "devDependencies": {
+    "@midnight-ntwrk/compact-runtime": "0.18.0-rc.1",
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}