@sig-net/midnight 0.0.1 → 0.0.2

package/src/signet-events.ts

@@ -1,337 +0,0 @@
-// Off-chain codecs for the event notifications the central signet contract
-// emits (Signet.compact structs wrapped in stdlib `Misc { name, payload }`
-// events — see packages/xcontract-events/knowledge-base/events.md), one per
-// direction of the MPC round trip:
-//   - SignBidirectionalEvent: the MPC watches these to discover WHEN a
-//     request was stored and WHERE to read it. Attribution is re-established
-//     by reading the request from the named caller's own authenticated ledger
-//     (see signet-request-resolver.ts and
-//     knowledge-base/caller-attribution.md); a field inside the event is not
-//     trustworthy (a Midnight contract cannot see its caller — gotcha #21).
-//   - SignatureRespondedEvent: the requesting client watches these to learn a
-//     signature response was posted, then reads the post back from the
-//     response log and verifies the signature off-chain (the log is
-//     unauthenticated — see signet-response-feed.ts).
-//   - RespondBidirectionalEvent: the requesting client watches these to learn
-//     the MPC's attestation of a request's remote execution landed, then reads
-//     the record back from the respond-bidirectional index — no off-chain
-//     verification, the contract authenticated it in-circuit at post time.
-// In every case the event is a notification only — never the source of truth.
-//
-// These are the event-side twins of the Compact structs — each MUST stay in
-// lockstep with its struct in Signet.compact (field order and widths). The
-// byte layouts are pinned by the golden e2e tests against a live indexer.
-
-import { bytesToHex, requestIdHex, type RequestIdHex } from "./signet-requests.ts";
-
-/**
- * The `Misc` event `name` tag the signet contract emits alongside the
- * serialized {@link SignBidirectionalEvent} payload (Compact:
- * `pad(32, "SignBidirectionalEvent")`). Observers filter on this ascii tag.
- */
-export const SIGN_BIDIRECTIONAL_EVENT_TAG = "SignBidirectionalEvent";
-
-/**
- * Byte width of the leading `version` tag (Compact `Uint<8>`). The event is a
- * FROZEN `{ version, payload }` envelope (see `SignBidirectionalEvent` in
- * Signet.compact): `version` is at offset 0 and every V1 field is shifted one
- * byte to make room for it.
- */
-const VERSION_BYTES = 1;
-
-/** The only payload interpretation this decoder understands today. */
-const SUPPORTED_VERSION = 1;
-
-/** Byte width of the `callerAddress` field (Compact `ContractAddress` = 32 raw bytes). */
-const CALLER_ADDRESS_BYTES = 32;
-
-/** Byte width of the `requestId` field (Compact `Bytes<32>`). */
-const REQUEST_ID_BYTES = 32;
-
-/** Offset of the V1 `callerAddress` in the outer payload (after the version byte). */
-const CALLER_ADDRESS_OFFSET = VERSION_BYTES;
-
-/** Offset of the V1 `requestId` (after version + callerAddress). */
-const REQUEST_ID_OFFSET = CALLER_ADDRESS_OFFSET + CALLER_ADDRESS_BYTES;
-
-/** Offset of the V1 `signBidirectionalRequestsIndexField` (after version + caller + requestId). */
-const REQUESTS_INDEX_FIELD_OFFSET = REQUEST_ID_OFFSET + REQUEST_ID_BYTES;
-
-/**
- * Minimum serialized length of a V1 event: `version` (1) + `callerAddress` (32)
- * + `requestId` (32) + `signBidirectionalRequestsIndexField` (1) = 66.
- * `serialize<T,256>` right-pads to 256, so a real payload is longer; this is the
- * floor the decoder needs.
- */
-const MIN_PAYLOAD_BYTES = REQUESTS_INDEX_FIELD_OFFSET + 1;
-
-/**
- * TS twin of the Compact `SignBidirectionalEvent` *event* struct (not the
- * request record). The notification the signet contract emits so the MPC knows
- * a {@link SignBidirectionalRequest} was stored — and, crucially, WHERE to read
- * the authenticated copy of it.
- */
-export interface SignBidirectionalEvent {
-  /**
-   * The frozen envelope's `version` tag (Compact `Uint<8>`). Selects how the
-   * opaque payload was interpreted; this decoder only understands version 1.
-   */
-  version: number;
-  /**
-   * Address of the contract whose request index holds the request (Compact
-   * `ContractAddress`, rendered as lowercase hex, no `0x` prefix — directly
-   * usable as a `queryContractState` argument). The MPC reads the request from
-   * THIS contract's authenticated state; the event field itself confers no
-   * authority.
-   */
-  callerAddress: string;
-  /** Which request in {@link callerAddress}'s index this notification is about. */
-  requestId: RequestIdHex;
-  /**
-   * Ledger field position of the `Map<RequestId, SignBidirectionalRequest>`
-   * request index in {@link callerAddress} (the signet layout convention puts
-   * it at field 0, but the event carries it so the reader never assumes).
-   */
-  requestsIndexField: number;
-}
-
-/**
- * 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: string): string {
-  return hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
-}
-
-/**
- * Decode a hex string (as the indexer returns `Misc.name` / `Misc.payload`)
- * into bytes.
- *
- * @param hex - Hex digits, with or without a `0x` prefix.
- * @returns The decoded bytes.
- */
-export function hexToBytes(hex: string): Uint8Array {
-  const digits = stripHexPrefix(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;
-}
-
-/**
- * The ascii tag of a zero-padded `Bytes<N>` name (the Compact `pad(N, "text")`
- * convention): decode the hex, then trim the trailing NUL padding.
- *
- * @param nameHex - The indexer's hex-encoded `Misc.name`.
- * @returns The trimmed ascii tag, e.g. `"SignBidirectionalEvent"`.
- */
-export function eventNameTag(nameHex: string): string {
-  return new TextDecoder().decode(hexToBytes(nameHex)).replace(/\0+$/, "");
-}
-
-/**
- * Decode a `Misc` payload (`serialize<SignBidirectionalEvent, 256>`) into the
- * struct. The event is a frozen `{ version: Uint<8>, payload: Bytes<224> }`
- * envelope, and V1 packs the concrete fields into that inner payload with
- * `serialize<SignBidirectionalEventV1Payload, 224>`. `serialize<T,N>` lays
- * fields out in declaration order, packed at the front and right-zero-padded
- * (see knowledge-base/events.md), so in the outer 256-byte payload:
- * `version = payload[0]`, then everything shifts one byte —
- * `callerAddress = payload[1..33]`, `requestId = payload[33..65]`,
- * `requestsIndexField = payload[65]`.
- *
- * The byte layout is pinned against a live indexer by the golden e2e test —
- * `callerAddress` is the V1 payload's FIRST field, a different position than the
- * DepositEvent precedent's `caller`, so do not assume it without that test.
- *
- * Fails closed on an unrecognised `version`: a future payload layout adds a
- * branch here (and, off-chain, a V{N} decoder) rather than silently
- * misinterpreting bytes under the V1 offsets.
- *
- * @param payload - The decoded (raw bytes) `Misc.payload`.
- * @returns The decoded event notification.
- * @throws Error if the payload is shorter than the fixed fields require, or its
- *   `version` is not one this decoder understands.
- */
-export function decodeSignBidirectionalEvent(
-  payload: Uint8Array,
-): SignBidirectionalEvent {
-  if (payload.length < MIN_PAYLOAD_BYTES) {
-    throw new Error(
-      `SignBidirectionalEvent payload is ${payload.length} bytes — fewer than ` +
-        `the ${MIN_PAYLOAD_BYTES} its fixed fields need`,
-    );
-  }
-  const version = payload[0];
-  if (version !== SUPPORTED_VERSION) {
-    throw new Error(
-      `SignBidirectionalEvent version ${version} is not supported ` +
-        `(this decoder understands version ${SUPPORTED_VERSION})`,
-    );
-  }
-  const callerAddress = bytesToHex(
-    payload.slice(CALLER_ADDRESS_OFFSET, CALLER_ADDRESS_OFFSET + CALLER_ADDRESS_BYTES),
-  );
-  const requestId = requestIdHex(
-    payload.slice(REQUEST_ID_OFFSET, REQUEST_ID_OFFSET + REQUEST_ID_BYTES),
-  );
-  const requestsIndexField = payload[REQUESTS_INDEX_FIELD_OFFSET];
-  return { version, callerAddress, requestId, requestsIndexField };
-}
-
-/**
- * The `Misc` event `name` tag the signet contract emits alongside the
- * serialized {@link SignatureRespondedEvent} payload (Compact:
- * `pad(32, "SignatureRespondedEvent")`). Observers filter on this ascii tag.
- */
-export const SIGNATURE_RESPONDED_EVENT_TAG = "SignatureRespondedEvent";
-
-/** Byte width of the `count` field (Compact `Uint<64>` = 8 bytes, little-endian). */
-const COUNT_BYTES = 8;
-
-/**
- * Minimum serialized length of a {@link SignatureRespondedEvent}: `requestId`
- * (32) + `count` (8). `serialize<T,256>` right-pads to 256, so a real payload
- * is longer; this is the floor the decoder needs.
- */
-const MIN_RESPONDED_PAYLOAD_BYTES = REQUEST_ID_BYTES + COUNT_BYTES;
-
-/**
- * TS twin of the Compact `SignatureRespondedEvent` *event* struct (not the
- * {@link SignatureResponse} record it announces). The notification the signet
- * contract emits from `postSignatureResponse` so the requesting client knows
- * a response post landed — and WHERE in the response log to read it back.
- * A ping only: the log is unauthenticated, so the client must verify the
- * post's signature off-chain (see signet-response-feed.ts).
- */
-export interface SignatureRespondedEvent {
-  /** Which request the posted response answers. */
-  requestId: RequestIdHex;
-  /**
-   * 0-based position of the post in {@link requestId}'s response log — the
-   * `count` half of the `SignetResponseKey` it is stored under.
-   */
-  count: bigint;
-}
-
-/**
- * Decode a `Misc` payload (`serialize<SignatureRespondedEvent, 256>`) into
- * the struct. Layout per knowledge-base/events.md: fields in declaration
- * order packed at the front — `requestId = payload[0..32]` (raw bytes),
- * `count = payload[32..40]` (Uint<64>, LITTLE-endian) — right-zero-padded.
- *
- * @param payload - The decoded (raw bytes) `Misc.payload`.
- * @returns The decoded event notification.
- * @throws Error if the payload is shorter than the fixed fields require.
- */
-export function decodeSignatureRespondedEvent(
-  payload: Uint8Array,
-): SignatureRespondedEvent {
-  if (payload.length < MIN_RESPONDED_PAYLOAD_BYTES) {
-    throw new Error(
-      `SignatureRespondedEvent payload is ${payload.length} bytes — fewer than ` +
-        `the ${MIN_RESPONDED_PAYLOAD_BYTES} its fixed fields need`,
-    );
-  }
-  const requestId = requestIdHex(payload.slice(0, REQUEST_ID_BYTES));
-  let count = 0n;
-  for (let i = REQUEST_ID_BYTES + COUNT_BYTES - 1; i >= REQUEST_ID_BYTES; i--) {
-    count = (count << 8n) | BigInt(payload[i]);
-  }
-  return { requestId, count };
-}
-
-/**
- * The `Misc` event `name` tag the signet contract emits alongside the
- * serialized {@link RespondBidirectionalEvent} payload (Compact:
- * `pad(32, "RespondBidirectionalEvent")`). Observers filter on this ascii tag.
- */
-export const RESPOND_BIDIRECTIONAL_EVENT_TAG = "RespondBidirectionalEvent";
-
-/**
- * Minimum serialized length of a {@link RespondBidirectionalEvent}:
- * `requestId` (32). `serialize<T,256>` right-pads to 256, so a real payload
- * is longer; this is the floor the decoder needs.
- */
-const MIN_RESPOND_BIDIRECTIONAL_PAYLOAD_BYTES = REQUEST_ID_BYTES;
-
-/**
- * TS twin of the Compact `RespondBidirectionalEvent` *event* struct (not the
- * `RespondBidirectional` record it announces). The notification the signet
- * contract emits from `postRespondBidirectional` when the MPC's attestation
- * of a request's remote execution lands in the respond-bidirectional index —
- * at most once per request (one authenticated slot, first valid write wins).
- * A ping only, but unlike {@link SignatureRespondedEvent} no off-chain
- * verification follows the read-back: the contract verified the attestation
- * in-circuit at post time, so the stored record is authentic by construction.
- */
-export interface RespondBidirectionalEvent {
-  /** Which request the stored attestation answers. */
-  requestId: RequestIdHex;
-}
-
-/**
- * Decode a `Misc` payload (`serialize<RespondBidirectionalEvent, 256>`) into
- * the struct. Layout per knowledge-base/events.md: fields in declaration
- * order packed at the front — `requestId = payload[0..32]` (raw bytes) —
- * right-zero-padded.
- *
- * @param payload - The decoded (raw bytes) `Misc.payload`.
- * @returns The decoded event notification.
- * @throws Error if the payload is shorter than the fixed fields require.
- */
-export function decodeRespondBidirectionalEvent(
-  payload: Uint8Array,
-): RespondBidirectionalEvent {
-  if (payload.length < MIN_RESPOND_BIDIRECTIONAL_PAYLOAD_BYTES) {
-    throw new Error(
-      `RespondBidirectionalEvent payload is ${payload.length} bytes — fewer than ` +
-        `the ${MIN_RESPOND_BIDIRECTIONAL_PAYLOAD_BYTES} its fixed fields need`,
-    );
-  }
-  return { requestId: requestIdHex(payload.slice(0, REQUEST_ID_BYTES)) };
-}
-
-/**
- * One signet event kind as an observer consumes it: the `Misc.name` ascii tag
- * to filter on plus the payload decoder. A `SignetEventObserver` is
- * instantiated with one of these — see {@link signBidirectionalEventCodec},
- * {@link signatureRespondedEventCodec}, and
- * {@link respondBidirectionalEventCodec}.
- */
-export interface SignetMiscEventCodec<T> {
-  /** The ascii `Misc.name` tag identifying this event kind. */
-  readonly tag: string;
-  /**
-   * Decode a raw `Misc.payload` into the typed notification.
-   *
-   * @param payload - The decoded (raw bytes) `Misc.payload`.
-   * @returns The decoded event notification.
-   * @throws Error if the payload is malformed.
-   */
-  decode(payload: Uint8Array): T;
-}
-
-/** The {@link SignetMiscEventCodec} of {@link SignBidirectionalEvent} notifications. */
-export const signBidirectionalEventCodec: SignetMiscEventCodec<SignBidirectionalEvent> =
-  {
-    tag: SIGN_BIDIRECTIONAL_EVENT_TAG,
-    decode: decodeSignBidirectionalEvent,
-  };
-
-/** The {@link SignetMiscEventCodec} of {@link SignatureRespondedEvent} notifications. */
-export const signatureRespondedEventCodec: SignetMiscEventCodec<SignatureRespondedEvent> =
-  {
-    tag: SIGNATURE_RESPONDED_EVENT_TAG,
-    decode: decodeSignatureRespondedEvent,
-  };
-
-/** The {@link SignetMiscEventCodec} of {@link RespondBidirectionalEvent} notifications. */
-export const respondBidirectionalEventCodec: SignetMiscEventCodec<RespondBidirectionalEvent> =
-  {
-    tag: RESPOND_BIDIRECTIONAL_EVENT_TAG,
-    decode: decodeRespondBidirectionalEvent,
-  };

package/src/signet-response-feed.ts

@@ -1,325 +0,0 @@
-// The requesting client's entry point for discovering MPC signature responses
-// by event observation: watch the central signet contract's
-// SignatureRespondedEvent notifications, and when one announces a post for a
-// request the client cares about, read the response log back and verify every
-// post against the request — the response-direction mirror of
-// signet-request-feed.ts. The event is only the TRIGGER for a state read; the
-// verdicts come from the ledger via the same SignetRequestResponseReader all
-// other consumers use, so an event/state indexing skew in either direction is
-// tolerated (a post visible in state before its event is still yielded; an
-// event whose write has not indexed yet is retried next cycle).
-//
-// Trust model (see "Signet Contract Ledger Layout" in Signet.compact): the
-// response log is UNAUTHENTICATED — neither the event nor the stored record
-// confers authenticity. Only the off-chain signature verification does, which
-// is why the feed yields per-post VERDICTS rather than raw responses.
-//
-// The MPC's OTHER response kind — the respond-bidirectional attestation of a
-// request's remote execution — gets the same event-gated treatment via
-// SignetRespondBidirectionalFeed (RespondBidirectionalEvent → index read),
-// but with the opposite trust model: the signet contract verified the
-// attestation IN-CIRCUIT at post time, so the feed yields the stored record
-// itself, no verdicts.
-
-import {
-  SignetEventObserver,
-  sleepUnlessAborted,
-  type SignetEventSource,
-} from "./signet-event-observer.ts";
-import {
-  respondBidirectionalEventCodec,
-  signatureRespondedEventCodec,
-  type RespondBidirectionalEvent,
-  type SignatureRespondedEvent,
-} from "./signet-events.ts";
-import {
-  readSignetContractLedgerFromState,
-  type RespondBidirectional,
-} from "./signet-contract-state-reader.ts";
-import {
-  SignetRequestResponseReader,
-  type SignatureResponseVerdict,
-  type SignetPublicStateSource,
-} from "./signet-request-response-reader.ts";
-import type {
-  RequestIdHex,
-  SignBidirectionalRequest,
-} from "./signet-requests.ts";
-
-/** Default gap between poll cycles of {@link SignetResponseFeed.verdicts}. */
-export const DEFAULT_RESPONSE_FEED_POLL_INTERVAL_MS = 3000;
-
-/** Everything a {@link SignetResponseFeed} needs. */
-export interface SignetResponseFeedConfig {
-  /** Address of the central signet contract whose events and response log to watch. */
-  readonly signetContractAddress: string;
-  /** Address of the signet-compliant requester contract holding the request records (e.g. the vault). */
-  readonly requesterContractAddress: string;
-  /**
-   * Source of BOTH events and raw contract state — a full
-   * `indexerPublicDataProvider` satisfies both halves.
-   */
-  readonly source: SignetEventSource & SignetPublicStateSource;
-  /** Durable resume floor for the underlying observer (see {@link SignetEventObserverConfig.fromEventId}). */
-  readonly fromEventId?: number;
-  /** Poll cadence for {@link SignetResponseFeed.verdicts}; default {@link DEFAULT_RESPONSE_FEED_POLL_INTERVAL_MS}. */
-  readonly pollIntervalMs?: number;
-}
-
-/**
- * The event-driven signature response feed. Composes a
- * {@link SignetEventObserver} of {@link SignatureRespondedEvent} notifications
- * (discovery) with a {@link SignetRequestResponseReader} (verification),
- * yielding one {@link SignatureResponseVerdict} per posted response, in count
- * order, each exactly once per feed lifetime. Consumers act on the first
- * valid verdict and surface the rejected ones as they see fit — the feed,
- * like the reader, never logs.
- */
-export class SignetResponseFeed {
-  private readonly observer: SignetEventObserver<SignatureRespondedEvent>;
-  private readonly reader: SignetRequestResponseReader;
-  private readonly pollIntervalMs: number;
-
-  // Post counts already yielded, per request. NOT a trust boundary (the
-  // verdicts are) — just an exactly-once gate so a post is not re-judged.
-  private readonly yielded = new Map<RequestIdHex, Set<bigint>>();
-
-  /**
-   * @param config - The contract pair, combined event/state source, and
-   *   resume floor.
-   */
-  constructor(config: SignetResponseFeedConfig) {
-    this.observer = new SignetEventObserver({
-      signetContractAddress: config.signetContractAddress,
-      source: config.source,
-      codec: signatureRespondedEventCodec,
-      fromEventId: config.fromEventId,
-      pollIntervalMs: config.pollIntervalMs,
-    });
-    this.reader = new SignetRequestResponseReader({
-      requesterContractAddress: config.requesterContractAddress,
-      signetContractAddress: config.signetContractAddress,
-      publicDataProvider: config.source,
-    });
-    this.pollIntervalMs =
-      config.pollIntervalMs ?? DEFAULT_RESPONSE_FEED_POLL_INTERVAL_MS;
-  }
-
-  /** The yielded-count set for `requestId`, created on first use. */
-  private yieldedCounts(requestId: RequestIdHex): Set<bigint> {
-    let counts = this.yielded.get(requestId);
-    if (counts === undefined) {
-      counts = new Set();
-      this.yielded.set(requestId, counts);
-    }
-    return counts;
-  }
-
-  /**
-   * One-shot: the verdicts on every response post for `requestId` not yielded
-   * before, in count order. The response log is only read when a currently-
-   * visible event announces a post this feed has not yielded yet — no new
-   * event, no state query. Ledger posts the read then surfaces beyond the
-   * announced ones are yielded too (events are the trigger, the ledger is the
-   * source of truth), and a post whose event is visible but whose write has
-   * not indexed yet is simply retried next cycle.
-   *
-   * @param requestId - The request whose response posts to judge.
-   * @param expectedSigner - The EVM address (0x hex, any case) the genuine
-   *   response must be signed by — the requester's MPC-derived address.
-   * @returns The newly-judged verdicts this cycle (possibly empty).
-   * @throws Error when either contract has no state, the request is not on
-   *   the requester's ledger, or the responses ledger is inconsistent.
-   */
-  async poll(
-    requestId: RequestIdHex,
-    expectedSigner: string,
-  ): Promise<SignatureResponseVerdict[]> {
-    const events = await this.observer.currentEvents();
-    const counts = this.yieldedCounts(requestId);
-    const announcesNew = events.some(
-      (event) => event.requestId === requestId && !counts.has(event.count),
-    );
-    if (!announcesNew) {
-      return [];
-    }
-    const { verdicts } = await this.reader.getVerifiedSignatureResponse(
-      requestId,
-      expectedSigner,
-    );
-    const fresh = verdicts.filter((verdict) => !counts.has(verdict.count));
-    for (const verdict of fresh) {
-      counts.add(verdict.count);
-    }
-    return fresh;
-  }
-
-  /**
-   * Live stream: poll + sleep, yielding the verdict on each posted response
-   * exactly once, in count order, until `opts.signal` aborts. The natural
-   * consumption is to warn on each rejected verdict and act on the first
-   * valid one (see the cli's poll-signature-response command).
-   *
-   * @param requestId - The request whose response posts to judge.
-   * @param expectedSigner - The EVM address (0x hex, any case) the genuine
-   *   response must be signed by — the requester's MPC-derived address.
-   * @param opts.signal - Abort to stop the stream.
-   * @yields Each post's verdict, in discovery order.
-   * @throws Error when either contract has no state, the request is not on
-   *   the requester's ledger, or the responses ledger is inconsistent.
-   */
-  async *verdicts(
-    requestId: RequestIdHex,
-    expectedSigner: string,
-    opts?: { signal?: AbortSignal },
-  ): AsyncIterableIterator<SignatureResponseVerdict> {
-    while (!opts?.signal?.aborted) {
-      const batch = await this.poll(requestId, expectedSigner);
-      for (const verdict of batch) yield verdict;
-      if (opts?.signal?.aborted) break;
-      await sleepUnlessAborted(this.pollIntervalMs, opts?.signal);
-    }
-  }
-
-  /**
-   * The request record a verdict's response answers, read through the feed's
-   * own reader (cached after the first fetch — free after any {@link poll}
-   * that reached verification). What a consumer needs to assemble the signed
-   * transaction from a valid verdict via
-   * `signBidirectionalRequestToSignedEVMTransaction`.
-   *
-   * @param requestId - The request id to look up.
-   * @returns The stored request record.
-   * @throws Error when the requester contract has no state or holds no
-   *   request under `requestId`.
-   */
-  async getSignatureRequest(
-    requestId: RequestIdHex,
-  ): Promise<SignBidirectionalRequest> {
-    return this.reader.getSignatureRequest(requestId);
-  }
-}
-
-/** Everything a {@link SignetRespondBidirectionalFeed} needs. */
-export interface SignetRespondBidirectionalFeedConfig {
-  /**
-   * Address of the central signet contract whose events and
-   * respond-bidirectional index to watch. Attestations live entirely on the
-   * signet contract, so — unlike {@link SignetResponseFeedConfig} — no
-   * requester contract address is needed.
-   */
-  readonly signetContractAddress: string;
-  /**
-   * Source of BOTH events and raw contract state — a full
-   * `indexerPublicDataProvider` satisfies both halves.
-   */
-  readonly source: SignetEventSource & SignetPublicStateSource;
-  /** Durable resume floor for the underlying observer (see {@link SignetEventObserverConfig.fromEventId}). */
-  readonly fromEventId?: number;
-  /** Poll cadence for {@link SignetRespondBidirectionalFeed.attestation}; default {@link DEFAULT_RESPONSE_FEED_POLL_INTERVAL_MS}. */
-  readonly pollIntervalMs?: number;
-}
-
-/**
- * The event-driven respond-bidirectional feed: composes a
- * {@link SignetEventObserver} of {@link RespondBidirectionalEvent}
- * notifications (discovery) with a read of the signet contract's
- * respond-bidirectional index (the source of truth), yielding the MPC's
- * attestation of a request's remote execution. No verdicts and no off-chain
- * verification — the signet contract verified the attestation IN-CIRCUIT at
- * post time (Schnorr over `(requestId, hash(serializedOutput, outputLen))`
- * against its sealed MPC key), so the stored record is authentic by
- * construction and there is exactly one per request (first valid write wins).
- */
-export class SignetRespondBidirectionalFeed {
-  private readonly observer: SignetEventObserver<RespondBidirectionalEvent>;
-  private readonly signetContractAddress: string;
-  private readonly source: SignetPublicStateSource;
-  private readonly pollIntervalMs: number;
-
-  // Attestation records never change once stored (one authenticated slot per
-  // request, first valid write wins), so cache them across polls.
-  private readonly attestations = new Map<RequestIdHex, RespondBidirectional>();
-
-  /**
-   * @param config - The signet contract, combined event/state source, and
-   *   resume floor.
-   */
-  constructor(config: SignetRespondBidirectionalFeedConfig) {
-    this.observer = new SignetEventObserver({
-      signetContractAddress: config.signetContractAddress,
-      source: config.source,
-      codec: respondBidirectionalEventCodec,
-      fromEventId: config.fromEventId,
-      pollIntervalMs: config.pollIntervalMs,
-    });
-    this.signetContractAddress = config.signetContractAddress;
-    this.source = config.source;
-    this.pollIntervalMs =
-      config.pollIntervalMs ?? DEFAULT_RESPONSE_FEED_POLL_INTERVAL_MS;
-  }
-
-  /**
-   * One-shot: the attestation for `requestId`, or `undefined` while none is
-   * discoverable yet. The index is only read when a currently-visible event
-   * announces `requestId`'s attestation — no event, no state query. An event
-   * whose ledger write has not indexed yet is simply retried next cycle
-   * (events are the trigger, the ledger is the source of truth).
-   *
-   * @param requestId - The request whose attestation to look for.
-   * @returns The stored attestation record, or `undefined` when its event is
-   *   not yet visible or its write not yet indexed.
-   * @throws Error when the signet contract has no state on-chain.
-   */
-  async poll(requestId: RequestIdHex): Promise<RespondBidirectional | undefined> {
-    const cached = this.attestations.get(requestId);
-    if (cached !== undefined) {
-      return cached;
-    }
-    const events = await this.observer.currentEvents();
-    if (!events.some((event) => event.requestId === requestId)) {
-      return undefined;
-    }
-    const state = await this.source.queryContractState(
-      this.signetContractAddress,
-    );
-    if (!state?.data) {
-      throw new Error(
-        `no state data found for signet contract '${this.signetContractAddress}' - is it deployed?`,
-      );
-    }
-    const record = readSignetContractLedgerFromState(
-      state.data,
-    ).respondBidirectionalIndex.get(requestId);
-    if (record === undefined) {
-      return undefined;
-    }
-    this.attestations.set(requestId, record);
-    return record;
-  }
-
-  /**
-   * Live wait: poll + sleep until `requestId`'s attestation is discoverable,
-   * and return it. Runs until `opts.signal` aborts — the caller owns the
-   * give-up policy (see the cli's poll-respond-bidirectional command).
-   *
-   * @param requestId - The request whose attestation to wait for.
-   * @param opts.signal - Abort to stop waiting.
-   * @returns The stored attestation record, or `undefined` when aborted
-   *   before one was discovered.
-   * @throws Error when the signet contract has no state on-chain.
-   */
-  async attestation(
-    requestId: RequestIdHex,
-    opts?: { signal?: AbortSignal },
-  ): Promise<RespondBidirectional | undefined> {
-    while (!opts?.signal?.aborted) {
-      const record = await this.poll(requestId);
-      if (record !== undefined) {
-        return record;
-      }
-      await sleepUnlessAborted(this.pollIntervalMs, opts?.signal);
-    }
-    return undefined;
-  }
-}