@sig-net/midnight 0.0.1

package/dist/signature-state-reading.js

@@ -0,0 +1,62 @@
+// Common signet raw-state reading, shared by the request and response readers
+// (signature-requests-state-reader.ts, signet-contract-state-reader.ts).
+// This is the MPC-/client-style path: decode a contract's ledger fields out of
+// its raw state WITHOUT the compiled contract, walking the state tree by field
+// position alone. Here live the generic tree walk (RawContractState,
+// signetFieldNode) and the base type descriptors both readers share; each
+// reader adds only the descriptors for its own layout.
+import { CompactTypeBytes, CompactTypeUnsignedInteger, } from "@midnight-ntwrk/compact-runtime";
+import {} from "./signet-requests.js";
+// ---- Shared base type descriptors ----
+// fromValue consumes the aligned value sequentially, so any width change here
+// is silent data corruption, not an error. These mirror the Compact base types
+// used across both signet layouts.
+/** Descriptor for a Compact `Uint<64>` (8-byte unsigned integer). */
+export const u64 = new CompactTypeUnsignedInteger(18446744073709551615n, 8);
+/** Descriptor for a Compact `Bytes<32>`. */
+export const bytes32 = new CompactTypeBytes(32);
+/**
+ * Descriptor for a request id ledger key (Compact `RequestId`, a
+ * nominal `Bytes<32>`). Use it to encode a {@link RequestId} into the
+ * aligned form the state tree stores, or decode one back.
+ */
+export const requestIdType = bytes32;
+/**
+ * Unwrap a {@link RawContractState} to the underlying `StateValue`.
+ *
+ * @param raw - Bare state value or a `.state`-carrying wrapper.
+ * @returns The bare `StateValue`.
+ */
+const unwrap = (raw) => "state" in raw ? raw.state : raw;
+/**
+ * Resolve a flat ledger field index to its node in the raw state tree.
+ *
+ * The runtime stores ledger fields as a root array and chunks them one level
+ * deep once the field count grows, so chunked roots are flattened before
+ * indexing. Chunk detection assumes signet field 0 is a `Map`, never a
+ * `List` (whose node is also array-typed) — guaranteed by the signet layout
+ * convention.
+ *
+ * @param raw - Raw contract state from the indexer or simulator.
+ * @param flatIndex - Zero-based ledger field position in declaration order.
+ * @returns The `StateValue` node holding that field.
+ * @throws Error if `flatIndex` is beyond the contract's field count.
+ */
+export function signetFieldNode(raw, flatIndex) {
+    const root = unwrap(raw);
+    if (root.type() !== "array") {
+        if (flatIndex === 0)
+            return root;
+        throw new Error(`Field index ${flatIndex} out of range: root is a leaf`);
+    }
+    const nodes = root.asArray() ?? [];
+    const fields = nodes[0]?.type() === "array"
+        ? nodes.flatMap((chunk) => chunk.asArray() ?? [])
+        : nodes;
+    const node = fields[flatIndex];
+    if (node === undefined) {
+        throw new Error(`Field index ${flatIndex} out of range`);
+    }
+    return node;
+}
+//# sourceMappingURL=signature-state-reading.js.map

package/dist/signature-state-reading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-state-reading.js","sourceRoot":"","sources":["../src/signature-state-reading.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,yEAAyE;AACzE,+EAA+E;AAC/E,+EAA+E;AAC/E,qEAAqE;AACrE,0EAA0E;AAC1E,uDAAuD;AAEvD,OAAO,EACL,gBAAgB,EAChB,0BAA0B,GAG3B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAkB,MAAM,sBAAsB,CAAC;AAEtD,yCAAyC;AACzC,8EAA8E;AAC9E,+EAA+E;AAC/E,mCAAmC;AAEnC,qEAAqE;AACrE,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,0BAA0B,CAAC,qBAAqB,EAAE,CAAC,CAAC,CAAC;AAE5E,4CAA4C;AAC5C,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,EAAE,CAAC,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAA2B,OAAO,CAAC;AAW7D;;;;;GAKG;AACH,MAAM,MAAM,GAAG,CAAC,GAAqB,EAAc,EAAE,CACnD,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAqB,EACrB,SAAiB;IAEjB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;QAC5B,IAAI,SAAS,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,eAAe,SAAS,+BAA+B,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;IACnC,MAAM,MAAM,GACV,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,OAAO;QAC1B,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;QACjD,CAAC,CAAC,KAAK,CAAC;IACZ,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,eAAe,SAAS,eAAe,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/signet-contract-state-reader.d.ts

