@sig-net/midnight 0.0.1 → 0.0.2

package/src/signet-contract-state-reader.ts

@@ -6,8 +6,9 @@
 // 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.
+// (field 3), notification registry (field 4). The generic state-tree walk
+// (RawContractState, signetFieldNode) and the shared base descriptors live in
+// signature-state-reading.ts.
 
 import {
   CompactTypeBytes,
@@ -19,6 +20,7 @@ import {
 } from "@midnight-ntwrk/compact-runtime";
 
 import {
+  bytesToHex,
   requestIdHex,
   type RequestId,
   type RequestIdHex,
@@ -43,6 +45,9 @@ 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;
 
+/** Signet contract layout: the request notification registry is ledger field 4. */
+export const SIGN_BIDIRECTIONAL_NOTIFICATION_INDEX_FIELD = 4;
+
 // ---- 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
@@ -232,6 +237,150 @@ export const respondBidirectionalType: CompactType<RespondBidirectional> = {
   },
 };
 
+/** Descriptor for the notification's packed V1 payload (`Bytes<65>`). */
+const bytes65 = new CompactTypeBytes(65);
+
+/**
+ * Raw twin of the Compact `SignBidirectionalNotification` struct as stored
+ * on-ledger: the version tag plus the still-packed 65-byte payload. Decode
+ * the payload with {@link decodeSignBidirectionalNotification}.
+ */
+export interface SignBidirectionalNotificationRecord {
+  /** Payload layout tag (Compact `Uint<8>`); 1 = the V1 layout. */
+  version: bigint;
+  /** The packed payload bytes, exactly as the registering circuit built them. */
+  payload: Uint8Array;
+}
+
+/**
+ * Hand-composed descriptor for {@link SignBidirectionalNotificationRecord}.
+ * Field order (version, payload) must match the Compact struct.
+ */
+export const signBidirectionalNotificationType: CompactType<SignBidirectionalNotificationRecord> =
+  {
+    /** @returns Compound alignment of the struct's fields in declaration order. */
+    alignment() {
+      return u8.alignment().concat(bytes65.alignment());
+    },
+    /**
+     * Decode one notification 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 {
+        version: u8.fromValue(value),
+        payload: bytes65.fromValue(value),
+      };
+    },
+    /**
+     * Encode a notification 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 u8.toValue(record.version).concat(bytes65.toValue(record.payload));
+    },
+  };
+
+/** Offset of the V1 `callerAddress` in the packed payload (`Bytes<32>` at the front). */
+const NOTIFICATION_CALLER_ADDRESS_OFFSET = 0;
+
+/** Offset of the V1 `requestId` (after the 32 callerAddress bytes). */
+const NOTIFICATION_REQUEST_ID_OFFSET = 32;
+
+/** Offset of the V1 `requestsIndexField` (after callerAddress + requestId). */
+const NOTIFICATION_REQUESTS_INDEX_FIELD_OFFSET = 64;
+
+/** The only payload interpretation {@link decodeSignBidirectionalNotification} understands today. */
+const SUPPORTED_NOTIFICATION_VERSION = 1n;
+
+/**
+ * A decoded V1 notification from the signet contract's registry: the flat
+ * pointer a client registered to tell the MPC a request was stored — and
+ * WHERE to read the authenticated copy. Never trusted on its own: the
+ * resolver authenticates by reading the request back from
+ * {@link callerAddress}'s own ledger (see signet-request-resolver.ts).
+ */
+export interface SignBidirectionalNotification {
+  /** Payload layout tag; this decoder only produces version 1. */
+  version: number;
+  /**
+   * Address of the contract whose request index holds the request, 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 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 notification carries it so the reader never assumes).
+   */
+  requestsIndexField: number;
+}
+
+/**
+ * Unpack a stored {@link SignBidirectionalNotificationRecord}'s payload by
+ * the fixed V1 offsets — the decode twin of the compiled
+ * `constructSignBidirectionalNotificationV1` circuit (byte plumbing only; the
+ * pack↔decode lockstep is pinned by the state-reader unit test that round-trips
+ * through the real circuit).
+ *
+ * Fails closed on an unrecognised `version`: a future payload layout adds a
+ * branch here rather than silently misinterpreting bytes under the V1 offsets.
+ *
+ * @param record - The raw on-ledger record.
+ * @returns The decoded flat notification.
+ * @throws Error if the record's `version` is not one this decoder understands.
+ */
+export function decodeSignBidirectionalNotification(
+  record: SignBidirectionalNotificationRecord,
+): SignBidirectionalNotification {
+  if (record.version !== SUPPORTED_NOTIFICATION_VERSION) {
+    throw new Error(
+      `SignBidirectionalNotification version ${record.version} is not supported ` +
+        `(this decoder understands version ${SUPPORTED_NOTIFICATION_VERSION})`,
+    );
+  }
+  const callerAddress = bytesToHex(
+    record.payload.slice(
+      NOTIFICATION_CALLER_ADDRESS_OFFSET,
+      NOTIFICATION_REQUEST_ID_OFFSET,
+    ),
+  );
+  const requestId = requestIdHex(
+    record.payload.slice(
+      NOTIFICATION_REQUEST_ID_OFFSET,
+      NOTIFICATION_REQUESTS_INDEX_FIELD_OFFSET,
+    ),
+  );
+  const requestsIndexField =
+    record.payload[NOTIFICATION_REQUESTS_INDEX_FIELD_OFFSET];
+  return {
+    version: Number(record.version),
+    callerAddress,
+    requestId,
+    requestsIndexField,
+  };
+}
+
+/**
+ * Plain-JS notification registry parsed out of the ledger: hex request id
+ * (the map KEY under which the notification was registered) to the raw
+ * stored record. Decode each record with
+ * {@link decodeSignBidirectionalNotification}.
+ */
+export type SignBidirectionalNotificationIndex = Map<
+  RequestIdHex,
+  SignBidirectionalNotificationRecord
+>;
+
 /**
  * Plain-JS signature response counter index parsed out of the ledger: hex
  * request id (see {@link requestIdHex}) to the number of responses posted for
@@ -271,11 +420,50 @@ export function signetResponseIndexKey(
   return `${id}:${count}`;
 }
 
+/**
+ * Read ONLY the notification registry (ledger field
+ * {@link SIGN_BIDIRECTIONAL_NOTIFICATION_INDEX_FIELD}) out of raw signet
+ * contract state — the poll-loop primitive of {@link SignetRequestFeed},
+ * which cycles frequently and has no use for the response fields.
+ *
+ * @param raw - Raw contract state, e.g. `queryContractState(address).data`
+ *   from the indexer or `ctx.currentQueryContext.state` from the simulator.
+ * @returns The registry, keyed by the hex request id each record was
+ *   registered under.
+ * @throws Error if the field is missing or is not a Map.
+ */
+export function readSignBidirectionalNotificationIndexFromState(
+  raw: RawContractState,
+): SignBidirectionalNotificationIndex {
+  const notificationMap = signetFieldNode(
+    raw,
+    SIGN_BIDIRECTIONAL_NOTIFICATION_INDEX_FIELD,
+  ).asMap();
+  if (notificationMap === undefined) {
+    throw new Error(
+      `Ledger field ${SIGN_BIDIRECTIONAL_NOTIFICATION_INDEX_FIELD} is not a Map`,
+    );
+  }
+  const index: SignBidirectionalNotificationIndex = new Map();
+  for (const key of notificationMap.keys()) {
+    // fromValue consumes its input, so hand each descriptor a copy.
+    const requestId = requestIdType.fromValue([...key.value]);
+    const cell = notificationMap.get(key)?.asCell();
+    if (cell === undefined) continue;
+    index.set(
+      requestIdHex(requestId),
+      signBidirectionalNotificationType.fromValue([...cell.value]),
+    );
+  }
+  return index;
+}
+
 /**
  * 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.
+ * (field 2), the sealed MPC attestation key hash (field 3), and the request
+ * notification registry (field 4). Together they give a poller everything
+ * the contract ever records about a request.
  */
 export interface SignetContractLedger {
   /**
@@ -299,6 +487,12 @@ export interface SignetContractLedger {
    * {@link MPC_PUB_KEY_HASH_FIELD}) posts are verified against.
    */
   mpcPubKeyHash: Uint8Array;
+  /**
+   * The request notification registry (ledger field
+   * {@link SIGN_BIDIRECTIONAL_NOTIFICATION_INDEX_FIELD}), keyed by hex
+   * request id.
+   */
+  signBidirectionalNotificationIndex: SignBidirectionalNotificationIndex;
 }
 
 /**
@@ -387,5 +581,7 @@ export function readSignetContractLedgerFromState(
     signatureResponseIndex,
     respondBidirectionalIndex,
     mpcPubKeyHash,
+    signBidirectionalNotificationIndex:
+      readSignBidirectionalNotificationIndexFromState(raw),
   };
 }

package/src/signet-request-feed.ts

@@ -1,9 +1,10 @@
-// The MPC's single entry point for discovering signature requests by event
-// observation: watch the central signet contract's notifications, resolve each
-// to an AUTHENTICATED request read from the named caller's own ledger, and
-// yield only the ones that pass the membership check. Replaces polling a
-// configured list of requester contracts — the feed discovers requesters
-// dynamically, keyed off whose authenticated state it actually read.
+// The MPC's single entry point for discovering signature requests: poll the
+// central signet contract's notification registry (ledger field 4), resolve
+// each notification to an AUTHENTICATED request read from the named caller's
+// own ledger, and yield only the ones that pass the membership check. The
+// registry is append-only with no on-ledger cursor, so the feed's in-memory
+// `yielded` set is the diff cursor: every poll enumerates the registry and
+// serves what it has not served before.
 //
 // The requester allow-list is an OPTIONAL policy filter here (drop requests
 // from contracts you choose not to serve), never a security requirement and
@@ -12,60 +13,81 @@
 // knowledge-base/caller-attribution.md).
 
 import {
-  SignetEventObserver,
-  sleepUnlessAborted,
-  type SignetEventSource,
-} from "./signet-event-observer.ts";
-import {
-  signBidirectionalEventCodec,
-  stripHexPrefix,
-  type SignBidirectionalEvent,
-} from "./signet-events.ts";
+  decodeSignBidirectionalNotification,
+  readSignBidirectionalNotificationIndexFromState,
+} from "./signet-contract-state-reader.ts";
 import {
   SignetRequestResolver,
   type ResolvedSignetRequest,
 } from "./signet-request-resolver.ts";
 import type { SignetPublicStateSource } from "./signet-request-response-reader.ts";
-import type { RequestIdHex } from "./signet-requests.ts";
+import { stripHexPrefix, type RequestIdHex } from "./signet-requests.ts";
 
 /** Default gap between poll cycles of {@link SignetRequestFeed.requests}. */
 export const DEFAULT_FEED_POLL_INTERVAL_MS = 3000;
 
 /** Everything a {@link SignetRequestFeed} needs. */
 export interface SignetRequestFeedConfig {
-  /** Address of the central signet contract whose events to watch. */
+  /** Address of the central signet contract whose notification registry to poll. */
   readonly signetContractAddress: string;
   /**
-   * Source of BOTH events and raw contract state — a full
-   * `indexerPublicDataProvider` satisfies both halves.
+   * Source of raw contract state for BOTH the signet contract's registry and
+   * the requester ledgers the resolver authenticates against — a full
+   * `indexerPublicDataProvider` is assignable.
    */
-  readonly source: SignetEventSource & SignetPublicStateSource;
+  readonly source: SignetPublicStateSource;
   /**
    * Optional policy allow-list of requester contract addresses to serve
    * (matched case- and `0x`-prefix-insensitively). Omit to serve every
    * requester the resolver can authenticate. NOT a security control.
    */
   readonly allowContracts?: Iterable<string>;
-  /** Durable resume floor for the underlying observer (see {@link SignetEventObserverConfig.fromEventId}). */
-  readonly fromEventId?: number;
   /** Poll cadence for {@link SignetRequestFeed.requests}; default {@link DEFAULT_FEED_POLL_INTERVAL_MS}. */
   readonly pollIntervalMs?: number;
 }
 
+/**
+ * Resolve after `ms`, or immediately once `signal` aborts. Used to space out
+ * polls without wedging a shutdown.
+ *
+ * @param ms - Milliseconds to wait.
+ * @param signal - Abort to resolve early.
+ * @returns A promise that settles after the delay or the abort.
+ */
+export function sleepUnlessAborted(
+  ms: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 /** Canonical form for comparing contract addresses: no `0x`, lowercase. */
 function normalizeAddress(address: string): string {
   return stripHexPrefix(address).toLowerCase();
 }
 
 /**
- * The event-driven request feed. Composes a {@link SignetEventObserver}
- * (discovery) with a {@link SignetRequestResolver} (authentication), yielding
- * only notifications that resolve to a real, member request. Dedupes by request
- * id across its lifetime, so a redelivered notification is not re-yielded; call
+ * The registry-polling request feed. Reads the signet contract's notification
+ * registry (discovery) and hands each notification to a
+ * {@link SignetRequestResolver} (authentication), yielding only notifications
+ * that resolve to a real, member request. Dedupes by request id across its
+ * lifetime, so a re-registered notification is not re-yielded; call
  * {@link forget} to re-arm a request whose downstream processing failed.
  */
 export class SignetRequestFeed {
-  private readonly observer: SignetEventObserver<SignBidirectionalEvent>;
+  private readonly signetContractAddress: string;
+  private readonly source: SignetPublicStateSource;
   private readonly resolver: SignetRequestResolver;
   private readonly allowContracts?: Set<string>;
   private readonly pollIntervalMs: number;
@@ -75,17 +97,12 @@ export class SignetRequestFeed {
   private readonly yielded = new Set<RequestIdHex>();
 
   /**
-   * @param config - The signet contract, combined event/state source, optional
-   *   policy allow-list, and resume floor.
+   * @param config - The signet contract, state source, and optional policy
+   *   allow-list.
    */
   constructor(config: SignetRequestFeedConfig) {
-    this.observer = new SignetEventObserver({
-      signetContractAddress: config.signetContractAddress,
-      source: config.source,
-      codec: signBidirectionalEventCodec,
-      fromEventId: config.fromEventId,
-      pollIntervalMs: config.pollIntervalMs,
-    });
+    this.signetContractAddress = config.signetContractAddress;
+    this.source = config.source;
     this.resolver = new SignetRequestResolver({ source: config.source });
     this.allowContracts = config.allowContracts
       ? new Set(Array.from(config.allowContracts, normalizeAddress))
@@ -103,23 +120,56 @@ export class SignetRequestFeed {
   }
 
   /**
-   * One-shot: every currently-visible notification that is admitted by the
-   * allow-list, not already yielded, and resolves to an authenticated member
-   * request. Forged / not-yet-indexed / wrong-field notifications resolve to
-   * nothing and are dropped WITHOUT being marked yielded, so a genuine
-   * request whose ledger write has not indexed yet is retried next cycle.
+   * One-shot: every currently-registered notification that decodes, is
+   * admitted by the allow-list, not already yielded, and resolves to an
+   * authenticated member request. Registry enumeration has no meaningful
+   * on-ledger order, so entries are processed in ascending request-id-hex
+   * order — a stable, deterministic sequence. Forged / not-yet-indexed /
+   * wrong-field notifications resolve to nothing and are dropped WITHOUT
+   * being marked yielded, so a genuine request whose ledger write has not
+   * indexed yet is retried next cycle; undecodable or unsupported-version
+   * records are likewise skipped (and logged) without being marked.
    *
-   * @returns The newly-authenticated requests this cycle, in event id order.
+   * Dedupe and resolution key off the notification PAYLOAD's request id (the
+   * canonical one — the registry map key is caller-supplied and could
+   * disagree; the resolver's membership check authenticates the payload's).
+   *
+   * @returns The newly-authenticated requests this cycle.
+   * @throws Error if the signet contract has no readable state at the
+   *   configured address (wrong address or not yet deployed/indexed).
    */
   async poll(): Promise<ResolvedSignetRequest[]> {
-    const events = await this.observer.currentEvents();
+    const state = await this.source.queryContractState(
+      this.signetContractAddress,
+    );
+    if (!state?.data) {
+      throw new Error(
+        `No contract state at signet contract ${this.signetContractAddress} ` +
+          `— wrong address, or not yet deployed/indexed`,
+      );
+    }
+    const registry = readSignBidirectionalNotificationIndexFromState(
+      state.data,
+    );
     const out: ResolvedSignetRequest[] = [];
-    for (const event of events) {
-      if (this.yielded.has(event.requestId)) continue;
-      if (!this.allowed(event.callerAddress)) continue;
-      const resolved = await this.resolver.resolve(event);
+    for (const [registryKey, record] of [...registry.entries()].sort(
+      ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
+    )) {
+      let notification;
+      try {
+        notification = decodeSignBidirectionalNotification(record);
+      } catch (error) {
+        console.warn(
+          `SignetRequestFeed: skipping undecodable notification ` +
+            `registered under ${registryKey}: ${String(error)}`,
+        );
+        continue;
+      }
+      if (this.yielded.has(notification.requestId)) continue;
+      if (!this.allowed(notification.callerAddress)) continue;
+      const resolved = await this.resolver.resolve(notification);
       if (resolved === undefined) continue;
-      this.yielded.add(event.requestId);
+      this.yielded.add(notification.requestId);
       out.push(resolved);
     }
     return out;

package/src/signet-request-resolver.ts

@@ -1,19 +1,19 @@
-// Turn a SignBidirectionalEvent notification into an AUTHENTICATED request
-// record. This is the security core of the event flow (see
-// knowledge-base/caller-attribution.md and the invariants in this task's
-// brief): the event says only WHERE to look; the request that gets signed is
-// read from the named caller's own authenticated ledger, and the event's
-// `requestId` must be a member of that contract's request index. An attacker
-// cannot write into a contract it does not control, so a forged event can at
-// most re-point at a legitimate request that already exists — never inject one.
+// Turn a SignBidirectionalNotification into an AUTHENTICATED request record.
+// This is the security core of the discovery flow (see
+// knowledge-base/caller-attribution.md): the notification says only WHERE to
+// look; the request that gets signed is read from the named caller's own
+// authenticated ledger, and the notification's `requestId` must be a member
+// of that contract's request index. An attacker cannot write into a contract
+// it does not control, so a forged notification can at most re-point at a
+// legitimate request that already exists — never inject one.
 //
 // Key derivation stays f(callerAddress, path), keyed off the contract whose
-// authenticated state was actually read — exactly today's guarantee, now
-// reached via an event ping instead of per-contract polling.
+// authenticated state was actually read — the notification registry is a
+// pointer board, never an authority.
 
 import { lookupSignetRequestAt } from "./signature-requests-state-reader.ts";
 import type { RawContractState } from "./signature-state-reading.ts";
-import type { SignBidirectionalEvent } from "./signet-events.ts";
+import type { SignBidirectionalNotification } from "./signet-contract-state-reader.ts";
 import type { SignetPublicStateSource } from "./signet-request-response-reader.ts";
 import type {
   RequestIdHex,
@@ -21,15 +21,15 @@ import type {
 } from "./signet-requests.ts";
 
 /**
- * A {@link SignBidirectionalEvent} resolved to the authenticated request it
- * refers to: the request record read from `callerAddress`'s own ledger, with
- * `requestId` confirmed to be a member of that contract's index.
+ * A {@link SignBidirectionalNotification} resolved to the authenticated
+ * request it refers to: the request record read from `callerAddress`'s own
+ * ledger, with `requestId` confirmed to be a member of that contract's index.
  */
 export interface ResolvedSignetRequest {
   /**
    * The contract whose authenticated state the request was read from — the
    * epsilon-derivation predecessor. Key derivation keys off THIS, never off a
-   * field taken from the event on faith.
+   * field taken from the notification on faith.
    */
   callerAddress: string;
   /** The request id, confirmed to be a member of `callerAddress`'s index. */
@@ -45,7 +45,7 @@ export interface SignetRequestResolverConfig {
 }
 
 /**
- * Resolves {@link SignBidirectionalEvent} notifications to authenticated
+ * Resolves {@link SignBidirectionalNotification}s to authenticated
  * {@link ResolvedSignetRequest}s by reading the named caller's ledger and
  * enforcing the membership check. Construct once and reuse: resolved records
  * are immutable (their ledger key is their hash), so they are cached by request
@@ -75,22 +75,22 @@ export class SignetRequestResolver {
    * Resolve a notification to its authenticated request, or `undefined` when it
    * cannot be trusted: the caller contract has no state, or `requestId` is not
    * a member of the index at `requestsIndexField` (forged, stale, wrong field,
-   * or not yet indexed — poll again). Never throws on an untrusted event; a bad
-   * notification is dropped, not surfaced as an error.
+   * or not yet indexed — poll again). Never throws on an untrusted
+   * notification; a bad one is dropped, not surfaced as an error.
    *
-   * @param event - The decoded event notification.
-   * @returns The authenticated request, or `undefined` to drop the event.
+   * @param notification - The decoded notification.
+   * @returns The authenticated request, or `undefined` to drop the notification.
    */
   async resolve(
-    event: SignBidirectionalEvent,
+    notification: SignBidirectionalNotification,
   ): Promise<ResolvedSignetRequest | undefined> {
-    const cached = this.resolvedCache.get(event.requestId);
+    const cached = this.resolvedCache.get(notification.requestId);
     if (cached !== undefined) {
       return cached;
     }
     let state: { data: RawContractState } | null;
     try {
-      state = await this.source.queryContractState(event.callerAddress);
+      state = await this.source.queryContractState(notification.callerAddress);
     } catch {
       return undefined; // caller address not a contract / transient read error
     }
@@ -99,18 +99,18 @@ export class SignetRequestResolver {
     }
     const request = lookupSignetRequestAt(
       state.data,
-      event.requestsIndexField,
-      event.requestId,
+      notification.requestsIndexField,
+      notification.requestId,
     );
     if (request === undefined) {
       return undefined; // membership check failed — drop the notification
     }
     const resolved: ResolvedSignetRequest = {
-      callerAddress: event.callerAddress,
-      requestId: event.requestId,
+      callerAddress: notification.callerAddress,
+      requestId: notification.requestId,
       request,
     };
-    this.resolvedCache.set(event.requestId, resolved);
+    this.resolvedCache.set(notification.requestId, resolved);
     return resolved;
   }
 }

package/src/signet-requests.ts

@@ -461,15 +461,15 @@ function decodeAccessList(
  * below both go through it, so the transaction a client broadcasts is
  * provably the one the MPC put its signature over.
  *
- * @param event - The on-ledger request record.
+ * @param request - The on-ledger request record.
  * @returns The unsigned ethers transaction (`unsignedHash` is the digest the
  *   MPC signs).
  * @throws Error if a calldata word carries an unknown kind.
  */
 export function signBidirectionalRequestToUnsignedEVMTransaction(
-  event: SignBidirectionalRequest,
+  request: SignBidirectionalRequest,
 ): Transaction {
-  const { txParams } = event;
+  const { txParams } = request;
   return Transaction.from({
     type: 2,
     chainId: txParams.chainId,
@@ -581,7 +581,7 @@ export function signatureToSignatureResponse(
  * requester's derived address — the response log is unauthenticated, so
  * verify first with `verifySignatureResponse`.
  *
- * @param event - The on-ledger request record.
+ * @param request - The on-ledger request record.
  * @param response - The posted signature record answering it.
  * @returns The signed ethers transaction; `serialized` is the raw payload for
  *   `eth_sendRawTransaction`, `hash` its on-chain hash, `from` the recovered
@@ -591,10 +591,10 @@ export function signatureToSignatureResponse(
  *   is not a decodable signature.
  */
 export function signBidirectionalRequestToSignedEVMTransaction(
-  event: SignBidirectionalRequest,
+  request: SignBidirectionalRequest,
   response: SignatureResponse,
 ): Transaction {
-  const transaction = signBidirectionalRequestToUnsignedEVMTransaction(event);
+  const transaction = signBidirectionalRequestToUnsignedEVMTransaction(request);
   transaction.signature = signatureResponseToSignature(response);
   return transaction;
 }
@@ -655,6 +655,31 @@ export function bytesToHex(bytes: Uint8Array): string {
   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: string): string {
+  return hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+}
+
+/**
+ * Decode a hex string into bytes — the inverse of {@link bytesToHex}.
+ *
+ * @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;
+}
+
 /**
  * Render a request id in its canonical TS form (see
  * {@link RequestIdHex}) — also usable as a JS `Map` key, which raw