@sig-net/midnight 0.0.1 → 0.0.3

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;
-  }
-}