@@ -0,0 +1,146 @@
+import { type CompactType, type JubjubPoint } from "@midnight-ntwrk/compact-runtime";
+import { type RequestId, type RequestIdHex } from "./signet-requests.ts";
+import { type RawContractState } from "./signature-state-reading.ts";
+/** Signet contract layout: the signature response counter index is ledger field 0. */
+export declare const SIGNATURE_RESPONSE_COUNTER_INDEX_FIELD = 0;
+/** Signet contract layout: the signature response log is ledger field 1. */
+export declare const SIGNATURE_RESPONSE_INDEX_FIELD = 1;
+/** Signet contract layout: the respond-bidirectional index is ledger field 2. */
+export declare const RESPOND_BIDIRECTIONAL_INDEX_FIELD = 2;
+/** Signet contract layout: the sealed MPC attestation key hash is ledger field 3. */
+export declare const MPC_PUB_KEY_HASH_FIELD = 3;
+/**
+ * The MPC's secp256k1 signature over the requested EVM transaction (Compact
+ * `SignatureResponse` — the canonical MPC `Signature { big_r, s,
+ * recovery_id }` with `big_r` decomposed into affine coordinates, big-endian
+ * scalar bytes). The request id it answers lives in the response index key,
+ * not here.
+ */
+export interface SignatureResponse {
+    /** Signature R.x, 32 big-endian bytes. */
+    bigRx: Uint8Array;
+    /** Signature R.y, 32 big-endian bytes. */
+    bigRy: Uint8Array;
+    /** Signature s, 32 big-endian bytes. */
+    s: Uint8Array;
+    /** Parity of R.y for public-key recovery (0 or 1). */
+    recoveryId: bigint;
+}
+/**
+ * Hand-composed descriptor for {@link SignatureResponse}. Field
+ * order (bigRx, bigRy, s, recoveryId) must match the Compact struct.
+ */
+export declare const signatureResponseType: CompactType<SignatureResponse>;
+/**
+ * The MPC's respond-bidirectional attestation of a request's remote EVM
+ * execution (Compact `RespondBidirectional`): the serialized execution
+ * output plus the Schnorr signature over
+ * `(requestId, hash(serializedOutput, outputLen))`. Stored records were
+ * verified IN-CIRCUIT by the signet contract at post time, so readers can
+ * trust them without re-verifying.
+ */
+export interface RespondBidirectional {
+    /** ABI-encoded return data (canonical serialized_output), zero-padded to 128 bytes. */
+    serializedOutput: Uint8Array;
+    /** Meaningful byte count of {@link serializedOutput}. */
+    outputLen: bigint;
+    /** The MPC attestation key (hash-checked against the sealed key at post). */
+    pk: JubjubPoint;
+    /** Schnorr nonce commitment R. */
+    announcement: JubjubPoint;
+    /** Schnorr response scalar s. */
+    response: bigint;
+}
+/**
+ * Composite key of one posted signature response (Compact
+ * `SignetResponseKey`): the request id it answers plus this post's 0-based
+ * count. Field order — count first, then request id — mirrors the Compact
+ * struct.
+ */
+export interface SignetResponseKey {
+    /** 0-based position of this post among the responses for {@link requestId}. */
+    count: bigint;
+    /** 32-byte id of the request this response answers. */
+    requestId: RequestId;
+}
+/**
+ * Hand-composed descriptor for {@link SignetResponseKey} — the map key of
+ * the signature response log. Field order (count, then requestId) must match
+ * the Compact struct.
+ */
+export declare const signetResponseKeyType: CompactType<SignetResponseKey>;
+/**
+ * Hand-composed descriptor for {@link RespondBidirectional}. Field
+ * order (serializedOutput, outputLen, pk, announcement, response) must match
+ * the Compact struct.
+ */
+export declare const respondBidirectionalType: CompactType<RespondBidirectional>;
+/**
+ * Plain-JS signature response counter index parsed out of the ledger: hex
+ * request id (see {@link requestIdHex}) to the number of responses posted for
+ * that request. Entries in the response log exist for counts `0 .. value - 1`.
+ */
+export type SignatureResponseCounterIndex = Map<RequestIdHex, bigint>;
+/**
+ * Plain-JS signature response log parsed out of the ledger, keyed by
+ * {@link signetResponseIndexKey} (`"<hexRequestId>:<count>"`) so the
+ * composite Compact key survives as a usable JS `Map` key.
+ */
+export type SignatureResponseIndex = Map<string, SignatureResponse>;
+/**
+ * Plain-JS respond-bidirectional index parsed out of the ledger: hex
+ * request id to the contract-verified attestation. One slot per request.
+ */
+export type RespondBidirectionalIndex = Map<RequestIdHex, RespondBidirectional>;
+/**
+ * Build the {@link SignatureResponseIndex} key for a `(requestId, count)`
+ * pair — the composite Compact key flattened to a string so it works as a JS
+ * `Map` key.
+ *
+ * @param id - The request id the response answers, in canonical hex form.
+ * @param count - 0-based post count within that request.
+ * @returns `"<hexRequestId>:<count>"`.
+ */
+export declare function signetResponseIndexKey(id: RequestIdHex, count: bigint): string;
+/**
+ * The decoded ledger fields of the signet contract: the signature response
+ * counter (field 0) and log (field 1), the respond-bidirectional index
+ * (field 2), and the sealed MPC attestation key hash (field 3). Together
+ * they give a client everything the MPC ever delivers for a request.
+ */
+export interface SignetContractLedger {
+    /**
+     * The signature response counter index (ledger field
+     * {@link SIGNATURE_RESPONSE_COUNTER_INDEX_FIELD}), keyed by hex request id.
+     */
+    signatureResponseCounterIndex: SignatureResponseCounterIndex;
+    /**
+     * The signature response log (ledger field
+     * {@link SIGNATURE_RESPONSE_INDEX_FIELD}), keyed by
+     * {@link signetResponseIndexKey}.
+     */
+    signatureResponseIndex: SignatureResponseIndex;
+    /**
+     * The respond-bidirectional index (ledger field
+     * {@link RESPOND_BIDIRECTIONAL_INDEX_FIELD}), keyed by hex request id.
+     */
+    respondBidirectionalIndex: RespondBidirectionalIndex;
+    /**
+     * The sealed MPC attestation key hash (ledger field
+     * {@link MPC_PUB_KEY_HASH_FIELD}) posts are verified against.
+     */
+    mpcPubKeyHash: Uint8Array;
+}
+/**
+ * MPC-/client-style read: parse the signet contract's ledger fields out of
+ * raw contract state by field position alone — no compiled contract, no
+ * generated `ledger()`, only the signet contract layout convention and the
+ * canonical descriptors above.
+ *
+ * @param raw - Raw contract state, e.g. `queryContractState(address).data`
+ *   from the indexer or `ctx.currentQueryContext.state` from the simulator.
+ * @returns The decoded {@link SignetContractLedger}.
+ * @throws Error if a field is missing or has the wrong state-value shape.
+ */
+export declare function readSignetContractLedgerFromState(raw: RawContractState): SignetContractLedger;
+//# sourceMappingURL=signet-contract-state-reader.d.ts.map

