@sig-net/midnight 0.19.0 → 0.20.0-rc.1

package/dist/byte-codecs.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Render bytes as a lowercase hex string, no `0x` prefix.
+ *
+ * @param bytes - The bytes to render.
+ * @returns Lowercase hex, two chars per byte.
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Strip an optional `0x`/`0X` prefix from a hex string.
+ *
+ * @param hex - A hex string, with or without a `0x` prefix.
+ * @returns The bare hex digits.
+ */
+export declare function stripHexPrefix(hex: string): string;
+/**
+ * Decode a hex string into bytes: the inverse of {@link bytesToHex}.
+ *
+ * @param hex - An even number of hex digits, with or without a `0x` prefix.
+ * @returns The decoded bytes.
+ * @throws {Error} If the digits are odd-length or not all hex: lenient parsing
+ *   would return plausible-looking wrong bytes.
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+/** BLS12-381 scalar field order (the Compact `Field` type modulus). */
+export declare const BLS_ORDER = 52435875175126190479447740508185965837690552500527637822603658699938581184513n;
+/**
+ * Little-endian bytes to a bigint: the byte order Compact's
+ * `Bytes<32> as Field` / `as Secp256k1Scalar` casts read.
+ *
+ * @param bytes - Little-endian byte array.
+ * @returns The decoded non-negative integer.
+ */
+export declare function bytesToBigint(bytes: Uint8Array): bigint;
+/**
+ * A bigint to exactly 32 little-endian bytes: the inverse of
+ * {@link bytesToBigint}. Non-negative values encode raw (the full 32-byte
+ * range, so secp256k1 scalars above {@link BLS_ORDER} fit). Negative values
+ * are interpreted in the BLS scalar field, so their domain is
+ * `[-BLS_ORDER, 0)`.
+ *
+ * @param n - The integer to encode.
+ * @returns The 32-byte little-endian encoding.
+ * @throws {Error} If the value is below `-BLS_ORDER` or does not fit 32 bytes.
+ */
+export declare function bigintToBytes32(n: bigint): Uint8Array;
+/**
+ * Big-endian (SEC1) bytes to a bigint: the byte order stored signatures use.
+ *
+ * @param bytes - Big-endian byte array.
+ * @returns The decoded non-negative integer.
+ */
+export declare function bytesToBigintBE(bytes: Uint8Array): bigint;
+/**
+ * A bigint to exactly 32 big-endian (SEC1) bytes: the inverse of
+ * {@link bytesToBigintBE}.
+ *
+ * @param value - The non-negative integer to encode.
+ * @returns The 32-byte big-endian encoding.
+ * @throws {Error} If the value is negative or does not fit 32 bytes.
+ */
+export declare function bigintToBytes32BE(value: bigint): Uint8Array;
+//# sourceMappingURL=byte-codecs.d.ts.map

package/dist/byte-codecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-codecs.d.ts","sourceRoot":"","sources":["../src/byte-codecs.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAUlD;AAED,uEAAuE;AACvE,eAAO,MAAM,SAAS,iFAC0D,CAAC;AAEjF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAQvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAWrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMzD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAW3D"}

package/dist/byte-codecs.js