package/dist/signet-contract-state-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signet-contract-state-reader.d.ts","sourceRoot":"","sources":["../src/signet-contract-state-reader.ts"],"names":[],"mappings":"AAWA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAC;AAEtC,sFAAsF;AACtF,eAAO,MAAM,sCAAsC,IAAI,CAAC;AAExD,4EAA4E;AAC5E,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,iFAAiF;AACjF,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,qFAAqF;AACrF,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAgBxC;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,KAAK,EAAE,UAAU,CAAC;IAClB,0CAA0C;IAC1C,KAAK,EAAE,UAAU,CAAC;IAClB,wCAAwC;IACxC,CAAC,EAAE,UAAU,CAAC;IACd,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,iBAAiB,CAqChE,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,uFAAuF;IACvF,gBAAgB,EAAE,UAAU,CAAC;IAC7B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,EAAE,EAAE,WAAW,CAAC;IAChB,kCAAkC;IAClC,YAAY,EAAE,WAAW,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,iBAAiB,CA0BhE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,oBAAoB,CAwCtE,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,6BAA6B,GAAG,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,GAAG,CACzC,YAAY,EACZ,oBAAoB,CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAER;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,6BAA6B,EAAE,6BAA6B,CAAC;IAC7D;;;;OAIG;IACH,sBAAsB,EAAE,sBAAsB,CAAC;IAC/C;;;OAGG;IACH,yBAAyB,EAAE,yBAAyB,CAAC;IACrD;;;OAGG;IACH,aAAa,EAAE,UAAU,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,gBAAgB,GACpB,oBAAoB,CA0EtB"}

package/dist/signet-contract-state-reader.js

@@ -0,0 +1,226 @@
+// MPC-/client-style raw state reader for the central SIGNET contract: decode
+// its ledger fields out of a contract's raw state WITHOUT the compiled
+// contract, the mirror image of signature-requests-state-reader.ts. A poller
+// has only the contract address, queries raw state from the indexer
+// (queryContractState(address).data), and decodes by the signet contract
+// layout convention (see "Signet Contract Ledger Layout" in Signet.compact):
+// signature response counter index (field 0), signature response log
+// (field 1), respond-bidirectional index (field 2), sealed MPC key hash
+// (field 3). The generic state-tree walk (RawContractState, signetFieldNode)
+// and the shared base descriptors live in signature-state-reading.ts.
+import { CompactTypeBytes, CompactTypeField, CompactTypeJubjubPoint, CompactTypeUnsignedInteger, } from "@midnight-ntwrk/compact-runtime";
+import { requestIdHex, } from "./signet-requests.js";
+import { requestIdType, signetFieldNode, u64, } from "./signature-state-reading.js";
+/** Signet contract layout: the signature response counter index is ledger field 0. */
+export const SIGNATURE_RESPONSE_COUNTER_INDEX_FIELD = 0;
+/** Signet contract layout: the signature response log is ledger field 1. */
+export const SIGNATURE_RESPONSE_INDEX_FIELD = 1;
+/** Signet contract layout: the respond-bidirectional index is ledger field 2. */
+export const RESPOND_BIDIRECTIONAL_INDEX_FIELD = 2;
+/** Signet contract layout: the sealed MPC attestation key hash is ledger field 3. */
+export const MPC_PUB_KEY_HASH_FIELD = 3;
+// ---- Type descriptors (must mirror Signet.compact field-for-field) ----
+// As in the requests reader, fromValue consumes the aligned value
+// sequentially, so field order and width here must match the Compact structs
+// exactly — a mismatch is silent data corruption, not an error.
+/** Descriptor for a signature scalar / MPC key hash (`Bytes<32>`). */
+const bytes32 = new CompactTypeBytes(32);
+/** Descriptor for the attestation's serialized output (`Bytes<128>`). */
+const bytes128 = new CompactTypeBytes(128);
+/** Descriptor for a Compact `Uint<8>` (1-byte unsigned integer). */
+const u8 = new CompactTypeUnsignedInteger(255n, 1);
+/**
+ * Hand-composed descriptor for {@link SignatureResponse}. Field
+ * order (bigRx, bigRy, s, recoveryId) must match the Compact struct.
+ */
+export const signatureResponseType = {
+    /** @returns Compound alignment of the struct's fields in declaration order. */
+    alignment() {
+        return bytes32
+            .alignment()
+            .concat(bytes32.alignment())
+            .concat(bytes32.alignment())
+            .concat(u8.alignment());
+    },
+    /**
+     * Decode one signature response from an aligned value, consuming it field
+     * by field.
+     *
+     * @param value - Mutable aligned value cursor; pass a copy.
+     * @returns The decoded record.
+     */
+    fromValue(value) {
+        return {
+            bigRx: bytes32.fromValue(value),
+            bigRy: bytes32.fromValue(value),
+            s: bytes32.fromValue(value),
+            recoveryId: u8.fromValue(value),
+        };
+    },
+    /**
+     * Encode a signature response into its aligned on-ledger representation.
+     *
+     * @param record - The record to encode.
+     * @returns The aligned value, fields concatenated in declaration order.
+     */
+    toValue(record) {
+        return bytes32
+            .toValue(record.bigRx)
+            .concat(bytes32.toValue(record.bigRy))
+            .concat(bytes32.toValue(record.s))
+            .concat(u8.toValue(record.recoveryId));
+    },
+};
+/**
+ * Hand-composed descriptor for {@link SignetResponseKey} — the map key of
+ * the signature response log. Field order (count, then requestId) must match
+ * the Compact struct.
+ */
+export const signetResponseKeyType = {
+    /** @returns Compound alignment of the struct's fields in declaration order. */
+    alignment() {
+        return u64.alignment().concat(requestIdType.alignment());
+    },
+    /**
+     * Decode one key from an aligned value, consuming it field by field.
+     *
+     * @param value - Mutable aligned value cursor; pass a copy.
+     * @returns The decoded composite key.
+     */
+    fromValue(value) {
+        return {
+            count: u64.fromValue(value),
+            requestId: requestIdType.fromValue(value),
+        };
+    },
+    /**
+     * Encode a key into its aligned on-ledger representation.
+     *
+     * @param key - The composite key to encode.
+     * @returns The aligned value, fields concatenated in declaration order.
+     */
+    toValue(key) {
+        return u64.toValue(key.count).concat(requestIdType.toValue(key.requestId));
+    },
+};
+/**
+ * Hand-composed descriptor for {@link RespondBidirectional}. Field
+ * order (serializedOutput, outputLen, pk, announcement, response) must match
+ * the Compact struct.
+ */
+export const respondBidirectionalType = {
+    /** @returns Compound alignment of the struct's fields in declaration order. */
+    alignment() {
+        return bytes128
+            .alignment()
+            .concat(u8.alignment())
+            .concat(CompactTypeJubjubPoint.alignment())
+            .concat(CompactTypeJubjubPoint.alignment())
+            .concat(CompactTypeField.alignment());
+    },
+    /**
+     * Decode one attestation record from an aligned value, consuming it field
+     * by field.
+     *
+     * @param value - Mutable aligned value cursor; pass a copy.
+     * @returns The decoded record.
+     */
+    fromValue(value) {
+        return {
+            serializedOutput: bytes128.fromValue(value),
+            outputLen: u8.fromValue(value),
+            pk: CompactTypeJubjubPoint.fromValue(value),
+            announcement: CompactTypeJubjubPoint.fromValue(value),
+            response: CompactTypeField.fromValue(value),
+        };
+    },
+    /**
+     * Encode an attestation record into its aligned on-ledger representation.
+     *
+     * @param record - The record to encode.
+     * @returns The aligned value, fields concatenated in declaration order.
+     */
+    toValue(record) {
+        return bytes128
+            .toValue(record.serializedOutput)
+            .concat(u8.toValue(record.outputLen))
+            .concat(CompactTypeJubjubPoint.toValue(record.pk))
+            .concat(CompactTypeJubjubPoint.toValue(record.announcement))
+            .concat(CompactTypeField.toValue(record.response));
+    },
+};
+/**
+ * Build the {@link SignatureResponseIndex} key for a `(requestId, count)`
+ * pair — the composite Compact key flattened to a string so it works as a JS
+ * `Map` key.
+ *
+ * @param id - The request id the response answers, in canonical hex form.
+ * @param count - 0-based post count within that request.
+ * @returns `"<hexRequestId>:<count>"`.
+ */
+export function signetResponseIndexKey(id, count) {
+    return `${id}:${count}`;
+}
+/**
+ * MPC-/client-style read: parse the signet contract's ledger fields out of
+ * raw contract state by field position alone — no compiled contract, no
+ * generated `ledger()`, only the signet contract layout convention and the
+ * canonical descriptors above.
+ *
+ * @param raw - Raw contract state, e.g. `queryContractState(address).data`
+ *   from the indexer or `ctx.currentQueryContext.state` from the simulator.
+ * @returns The decoded {@link SignetContractLedger}.
+ * @throws Error if a field is missing or has the wrong state-value shape.
+ */
+export function readSignetContractLedgerFromState(raw) {
+    const counterMap = signetFieldNode(raw, SIGNATURE_RESPONSE_COUNTER_INDEX_FIELD).asMap();
+    if (counterMap === undefined) {
+        throw new Error(`Ledger field ${SIGNATURE_RESPONSE_COUNTER_INDEX_FIELD} is not a Map`);
+    }
+    const signatureResponseCounterIndex = new Map();
+    for (const key of counterMap.keys()) {
+        // fromValue consumes its input, so hand each descriptor a copy.
+        const requestId = requestIdType.fromValue([...key.value]);
+        // A Counter is stored as a plain u64 cell.
+        const cell = counterMap.get(key)?.asCell();
+        if (cell === undefined)
+            continue;
+        signatureResponseCounterIndex.set(requestIdHex(requestId), u64.fromValue([...cell.value]));
+    }
+    const responseMap = signetFieldNode(raw, SIGNATURE_RESPONSE_INDEX_FIELD).asMap();
+    if (responseMap === undefined) {
+        throw new Error(`Ledger field ${SIGNATURE_RESPONSE_INDEX_FIELD} is not a Map`);
+    }
+    const signatureResponseIndex = new Map();
+    for (const key of responseMap.keys()) {
+        const responseKey = signetResponseKeyType.fromValue([...key.value]);
+        const cell = responseMap.get(key)?.asCell();
+        if (cell === undefined)
+            continue;
+        signatureResponseIndex.set(signetResponseIndexKey(requestIdHex(responseKey.requestId), responseKey.count), signatureResponseType.fromValue([...cell.value]));
+    }
+    const respondBidirectionalMap = signetFieldNode(raw, RESPOND_BIDIRECTIONAL_INDEX_FIELD).asMap();
+    if (respondBidirectionalMap === undefined) {
+        throw new Error(`Ledger field ${RESPOND_BIDIRECTIONAL_INDEX_FIELD} is not a Map`);
+    }
+    const respondBidirectionalIndex = new Map();
+    for (const key of respondBidirectionalMap.keys()) {
+        const requestId = requestIdType.fromValue([...key.value]);
+        const cell = respondBidirectionalMap.get(key)?.asCell();
+        if (cell === undefined)
+            continue;
+        respondBidirectionalIndex.set(requestIdHex(requestId), respondBidirectionalType.fromValue([...cell.value]));
+    }
+    const hashCell = signetFieldNode(raw, MPC_PUB_KEY_HASH_FIELD).asCell();
+    if (hashCell === undefined) {
+        throw new Error(`Ledger field ${MPC_PUB_KEY_HASH_FIELD} is not a Cell`);
+    }
+    const mpcPubKeyHash = bytes32.fromValue([...hashCell.value]);
+    return {
+        signatureResponseCounterIndex,
+        signatureResponseIndex,
+        respondBidirectionalIndex,
+        mpcPubKeyHash,
+    };
+}
+//# sourceMappingURL=signet-contract-state-reader.js.map