@@ -0,0 +1,116 @@
+// Byte codecs shared across the package: hex string rendering/parsing and
+// fixed-width integer encodings in both byte orders. Big-endian is the SEC1
+// order stored signatures and ABI words use, little-endian is the order
+// Compact's `Bytes<32> as Field` / `as Secp256k1Scalar` casts read.
+/**
+ * Render bytes as a lowercase hex string, no `0x` prefix.
+ *
+ * @param bytes - The bytes to render.
+ * @returns Lowercase hex, two chars per byte.
+ */
+export function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Strip an optional `0x`/`0X` prefix from a hex string.
+ *
+ * @param hex - A hex string, with or without a `0x` prefix.
+ * @returns The bare hex digits.
+ */
+export function stripHexPrefix(hex) {
+    return hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+}
+/**
+ * Decode a hex string into bytes: the inverse of {@link bytesToHex}.
+ *
+ * @param hex - An even number of hex digits, with or without a `0x` prefix.
+ * @returns The decoded bytes.
+ * @throws {Error} If the digits are odd-length or not all hex: lenient parsing
+ *   would return plausible-looking wrong bytes.
+ */
+export function hexToBytes(hex) {
+    const digits = stripHexPrefix(hex);
+    if (digits.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(digits)) {
+        throw new Error(`not a hex byte string: "${hex}"`);
+    }
+    const out = new Uint8Array(digits.length >> 1);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = Number.parseInt(digits.slice(2 * i, 2 * i + 2), 16);
+    }
+    return out;
+}
+/** BLS12-381 scalar field order (the Compact `Field` type modulus). */
+export const BLS_ORDER = 52435875175126190479447740508185965837690552500527637822603658699938581184513n;
+/**
+ * Little-endian bytes to a bigint: the byte order Compact's
+ * `Bytes<32> as Field` / `as Secp256k1Scalar` casts read.
+ *
+ * @param bytes - Little-endian byte array.
+ * @returns The decoded non-negative integer.
+ */
+export function bytesToBigint(bytes) {
+    let result = 0n;
+    let shift = 0n;
+    for (const byte of bytes) {
+        result |= BigInt(byte) << shift;
+        shift += 8n;
+    }
+    return result;
+}
+/**
+ * A bigint to exactly 32 little-endian bytes: the inverse of
+ * {@link bytesToBigint}. Non-negative values encode raw (the full 32-byte
+ * range, so secp256k1 scalars above {@link BLS_ORDER} fit). Negative values
+ * are interpreted in the BLS scalar field, so their domain is
+ * `[-BLS_ORDER, 0)`.
+ *
+ * @param n - The integer to encode.
+ * @returns The 32-byte little-endian encoding.
+ * @throws {Error} If the value is below `-BLS_ORDER` or does not fit 32 bytes.
+ */
+export function bigintToBytes32(n) {
+    if (n < -BLS_ORDER || n >= 1n << 256n) {
+        throw new Error(`value does not fit 32 little-endian bytes: ${String(n)}`);
+    }
+    const buf = new Uint8Array(32);
+    let v = n < 0n ? n + BLS_ORDER : n;
+    for (let i = 0; i < 32; i++) {
+        buf[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return buf;
+}
+/**
+ * Big-endian (SEC1) bytes to a bigint: the byte order stored signatures use.
+ *
+ * @param bytes - Big-endian byte array.
+ * @returns The decoded non-negative integer.
+ */
+export function bytesToBigintBE(bytes) {
+    let value = 0n;
+    for (const byte of bytes) {
+        value = (value << 8n) | BigInt(byte);
+    }
+    return value;
+}
+/**
+ * A bigint to exactly 32 big-endian (SEC1) bytes: the inverse of
+ * {@link bytesToBigintBE}.
+ *
+ * @param value - The non-negative integer to encode.
+ * @returns The 32-byte big-endian encoding.
+ * @throws {Error} If the value is negative or does not fit 32 bytes.
+ */
+export function bigintToBytes32BE(value) {
+    if (value < 0n || value >= 1n << 256n) {
+        throw new Error(`value does not fit 32 big-endian bytes: ${String(value)}`);
+    }
+    const out = new Uint8Array(32);
+    let v = value;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+//# sourceMappingURL=byte-codecs.js.map

package/dist/byte-codecs.js.map

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

package/dist/compact-descriptors.d.ts

@@ -0,0 +1,89 @@
+import { type AlignedValue, type CompactType, CompactTypeBytes, CompactTypeUnsignedInteger } from "@midnight-ntwrk/compact-runtime";
+/** Descriptor of a Compact `Bytes<4>`. */
+export declare const BYTES_4: CompactTypeBytes;
+/** Descriptor of a Compact `Bytes<20>`. */
+export declare const BYTES_20: CompactTypeBytes;
+/** Descriptor of a Compact `Bytes<32>`. */
+export declare const BYTES_32: CompactTypeBytes;
+/** Descriptor of a Compact `Bytes<64>`. */
+export declare const BYTES_64: CompactTypeBytes;
+/** Descriptor of a Compact `Uint<8>`. */
+export declare const UINT_8: CompactTypeUnsignedInteger;
+/** Descriptor of a Compact `Uint<16>`. */
+export declare const UINT_16: CompactTypeUnsignedInteger;
+/** Descriptor of a Compact `Uint<64>`. */
+export declare const UINT_64: CompactTypeUnsignedInteger;
+/** Descriptor of a Compact `Uint<128>`. */
+export declare const UINT_128: CompactTypeUnsignedInteger;
+/**
+ * A Midnight contract address as the generated code represents it in struct
+ * fields (Compact `ContractAddress`): a single-field wrapper around the raw
+ * 32 address bytes.
+ */
+export interface ContractAddress {
+    bytes: Uint8Array;
+}
+/**
+ * Descriptor of a Compact `ContractAddress` struct field: a single-field
+ * `{ bytes: Bytes<32> }` wrapper, exactly as the compiler generates it.
+ */
+export declare const CONTRACT_ADDRESS: CompactType<ContractAddress>;
+/**
+ * Compact's standard-library `Maybe<T>` as the compiler generates it: a
+ * plain struct. Even when `is_some` is false, `value` carries a full
+ * default-valued `T` (so vector capacities remain inferable).
+ */
+export interface Maybe<T> {
+    is_some: boolean;
+    value: T;
+}
+/**
+ * Build the runtime descriptor of a Compact struct from its per-field
+ * descriptors. Field ORDER is the encoding order and must match the Compact
+ * struct declaration order: object literals preserve insertion order for
+ * string keys, so pass fields in declaration order.
+ *
+ * @param fields - One runtime descriptor per struct field, in declaration order.
+ * @returns The composed struct descriptor.
+ */
+export declare function compactStructDescriptor<T extends object>(fields: {
+    readonly [K in keyof T]-?: CompactType<T[K]>;
+}): CompactType<T>;
+/**
+ * Descriptor of Compact's standard-library `Maybe<T>`: the compiler
+ * generates it as the struct `{ is_some: Boolean, value: T }`.
+ *
+ * @param inner - Descriptor of the wrapped type.
+ * @returns The Maybe struct descriptor.
+ */
+export declare function compactMaybeDescriptor<T>(inner: CompactType<T>): CompactType<Maybe<T>>;
+/**
+ * Decode ONE whole stored value with a descriptor. `fromValue` is a cursor:
+ * it consumes atoms from the front of the array it is handed and ignores
+ * whatever remains, which is right for descriptors chained mid-struct but
+ * wrong for a complete key, cell or payload: called directly it either
+ * mutates live state (no copy) or accepts trailing atoms the descriptor
+ * never read (copy, no length check). This wrapper owns the copy and rejects
+ * leftovers, so a stored shape that has outgrown its descriptor fails loudly
+ * instead of decoding a stale prefix.
+ *
+ * @param type - The descriptor to decode with.
+ * @param atoms - The complete stored value. Never mutated.
+ * @param what - Error-message subject.
+ * @returns The decoded value.
+ * @throws {Error} If the descriptor rejects the atoms, or atoms remain after
+ *   it has consumed its fill.
+ */
+export declare function decodeExactly<T>(type: CompactType<T>, atoms: readonly Uint8Array[], what: string): T;
+/**
+ * The declared width of each atom. Signet declares only `Bytes` atoms, so a
+ * widthless or nested segment is refused rather than assigned a width.
+ *
+ * @param cell - The record cell as stored.
+ * @param what - Error-message subject.
+ * @returns One declared byte width per atom.
+ * @throws {Error} If the alignment and value lengths disagree or a segment is
+ *   not a `Bytes` atom.
+ */
+export declare function declaredWidths(cell: AlignedValue, what: string): number[];
+//# sourceMappingURL=compact-descriptors.d.ts.map

package/dist/compact-descriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact-descriptors.d.ts","sourceRoot":"","sources":["../src/compact-descriptors.ts"],"names":[],"mappings":"AAyBA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAEhB,gBAAgB,EAChB,0BAA0B,EAC3B,MAAM,iCAAiC,CAAC;AAKzC,0CAA0C;AAC1C,eAAO,MAAM,OAAO,kBAA0B,CAAC;AAC/C,2CAA2C;AAC3C,eAAO,MAAM,QAAQ,kBAA2B,CAAC;AACjD,2CAA2C;AAC3C,eAAO,MAAM,QAAQ,kBAA2B,CAAC;AACjD,2CAA2C;AAC3C,eAAO,MAAM,QAAQ,kBAA2B,CAAC;AACjD,yCAAyC;AACzC,eAAO,MAAM,MAAM,4BAAmD,CAAC;AACvE,0CAA0C;AAC1C,eAAO,MAAM,OAAO,4BAAoD,CAAC;AACzE,0CAA0C;AAC1C,eAAO,MAAM,OAAO,4BAAoD,CAAC;AACzE,2CAA2C;AAC3C,eAAO,MAAM,QAAQ,4BAAsD,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,eAAe,CAIzD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,CAAC,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE;IAChE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7C,GAAG,WAAW,CAAC,CAAC,CAAC,CAgBjB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAKtF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,IAAI,EAAE,MAAM,GACX,CAAC,CASH;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBzE"}

package/dist/compact-descriptors.js

@@ -0,0 +1,139 @@
+// Compact-generic runtime descriptor toolkit: compact-runtime `CompactType`
+// codecs (alignment/toValue/fromValue) at the same literals the compiler
+// emits, composed into the signet record descriptors by the request modules.
+// They exist so the package can (a) decode raw state cells of ANY requester
+// contract discovered at runtime and (b) serialize a record byte-identically
+// to the circuits' keccak256 preimage, and they exist HERE only because the
+// Midnight libraries expose no supported equivalent:
+//  - A compiled contract module (`src/managed/`) builds one such codec per
+//    ledger type but keeps them module-private, exporting only `ledger()`,
+//    which decodes the FULL state of the one contract it was compiled from.
+//    Signet readers hold neither that contract's compiled module nor its
+//    full state: just a cell.
+//  - `@midnight-ntwrk/compact-runtime` exports the primitive codec classes
+//    (`CompactTypeBytes`, `CompactTypeUnsignedInteger`, ...) but no struct
+//    composer and no `Maybe` descriptor, and documents its own pre-built
+//    instances (`Bytes32Descriptor`, `ContractAddressDescriptor`, ...) as
+//    "not intended for direct consumption".
+// Delete each piece of this file the moment compact-runtime exports a
+// supported equivalent.
+//
+// These are NOT the `CompactType` schema types of @sig-net/midnight-serde
+// (that package describes the `serialize<T, N>` wire format, a different
+// layer). Package-internal: consumers use the reader/request functions built
+// on top, never these directly.
+import { CompactTypeBoolean, CompactTypeBytes, CompactTypeUnsignedInteger, } from "@midnight-ntwrk/compact-runtime";
+// Runtime descriptors of the Compact base types, at the same literals the
+// compiler emits.
+/** Descriptor of a Compact `Bytes<4>`. */
+export const BYTES_4 = new CompactTypeBytes(4);
+/** Descriptor of a Compact `Bytes<20>`. */
+export const BYTES_20 = new CompactTypeBytes(20);
+/** Descriptor of a Compact `Bytes<32>`. */
+export const BYTES_32 = new CompactTypeBytes(32);
+/** Descriptor of a Compact `Bytes<64>`. */
+export const BYTES_64 = new CompactTypeBytes(64);
+/** Descriptor of a Compact `Uint<8>`. */
+export const UINT_8 = new CompactTypeUnsignedInteger(2n ** 8n - 1n, 1);
+/** Descriptor of a Compact `Uint<16>`. */
+export const UINT_16 = new CompactTypeUnsignedInteger(2n ** 16n - 1n, 2);
+/** Descriptor of a Compact `Uint<64>`. */
+export const UINT_64 = new CompactTypeUnsignedInteger(2n ** 64n - 1n, 8);
+/** Descriptor of a Compact `Uint<128>`. */
+export const UINT_128 = new CompactTypeUnsignedInteger(2n ** 128n - 1n, 16);
+/**
+ * Descriptor of a Compact `ContractAddress` struct field: a single-field
+ * `{ bytes: Bytes<32> }` wrapper, exactly as the compiler generates it.
+ */
+export const CONTRACT_ADDRESS = {
+    alignment: () => BYTES_32.alignment(),
+    fromValue: (value) => ({ bytes: BYTES_32.fromValue(value) }),
+    toValue: (value) => BYTES_32.toValue(value.bytes),
+};
+/**
+ * Build the runtime descriptor of a Compact struct from its per-field
+ * descriptors. Field ORDER is the encoding order and must match the Compact
+ * struct declaration order: object literals preserve insertion order for
+ * string keys, so pass fields in declaration order.
+ *
+ * @param fields - One runtime descriptor per struct field, in declaration order.
+ * @returns The composed struct descriptor.
+ */
+export function compactStructDescriptor(fields) {
+    const entries = Object.entries(fields);
+    return {
+        alignment: () => entries.flatMap(([, type]) => type.alignment()),
+        toValue: (value) => entries.flatMap(([key, type]) => type.toValue(value[key])),
+        fromValue: (value) => {
+            const result = {};
+            for (const [key, type] of entries) {
+                result[key] = type.fromValue(value);
+            }
+            return result;
+        },
+    };
+}
+/**
+ * Descriptor of Compact's standard-library `Maybe<T>`: the compiler
+ * generates it as the struct `{ is_some: Boolean, value: T }`.
+ *
+ * @param inner - Descriptor of the wrapped type.
+ * @returns The Maybe struct descriptor.
+ */
+export function compactMaybeDescriptor(inner) {
+    return compactStructDescriptor({
+        is_some: CompactTypeBoolean,
+        value: inner,
+    });
+}
+/**
+ * Decode ONE whole stored value with a descriptor. `fromValue` is a cursor:
+ * it consumes atoms from the front of the array it is handed and ignores
+ * whatever remains, which is right for descriptors chained mid-struct but
+ * wrong for a complete key, cell or payload: called directly it either
+ * mutates live state (no copy) or accepts trailing atoms the descriptor
+ * never read (copy, no length check). This wrapper owns the copy and rejects
+ * leftovers, so a stored shape that has outgrown its descriptor fails loudly
+ * instead of decoding a stale prefix.
+ *
+ * @param type - The descriptor to decode with.
+ * @param atoms - The complete stored value. Never mutated.
+ * @param what - Error-message subject.
+ * @returns The decoded value.
+ * @throws {Error} If the descriptor rejects the atoms, or atoms remain after
+ *   it has consumed its fill.
+ */
+export function decodeExactly(type, atoms, what) {
+    const cursor = [...atoms];
+    const decoded = type.fromValue(cursor);
+    if (cursor.length !== 0) {
+        throw new Error(`${what} decode left ${String(cursor.length)} of ${String(atoms.length)} atoms unconsumed`);
+    }
+    return decoded;
+}
+/**
+ * The declared width of each atom. Signet declares only `Bytes` atoms, so a
+ * widthless or nested segment is refused rather than assigned a width.
+ *
+ * @param cell - The record cell as stored.
+ * @param what - Error-message subject.
+ * @returns One declared byte width per atom.
+ * @throws {Error} If the alignment and value lengths disagree or a segment is
+ *   not a `Bytes` atom.
+ */
+export function declaredWidths(cell, what) {
+    if (cell.alignment.length !== cell.value.length) {
+        throw new Error(`${what} declares ${String(cell.alignment.length)} alignment segments for ` +
+            `${String(cell.value.length)} atoms`);
+    }
+    return cell.alignment.map((segment, index) => {
+        if (segment.tag !== "atom") {
+            throw new Error(`${what} atom ${String(index)} is an alignment option, which no signet type declares`);
+        }
+        if (segment.value.tag !== "bytes") {
+            throw new Error(`${what} atom ${String(index)} is aligned '${segment.value.tag}', which carries no byte width`);
+        }
+        return segment.value.length;
+    });
+}
+//# sourceMappingURL=compact-descriptors.js.map

package/dist/compact-descriptors.js.map

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

package/dist/constants.d.ts

@@ -7,41 +7,25 @@ export declare const SELECTOR_BYTES = 4;
 /**
  * The complete serialised output the MPC attests for a FAILED remote
  * execution (reverted or replaced transaction): the 4-byte error marker
- * `0xdeadbeef` followed by one `0x01` byte. Schema-independent by design,
- * mirroring the canonical MPC's Borsh-format failure payload (sig-net/mpc,
- * node/src/respond_bidirectional.rs), so every respond schema shares one
- * fixed 5-byte failure width. Clients recompute their failure candidate from
- * this constant alone: no receipt or schema needed.
- *
- * The exact-equality check ({@link isMpcFailureOutput}) is unambiguous for
- * every respond schema whose packed width differs from 5 bytes. A schema
- * whose packed width is exactly 5 could in principle produce a legitimate
- * output equal to this sentinel, and such clients must route settlement by
- * digest-candidate matching (recompute both the real-output candidate and
- * the failure candidate, and see which digest the MPC attested), never by
- * inspecting output bytes.
+ * `0xdeadbeef` followed by one `0x01` byte, mirroring the canonical MPC's
+ * failure payload (sig-net/mpc, node/src/respond_bidirectional.rs). A
+ * respond schema whose packed width is exactly 5 bytes could produce a
+ * legitimate output equal to this sentinel: such clients must route
+ * settlement by digest-candidate matching, never by inspecting output
+ * bytes. See {@link isMpcFailureOutput}.
  */
 export declare const MPC_FAILURE_OUTPUT: Uint8Array<ArrayBuffer>;
 /**
  * Whether an attested serialised output IS the MPC's fixed failure payload:
- * exact byte equality with the 5-byte {@link MPC_FAILURE_OUTPUT} (the length
- * must be exactly 5 and every byte must match). A prefix check would be
- * unsafe, as a legitimate packed output can begin with the same bytes.
- *
- * Unambiguous for every respond schema whose packed width differs from 5
- * bytes. A schema whose packed width is exactly 5 could in principle produce
- * a legitimate output equal to the sentinel: such clients must route
- * settlement by digest-candidate matching instead of inspecting output
- * bytes (see {@link MPC_FAILURE_OUTPUT}).
+ * exact byte equality with the 5-byte {@link MPC_FAILURE_OUTPUT}.
  *
  * @param serializedOutput - The attested serialised output.
  * @returns `true` when the output equals the MPC failure payload exactly.
  */
 export declare function isMpcFailureOutput(serializedOutput: Uint8Array): boolean;
 /**
- * Default MPC key version (`keyVersion` field value). Version 0 is the
- * unsupported legacy format: the canonical MPC (and
- * `constructSignBidirectionalEvent`) requires `keyVersion >= 1`.
+ * Default MPC key version (`keyVersion` field value). The canonical MPC
+ * (and `constructSignBidirectionalEvent`) requires `keyVersion >= 1`.
  */
 export declare const SIGNET_DEFAULT_KEY_VERSION = 1n;
 /**
@@ -52,15 +36,12 @@ export declare const SIGNET_DEFAULT_KEY_VERSION = 1n;
  * @param text - The ASCII text to encode.
  * @param length - The fixed field width in bytes.
  * @returns `text`'s bytes followed by zero padding to exactly `length`.
- * @throws If the encoded text does not fit in `length` bytes.
+ * @throws {Error} If the encoded text does not fit in `length` bytes.
  */
 export declare function asciiPadded(text: string, length: number): Uint8Array;
 /**
  * A named Midnight network: the single source of the network names shared
- * across the `@sig-net/midnight*` packages. midnight-js types a network id
- * as a bare `string` with no companion enum, so the names live here, and
- * `@sig-net/midnight-contract-deploy`'s network-id plumbing widens this
- * enum back to the SDK's string type for its deploy config.
+ * across the `@sig-net/midnight*` packages.
  */
 export declare enum MidnightNetwork {
     /** Local standalone stack (Docker node, indexer and proof server on localhost). */
@@ -78,35 +59,29 @@ export declare enum MidnightNetwork {
  * A public, long-lived Midnight network: every named network except the
  * local standalone stack. Only these have fixed protocol counterparty
  * values published in this package (see {@link getMpcRootPublicKey} and
- * {@link getSignetContractAddress}); a local stack generates its own values
- * per deployment instead.
+ * {@link getSignetContractAddress}).
  */
 export type DeployedNetwork = Exclude<MidnightNetwork, MidnightNetwork.Undeployed>;
 /**
  * The MPC root public key of a deployed Midnight network, as hex: the
  * `mpcRootPublicKey` every client key derivation starts from (see
- * `deriveEvmAddress`). Only the {@link DeployedNetwork} networks have a
- * fixed key. A local standalone stack has none: its setup generates a fresh
- * `MPC_ROOT_KEY` per stack (the integration-test setup prints it and
- * appends it to the repo-root `.env`).
+ * `deriveEvmAddress`). A local standalone stack has no fixed key: its setup
+ * generates a fresh `MPC_ROOT_KEY` per stack.
  *
  * @param networkId - The deployed network to look up.
  * @returns The network's MPC root public key.
- * @throws Error when the network's key is not yet published in this package.
+ * @throws {Error} When the network's key is not yet published in this package.
  */
 export declare function getMpcRootPublicKey(networkId: DeployedNetwork): string;
 /**
  * The address of the central signet singleton contract on a deployed
  * Midnight network: the `signetContractAddress` a
- * `SignetRequestResponseReader` polls. Only the {@link DeployedNetwork}
- * networks have a fixed address. A local standalone stack has none: each
- * stack deploys its own singleton (the integration-test setup prints the
- * address as `MIDNIGHT_SIGNET_CONTRACT_ADDRESS` and appends it to the
- * repo-root `.env`).
+ * `SignetRequestResponseReader` polls. A local standalone stack has no
+ * fixed address: each stack deploys its own singleton.
  *
  * @param networkId - The deployed network to look up.
  * @returns The network's signet contract address.
- * @throws Error when the singleton's address is not yet published in this
+ * @throws {Error} When the singleton's address is not yet published in this
  *   package.
  */
 export declare function getSignetContractAddress(networkId: DeployedNetwork): string;

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAWA,+DAA+D;AAC/D,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,wFAAwF;AACxF,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,yBAAiD,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,UAAU,GAAG,OAAO,CAKxE;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAQpE;AAED;;;;;;GAMG;AACH,oBAAY,eAAe;IACzB,mFAAmF;IACnF,UAAU,eAAe;IACzB,2CAA2C;IAC3C,QAAQ,aAAa;IACrB,iFAAiF;IACjF,OAAO,YAAY;IACnB,+EAA+E;IAC/E,OAAO,YAAY;IACnB,6CAA6C;IAC7C,OAAO,YAAY;CACpB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;AAYnF;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAMtE;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAM3E"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AASA,+DAA+D;AAC/D,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,wFAAwF;AACxF,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,yBAAiD,CAAC;AAEjF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,UAAU,GAAG,OAAO,CAKxE;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAUpE;AAED;;;GAGG;AACH,oBAAY,eAAe;IACzB,mFAAmF;IACnF,UAAU,eAAe;IACzB,2CAA2C;IAC3C,QAAQ,aAAa;IACrB,iFAAiF;IACjF,OAAO,YAAY;IACnB,+EAA+E;IAC/E,OAAO,YAAY;IACnB,6CAA6C;IAC7C,OAAO,YAAY;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;AAYnF;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAMtE;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAM3E"}