package/dist/signet-contract-state-reader.js.map

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

package/dist/signet-event-observer.d.ts

@@ -0,0 +1,102 @@
+import type { ContractEvent, ContractEventQueryFilter, PublicDataProvider } from "@midnight-ntwrk/midnight-js-types";
+import { type SignetMiscEventCodec } from "./signet-events.ts";
+/** Default gap between polls of the indexer's event stream. */
+export declare const DEFAULT_EVENT_POLL_INTERVAL_MS = 3000;
+/**
+ * The least of midnight-js's `PublicDataProvider` the event path needs: read a
+ * contract's events, and (optionally) stream them live. Declared structurally
+ * so tests can satisfy it with a plain stub; any full `PublicDataProvider`
+ * (e.g. `indexerPublicDataProvider`) is assignable to it.
+ */
+export interface SignetEventSource {
+    /**
+     * Point-in-time read of a contract's events matching `filter`.
+     *
+     * @param filter - The event filter; `contractAddress` is required, an empty
+     *   `types` array is rejected (omit for all).
+     * @returns The matching events, in ascending indexer-id order.
+     */
+    queryContractEvents(filter: ContractEventQueryFilter): Promise<ContractEvent[]>;
+    /**
+     * Optional live stream, for a future push path. Typed off
+     * `PublicDataProvider` so a full provider stays assignable; the observer's
+     * default path polls {@link queryContractEvents}.
+     */
+    contractEventsObservable?: PublicDataProvider["contractEventsObservable"];
+}
+/** Everything a {@link SignetEventObserver} needs. */
+export interface SignetEventObserverConfig<T> {
+    /** Address of the central signet contract whose events to watch. */
+    readonly signetContractAddress: string;
+    /** Source of contract events, e.g. midnight-js's `indexerPublicDataProvider`. */
+    readonly source: SignetEventSource;
+    /**
+     * Which signet event kind to surface: the `Misc.name` tag to filter on and
+     * the payload decoder, e.g. `signBidirectionalEventCodec` or
+     * `signatureRespondedEventCodec` (signet-events.ts).
+     */
+    readonly codec: SignetMiscEventCodec<T>;
+    /**
+     * Durable resume floor: only events with `id >= fromEventId` are considered
+     * (the in-memory cursor of a prior run, persisted across restarts so nothing
+     * is missed or replayed). Defaults to 0 — the start of the event stream.
+     */
+    readonly fromEventId?: number;
+    /** Poll cadence for {@link SignetEventObserver.watch}; default {@link DEFAULT_EVENT_POLL_INTERVAL_MS}. */
+    readonly pollIntervalMs?: number;
+}
+/**
+ * Resolve after `ms`, or immediately once `signal` aborts. Used to space out
+ * polls without wedging a shutdown.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Watches one signet contract's `Misc` events and surfaces the notifications
+ * of ONE kind among them (the codec's name tag), decoded and in ascending
+ * indexer-id order. A single decode failure is logged and skipped — one
+ * malformed event never stalls the stream.
+ */
+export declare class SignetEventObserver<T> {
+    private readonly signetContractAddress;
+    private readonly source;
+    private readonly codec;
+    private readonly fromEventId;
+    private readonly pollIntervalMs;
+    /**
+     * @param config - The signet contract, event source, codec, and resume floor.
+     */
+    constructor(config: SignetEventObserverConfig<T>);
+    /** The `Misc` filter for the watched signet contract. */
+    private filter;
+    /**
+     * Every currently-visible notification of the codec's kind at or after the
+     * resume floor, each paired with its indexer cursor id, ascending by id.
+     * Non-`Misc` events, other name tags, and decode failures are dropped
+     * (failures logged).
+     */
+    private scan;
+    /**
+     * One-shot: every notification of the codec's kind currently visible at or
+     * after the resume floor, in id order. The polling feeds
+     * ({@link SignetRequestFeed}, `SignetResponseFeed`) re-scan through this
+     * each cycle (so a not-yet-indexed write is retried); it does NOT advance a
+     * cursor — the feeds dedupe by content instead.
+     *
+     * @returns The decoded notifications, ascending by indexer id.
+     */
+    currentEvents(): Promise<T[]>;
+    /**
+     * Live stream: poll the event source forever, yielding each notification
+     * exactly once in id order — nothing at or below the last yielded id is
+     * re-emitted (the cursor advances as `id + 1`, matching the indexer's
+     * resume convention). Runs until `opts.signal` aborts.
+     *
+     * @param opts.signal - Abort to stop the stream (between polls or on the next yield).
+     * @yields Each decoded notification once, ascending by indexer id.
+     */
+    watch(opts?: {
+        signal?: AbortSignal;
+    }): AsyncIterableIterator<T>;
+}
+export { sleep as sleepUnlessAborted };
+//# sourceMappingURL=signet-event-observer.d.ts.map

package/dist/signet-event-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signet-event-observer.d.ts","sourceRoot":"","sources":["../src/signet-event-observer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAE5B,+DAA+D;AAC/D,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAChF;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,kBAAkB,CAAC,0BAA0B,CAAC,CAAC;CAC3E;AAED,sDAAsD;AACtD,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,oEAAoE;IACpE,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,0GAA0G;IAC1G,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;GAGG;AACH,iBAAS,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAa9D;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB,CAAC,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC;;OAEG;gBACS,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;IAQhD,yDAAyD;IACzD,OAAO,CAAC,MAAM;IAId;;;;;OAKG;YACW,IAAI;IAuBlB;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAInC;;;;;;;;OAQG;IACI,KAAK,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,qBAAqB,CAAC,CAAC,CAAC;CAaxE;AAED,OAAO,EAAE,KAAK,IAAI,kBAAkB,EAAE,CAAC"}