@sig-net/midnight 0.0.2 → 0.0.4

package/src/signet-requests.ts

@@ -1,762 +0,0 @@
-// TypeScript twins of the request-side structs in the Compact library
-// `Signet.compact` (same directory). The shapes MUST stay in lockstep with the Compact structs: the
-// compiler inlines struct types anonymously into each contract's generated
-// managed/contract/index.d.ts, and these named types match them structurally,
-// so ledger reads assign to them without casts.
-//
-// The lockstep is enforced by each consuming contract's simulator tests: the
-// "erc20-vault ledger shape" test in packages/vault-contract/tests/
-// contract.test.ts assigns the generated `ledger().signetRequestsIndex` to the
-// named SignBidirectionalRequestLedgerIndex type — the assignment itself is
-// the assertion, so any structural drift between the generated managed types
-// and these twins fails that package's `yarn build` / `yarn test`.
-//
-// Read more: https://docs.sig.network/ (signet protocol) and the module
-// header in Signet.compact (layout convention, path binding).
-
-import {
-  CompactTypeBoolean,
-  CompactTypeBytes,
-  CompactTypeEnum,
-  CompactTypeUnsignedInteger,
-  CompactTypeVector,
-  persistentHash,
-  type CompactType,
-} from "@midnight-ntwrk/compact-runtime";
-import { getAddress, getBytes, Signature, Transaction } from "ethers";
-
-import { asciiPadded } from "./constants.ts";
-import { bigintToBytes32, bytesToBigint } from "./schnorr.ts";
-import type { SignatureResponse } from "./signet-contract-state-reader.ts";
-
-/**
- * 32-byte signet request id (Compact: `new type RequestId = Bytes<32>`).
- * Chain-agnostic: downstream consumers treat it as an opaque key. Ids are
- * minted by `calculateRequestId` in Signet.compact — the domain-separated
- * hash of the full {@link SignBidirectionalRequest} record.
- */
-export type RequestId = Uint8Array;
-
-/**
- * Which transaction-param decomposition a request carries (Compact:
- * `enum TxParamType`), as the generated code represents enums: a `number`
- * holding the 0-based variant index. Exported as a `const` object (not a TS
- * `enum`) so the values stay structurally `number`.
- */
-export const TxParamType = {
-  /** {@link EVMType2TxParams}: an EIP-1559 EVM transaction. */
-  evmType2: 0,
-  /**
-   * Never emitted — mirrors the Compact-side padding variant that keeps the
-   * enum at >= 2 variants (a 1-variant enum is a zero-byte value the proof
-   * server cannot parse inside persistentHash preimages).
-   */
-  reserved: 1,
-} as const;
-
-/**
- * Compact's standard-library `Maybe<T>` as the compiler generates it: a
- * plain struct. Even when `is_some` is false, `value` carries a full
- * default-valued `T` (so vector capacities remain inferable).
- */
-export interface Maybe<T> {
-  is_some: boolean;
-  value: T;
-}
-
-/**
- * ABI calldata as a 4-byte selector + 32-byte word slots (Compact:
- * `EVMCalldata<#maxWords>`). Each word is a little-endian field embed (what the
- * contract's `x as Field as Bytes<32>` cast produces); the MPC re-encodes the
- * leading {@link noWords} of them big-endian to form the calldata body —
- * `data = selector || BE(words[0..noWords])`, see {@link assembleCalldata}.
- */
-export interface EVMCalldata {
-  /** The literal first 4 calldata bytes (big-endian, as broadcast). */
-  selector: Uint8Array;
-  /** How many leading {@link words} are real (Compact `noWords: Uint<16>`). */
-  noWords: bigint;
-  /** 32-byte word slots; capacity is the contract's `#maxWords` (vault: 2). */
-  words: Uint8Array[];
-}
-
-/**
- * One EIP-2930 access-list entry (Compact:
- * `EVMAccessListEntry<#maxStorageKeys>`).
- */
-export interface EVMAccessListEntry {
-  /** The pre-declared contract address, 20 display-order bytes. */
-  address: Uint8Array;
-  /** How many leading {@link storageKeys} are real. */
-  storageKeyCount: bigint;
-  /** Raw 32-byte storage keys, copied verbatim into the transaction. */
-  storageKeys: Uint8Array[];
-}
-
-/**
- * The EVM transaction to be signed, decomposed into typed fields (Compact:
- * `EVMType2TxParams<#maxCalldataWords, #maxAccessListEntries,
- * #maxStorageKeysPerEntry>`; EIP-1559 — https://eips.ethereum.org/EIPS/eip-1559).
- * Compact `Bytes<N>` fields arrive as N-byte `Uint8Array`s, `Uint<N>` as
- * `bigint`. Vector capacities are each contract's compile-time throttle;
- * the runtime counts say how many leading slots are real.
- */
-export interface EVMType2TxParams {
-  /** Call target (e.g. the ERC20 contract), 20 bytes. */
-  to: Uint8Array;
-  /** EVM chain id (also expressed in {@link SignBidirectionalRequest.caip2Id}). */
-  chainId: bigint;
-  /** Account nonce of the MPC-derived sender address. */
-  nonce: bigint;
-  /** Gas ceiling for the call. */
-  gasLimit: bigint;
-  /** Max total fee per gas, wei. */
-  maxFeePerGas: bigint;
-  /** Max priority fee per gas, wei. */
-  maxPriorityFeePerGas: bigint;
-  /** ETH sent with the call, wei. */
-  value: bigint;
-  /** How many leading {@link accessList} entries are real. */
-  accessListEntryCount: bigint;
-  /** EIP-2930 access list slots (capacity = contract's throttle). */
-  accessList: EVMAccessListEntry[];
-  /** Call data; `is_some: false` means a plain ETH transfer (`0x` data). */
-  calldata: Maybe<EVMCalldata>;
-}
-
-/**
- * Canonical signet request record (Compact:
- * `SignBidirectionalRequest<TxParams>`), stored per {@link RequestId} in a
- * requesting contract's index (ledger field 0). Mirrors the MPC's
- * SignBidirectionalRequest with the transaction decomposed. The TS twin fixes
- * the type parameter at {@link EVMType2TxParams} — the only decomposition
- * so far; new tx kinds add a union here alongside their Compact struct.
- */
-export interface SignBidirectionalRequest {
-  /** Contract-local nonce captured when the request was created. */
-  requestNonce: bigint;
-  /** A {@link TxParamType} value tagging the txParams decomposition. */
-  txParamType: number;
-  /** The transaction decomposition. */
-  txParams: EVMType2TxParams;
-  /** Target chain in CAIP-2 form (https://chainagnostic.org/CAIPs/caip-2), zero-padded; 32 bytes. */
-  caip2Id: Uint8Array;
-  /** MPC root-key version to derive from (>= 1; version 0 is the unsupported legacy format). */
-  keyVersion: bigint;
-  /** Key-derivation path: canonical lowercase hex of the caller's identity commitment, zero-padded; 256 bytes. */
-  path: Uint8Array;
-  /** Signature scheme, zero-padded ASCII, e.g. "ecdsa"; 32 bytes. */
-  algo: Uint8Array;
-  /** Response destination, zero-padded ASCII, e.g. "ethereum"; 32 bytes. */
-  dest: Uint8Array;
-  /** Scheme-specific extras, opaque; 64 bytes. */
-  params: Uint8Array;
-  /** MPC output_deserialization_schema (destination chain -> MPC); 128 bytes. */
-  outputDeserializationSchema: Uint8Array;
-  /** MPC respond_serialization_schema (MPC -> source chain); 128 bytes. */
-  respondSerializationSchema: Uint8Array;
-}
-
-// ---- Request id (TS twin of the Compact circuit) ---------------------------
-//
-// DEVIATION from the "pure circuits are compiled, never re-written in TS"
-// rule (see circuits.compact): `calculateRequestId` is generic over the
-// tx-params type, the Compact compiler cannot export type-parameterized
-// circuits from the top level, and a compiled copy would have to be
-// monomorphized at ONE capacity instantiation — a client contract's choice
-// that never belongs in this client-agnostic package. So the request-id
-// circuit alone gets a TS twin here.
-//
-// It is NOT a hand-port of the hash algorithm: it calls the very
-// `persistentHash` runtime builtin that compiled circuits call, over runtime
-// type descriptors mirroring the ones the compiler generates (compare
-// `_calculateRequestId_0` in any consuming contract's
-// managed/contract/index.js). What must stay in lockstep with Signet.compact
-// is exactly what this file already keeps in lockstep — the struct shapes,
-// field by field, in declaration order. Enforced by vault-contract's
-// "deposit round-trip" test, which asserts the id computed here equals the
-// ledger map key minted by the REAL compiled contract.
-
-// Runtime descriptors of the Compact base types the request record uses.
-// CompactTypeUnsignedInteger takes (maxValue, byte length) — same literals
-// the compiler emits for Uint<8/32/64/128>. CompactTypeEnum takes
-// (variantCount - 1, byte length); NOTE a 1-variant enum would compile to
-// `CompactTypeEnum(0, 0)` — zero bytes, which the proof server cannot parse
-// inside persistentHash preimages. TxParamType therefore carries a padding
-// `reserved` variant so it stays at (1, 1).
-const BYTES_4 = new CompactTypeBytes(4);
-const BYTES_20 = new CompactTypeBytes(20);
-const BYTES_32 = new CompactTypeBytes(32);
-const BYTES_64 = new CompactTypeBytes(64);
-const BYTES_128 = new CompactTypeBytes(128);
-const BYTES_256 = new CompactTypeBytes(256);
-const UINT_8 = new CompactTypeUnsignedInteger(2n ** 8n - 1n, 1);
-const UINT_16 = new CompactTypeUnsignedInteger(2n ** 16n - 1n, 2);
-const UINT_32 = new CompactTypeUnsignedInteger(2n ** 32n - 1n, 4);
-const UINT_64 = new CompactTypeUnsignedInteger(2n ** 64n - 1n, 8);
-const UINT_128 = new CompactTypeUnsignedInteger(2n ** 128n - 1n, 16);
-const TX_PARAM_TYPE = new CompactTypeEnum(1, 1);
-
-/**
- * Build the runtime descriptor of a Compact struct from its per-field
- * descriptors — the generic form of the struct descriptor classes the
- * compiler generates (field-by-field concatenation of alignments and values).
- *
- * Field ORDER must match the Compact struct declaration order; object
- * literals preserve insertion order for string keys, so pass fields in
- * declaration order.
- *
- * @param fields - One runtime descriptor per struct field, in declaration order.
- * @returns The composed struct descriptor.
- */
-function compactStructDescriptor<T extends object>(fields: {
-  readonly [K in keyof T]-?: CompactType<T[K]>;
-}): CompactType<T> {
-  const entries = Object.entries(fields) as unknown as ReadonlyArray<
-    [keyof T & string, CompactType<T[keyof T & string]>]
-  >;
-  return {
-    alignment: () =>
-      entries.flatMap(([, type]) => type.alignment()),
-    toValue: (value) =>
-      entries.flatMap(([key, type]) => type.toValue(value[key])),
-    fromValue: (value) => {
-      const result = {} as Record<keyof T & string, unknown>;
-      for (const [key, type] of entries) {
-        result[key] = type.fromValue(value);
-      }
-      return result as T;
-    },
-  };
-}
-
-/**
- * Descriptor of Compact's standard-library `Maybe<T>` — the compiler
- * generates it as the struct `{ is_some: Boolean, value: T }`.
- *
- * @param inner - Descriptor of the wrapped type.
- * @returns The Maybe struct descriptor.
- */
-function compactMaybeDescriptor<T>(inner: CompactType<T>): CompactType<Maybe<T>> {
-  return compactStructDescriptor<Maybe<T>>({
-    is_some: CompactTypeBoolean,
-    value: inner,
-  });
-}
-
-/**
- * Descriptor of {@link EVMCalldata} at one word capacity — the TS analogue
- * of instantiating Compact's `EVMCalldata<#maxWords>`.
- *
- * @param maxWords - The contract's calldata word capacity (the vault uses 2).
- * @returns The calldata descriptor.
- */
-export function evmCalldataDescriptor(maxWords: number): CompactType<EVMCalldata> {
-  return compactStructDescriptor<EVMCalldata>({
-    selector: BYTES_4,
-    noWords: UINT_16,
-    words: new CompactTypeVector(maxWords, BYTES_32),
-  });
-}
-
-/**
- * Descriptor of {@link EVMAccessListEntry} at one storage-key capacity
- * (Compact: `EVMAccessListEntry<#maxStorageKeys>`).
- *
- * @param maxStorageKeys - Storage-key capacity per entry.
- * @returns The entry descriptor.
- */
-export function evmAccessListEntryDescriptor(
-  maxStorageKeys: number,
-): CompactType<EVMAccessListEntry> {
-  return compactStructDescriptor<EVMAccessListEntry>({
-    address: BYTES_20,
-    storageKeyCount: UINT_8,
-    storageKeys: new CompactTypeVector(maxStorageKeys, BYTES_32),
-  });
-}
-
-/**
- * Descriptor of {@link EVMType2TxParams} at one capacity instantiation —
- * the TS analogue of Compact's `EVMType2TxParams<#maxCalldataWords,
- * #maxAccessListEntries, #maxStorageKeysPerEntry>`.
- *
- * @param maxCalldataWords - Calldata word capacity.
- * @param maxAccessListEntries - Access-list entry capacity.
- * @param maxStorageKeysPerEntry - Storage-key capacity per entry.
- * @returns The tx-params descriptor.
- */
-export function evmType2TxParamsDescriptor(
-  maxCalldataWords: number,
-  maxAccessListEntries: number,
-  maxStorageKeysPerEntry: number,
-): CompactType<EVMType2TxParams> {
-  return compactStructDescriptor<EVMType2TxParams>({
-    to: BYTES_20,
-    chainId: UINT_64,
-    nonce: UINT_64,
-    gasLimit: UINT_64,
-    maxFeePerGas: UINT_128,
-    maxPriorityFeePerGas: UINT_128,
-    value: UINT_128,
-    accessListEntryCount: UINT_8,
-    accessList: new CompactTypeVector(
-      maxAccessListEntries,
-      evmAccessListEntryDescriptor(maxStorageKeysPerEntry),
-    ),
-    calldata: compactMaybeDescriptor(evmCalldataDescriptor(maxCalldataWords)),
-  });
-}
-
-/**
- * Descriptor of {@link SignBidirectionalRequest} at one capacity instantiation.
- *
- * @param maxCalldataWords - Calldata word capacity.
- * @param maxAccessListEntries - Access-list entry capacity.
- * @param maxStorageKeysPerEntry - Storage-key capacity per entry.
- * @returns The request record descriptor.
- */
-export function signBidirectionalRequestDescriptor(
-  maxCalldataWords: number,
-  maxAccessListEntries: number,
-  maxStorageKeysPerEntry: number,
-): CompactType<SignBidirectionalRequest> {
-  return compactStructDescriptor<SignBidirectionalRequest>({
-    requestNonce: UINT_64,
-    txParamType: TX_PARAM_TYPE,
-    txParams: evmType2TxParamsDescriptor(
-      maxCalldataWords,
-      maxAccessListEntries,
-      maxStorageKeysPerEntry,
-    ),
-    caip2Id: BYTES_32,
-    keyVersion: UINT_32,
-    path: BYTES_256,
-    algo: BYTES_32,
-    dest: BYTES_32,
-    params: BYTES_64,
-    outputDeserializationSchema: BYTES_128,
-    respondSerializationSchema: BYTES_128,
-  });
-}
-
-/**
- * Domain tag partitioning the {@link RequestId} space
- * (Compact: `pad(32, "signet:midnight:request")`).
- */
-const REQUEST_ID_DOMAIN_TAG = asciiPadded("signet:midnight:request", 32);
-
-/**
- * Canonical id of a signet request: the domain-separated persistent hash of
- * the entire request record. TS twin of Signet.compact's `calculateRequestId`
- * circuit (see the deviation note atop this section), generic over the
- * capacity instantiation via the record's own array lengths — pass the
- * record exactly as the ledger stores it, unused slots included.
- *
- * @param request - The full request record (contract-shaped, all slots).
- * @returns The 32-byte request id — the record's ledger map key.
- */
-export function calculateRequestId(request: SignBidirectionalRequest): RequestId {
-  const { txParams } = request;
-  const maxCalldataWords = txParams.calldata.value.words.length;
-  const maxAccessListEntries = txParams.accessList.length;
-  const maxStorageKeysPerEntry =
-    maxAccessListEntries === 0 ? 0 : txParams.accessList[0].storageKeys.length;
-  return persistentHash(new CompactTypeVector(2, BYTES_32), [
-    REQUEST_ID_DOMAIN_TAG,
-    persistentHash(
-      signBidirectionalRequestDescriptor(
-        maxCalldataWords,
-        maxAccessListEntries,
-        maxStorageKeysPerEntry,
-      ),
-      request,
-    ),
-  ]);
-}
-
-// ---- Calldata / transaction assembly ----------------------------------------
-
-/**
- * The 32-byte value of a numeric ABI word: the little-endian field embed of
- * the number, exactly what Compact's `x as Field as Bytes<32>` cast produces
- * in-circuit. Use when building words off-chain (UIs, expected-record
- * builders, tests).
- *
- * @param value - The word's numeric value (e.g. an amount).
- * @returns The 32-byte LE embed to store in an {@link EVMCalldata} word.
- */
-export function numericAbiWordValue(value: bigint): Uint8Array {
-  return bigintToBytes32(value);
-}
-
-/**
- * The 32-byte staticArg word value for an EVM address: the BIG-ENDIAN
- * numeric reading of its 20 display-order bytes, LE-embedded. TS mirror of
- * Signet.compact's `evmAddressAbiValue` circuit (+ `as Bytes<32>`); see the
- * warning there — embedding the display-order bytes directly would come out
- * byte-reversed in the assembled calldata.
- *
- * @param address - The 20-byte address in display order.
- * @returns The 32-byte word value to store in an {@link EVMCalldata} word.
- */
-export function evmAddressAbiWord(address: Uint8Array): Uint8Array {
-  let value = 0n;
-  for (const byte of address) {
-    value = value * 256n + BigInt(byte);
-  }
-  return bigintToBytes32(value);
-}
-
-/**
- * Re-assemble the raw calldata a request's words describe:
- * `data = selector || BE(words[0..noWords])`. Each word is a little-endian
- * field embed (the contract's `x as Field as Bytes<32>` cast); the leading
- * `noWords` are re-encoded big-endian into 32-byte ABI words and any remaining
- * capacity slots are dropped. This is THE implementation of the MPC re-assembly
- * documented on `EVMCalldata` in Signet.compact.
- *
- * @param calldata - The request's calldata field.
- * @returns Hex calldata for the transaction (`"0x"` when absent).
- */
-export function assembleCalldata(calldata: Maybe<EVMCalldata>): string {
-  if (!calldata.is_some) {
-    return "0x";
-  }
-  const { selector, noWords, words } = calldata.value;
-  let data = `0x${bytesToHex(selector)}`;
-  for (let i = 0; i < Number(noWords); i++) {
-    data += bytesToHex(bigintToBytes32BE(bytesToBigint(words[i])));
-  }
-  return data;
-}
-
-/**
- * Decode the real (count-trimmed) access list of a request into the shape
- * ethers' `Transaction.from` accepts.
- *
- * @param txParams - The request's transaction decomposition.
- * @returns The access list, possibly empty.
- */
-function decodeAccessList(
-  txParams: EVMType2TxParams,
-): Array<{ address: string; storageKeys: string[] }> {
-  return txParams.accessList
-    .slice(0, Number(txParams.accessListEntryCount))
-    .map((entry) => ({
-      address: getAddress(`0x${bytesToHex(entry.address)}`),
-      storageKeys: entry.storageKeys
-        .slice(0, Number(entry.storageKeyCount))
-        .map((key) => `0x${bytesToHex(key)}`),
-    }));
-}
-
-/**
- * Rebuild the unsigned EIP-1559 transaction a request record describes,
- * byte-identical to the one the MPC assembles and signs: calldata from the
- * tagged words (see {@link assembleCalldata}), the count-trimmed access
- * list, and the stored envelope fields. This is the canonical
- * request→transaction transform; response-side verification
- * (`signature-response-verification.ts`) and the signed-transaction builder
- * below both go through it, so the transaction a client broadcasts is
- * provably the one the MPC put its signature over.
- *
- * @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(
-  request: SignBidirectionalRequest,
-): Transaction {
-  const { txParams } = request;
-  return Transaction.from({
-    type: 2,
-    chainId: txParams.chainId,
-    nonce: Number(txParams.nonce),
-    gasLimit: txParams.gasLimit,
-    maxFeePerGas: txParams.maxFeePerGas,
-    maxPriorityFeePerGas: txParams.maxPriorityFeePerGas,
-    to: getAddress(`0x${bytesToHex(txParams.to)}`),
-    value: txParams.value,
-    accessList: decodeAccessList(txParams),
-    data: assembleCalldata(txParams.calldata),
-  });
-}
-
-/**
- * Decode a response signature record (as posted to the signet contract's
- * signature response log — the canonical MPC `Signature { big_r, s,
- * recovery_id }` shape) into an ethers {@link Signature}: `r` is `bigR`'s x
- * coordinate, `v` the legacy parity derived from the recovery id.
- *
- * @param response - The posted signature record.
- * @returns The ethers signature.
- * @throws Error if the recovery id is not 0 or 1.
- */
-export function signatureResponseToSignature(
-  response: SignatureResponse,
-): Signature {
-  const recoveryId = Number(response.recoveryId);
-  if (recoveryId !== 0 && recoveryId !== 1) {
-    throw new Error(`expected a recovery id of 0 or 1, got ${recoveryId}`);
-  }
-  return Signature.from({
-    r: `0x${bytesToHex(response.bigRx)}`,
-    s: `0x${bytesToHex(response.s)}`,
-    v: recoveryId + 27,
-  });
-}
-
-/** secp256k1 base field prime (2^256 - 2^32 - 977). */
-const SECP256K1_P = 2n ** 256n - 2n ** 32n - 977n;
-
-/** Modular exponentiation by squaring. */
-function modPow(base: bigint, exponent: bigint, modulus: bigint): bigint {
-  let result = 1n;
-  let b = base % modulus;
-  let e = exponent;
-  while (e > 0n) {
-    if (e & 1n) result = (result * b) % modulus;
-    b = (b * b) % modulus;
-    e >>= 1n;
-  }
-  return result;
-}
-
-/** Encode a bigint as exactly 32 BIG-endian bytes (secp256k1 scalar form). */
-function bigintToBytes32BE(value: bigint): Uint8Array {
-  const out = new Uint8Array(32);
-  let v = value;
-  for (let i = 31; i >= 0; i--) {
-    out[i] = Number(v & 0xffn);
-    v >>= 8n;
-  }
-  return out;
-}
-
-/**
- * Encode an ECDSA signature as the response record posted to the signet
- * contract — the inverse of {@link signatureResponseToSignature},
- * for MPC-side posters (the fakenet signer, tests). The canonical record
- * carries `bigR` as a full affine point but an `r || s || v` signature only
- * has R.x and the parity of R.y, so R.y is recovered by decompressing the
- * point on the curve (y² = x³ + 7 over the secp256k1 base field).
- *
- * The parameter is structural (the r/s/yParity subset of an ethers
- * {@link Signature}) so signatures from ANY ethers instance qualify — posters
- * living in other repos resolve their own ethers install, and nominal class
- * typing would reject it.
- *
- * @param signature - The signature to encode (`r`/`s` as 0x hex, `yParity` 0 or 1).
- * @returns The response record, ready to post.
- * @throws Error if `r` is not the x coordinate of a curve point.
- */
-export function signatureToSignatureResponse(
-  signature: Pick<Signature, "r" | "s" | "yParity">,
-): SignatureResponse {
-  const x = BigInt(signature.r);
-  const ySquared = (modPow(x, 3n, SECP256K1_P) + 7n) % SECP256K1_P;
-  // P ≡ 3 (mod 4), so a square root (when one exists) is c^((P+1)/4).
-  let y = modPow(ySquared, (SECP256K1_P + 1n) / 4n, SECP256K1_P);
-  if ((y * y) % SECP256K1_P !== ySquared) {
-    throw new Error("signature r is not the x coordinate of a secp256k1 point");
-  }
-  if ((y & 1n) !== BigInt(signature.yParity)) {
-    y = SECP256K1_P - y;
-  }
-  return {
-    bigRx: getBytes(signature.r),
-    bigRy: bigintToBytes32BE(y),
-    s: getBytes(signature.s),
-    recoveryId: BigInt(signature.yParity),
-  };
-}
-
-/**
- * Assemble the broadcast-ready signed EIP-1559 transaction for a request from
- * its MPC signature response: rebuild the exact unsigned transaction the MPC
- * signed (see {@link signBidirectionalRequestToUnsignedEVMTransaction}) and
- * attach the signature. Does NOT check that the signature recovers to the
- * requester's derived address — the response log is unauthenticated, so
- * verify first with `verifySignatureResponse`.
- *
- * @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
- *   sender.
- * @throws Error if the request record is malformed (see
- *   {@link signBidirectionalRequestToUnsignedEVMTransaction}) or the response
- *   is not a decodable signature.
- */
-export function signBidirectionalRequestToSignedEVMTransaction(
-  request: SignBidirectionalRequest,
-  response: SignatureResponse,
-): Transaction {
-  const transaction = signBidirectionalRequestToUnsignedEVMTransaction(request);
-  transaction.signature = signatureResponseToSignature(response);
-  return transaction;
-}
-
-/**
- * The generated ledger shape of `Map<RequestId, SignBidirectionalRequest>`:
- * what a contract's `ledger(state).signetRequestsIndex` provides. Structural,
- * so any contract exposing the index satisfies it.
- */
-export interface SignBidirectionalRequestLedgerIndex
-  extends Iterable<[RequestId, SignBidirectionalRequest]> {
-  /** @returns `true` when the index holds no requests. */
-  isEmpty(): boolean;
-  /** @returns Number of requests in the index. */
-  size(): bigint;
-  /**
-   * @param requestId - 32-byte request id to probe.
-   * @returns `true` when the index holds an entry for `requestId`.
-   */
-  member(requestId: RequestId): boolean;
-  /**
-   * @param requestId - 32-byte request id to fetch.
-   * @returns The stored request record; throws when absent — guard with
-   *   {@link member} first.
-   */
-  lookup(requestId: RequestId): SignBidirectionalRequest;
-}
-
-declare const requestIdHexBrand: unique symbol;
-
-/**
- * 64-char lowercase hex rendering of a {@link RequestId} — THE
- * representation of a request id everywhere in TypeScript. Raw
- * {@link RequestId} bytes appear only at the Compact boundary (state
- * readers, compiled-circuit calls); the moment an id crosses that boundary it
- * becomes this type. Branded (the TS analogue of Compact's `new type`) so an
- * arbitrary string cannot pose as a request id: mint one with
- * {@link requestIdHex} (from ledger bytes) or {@link parseRequestIdHex}
- * (from user input), and go back to bytes with {@link requestIdBytes}.
- */
-export type RequestIdHex = string & {
-  readonly [requestIdHexBrand]: true;
-};
-
-/** Plain-JS index parsed out of the ledger, keyed by hex request id. */
-export type SignBidirectionalRequestIndex = Map<
-  RequestIdHex,
-  SignBidirectionalRequest
->;
-
-/**
- * Render bytes as a lowercase hex string, no `0x` prefix.
- *
- * @param bytes - The bytes to render.
- * @returns Lowercase hex, two chars per byte.
- */
-export function bytesToHex(bytes: 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
- * `Uint8Array` ids are not (they compare by reference).
- *
- * @param requestId - 32-byte request id.
- * @returns The branded 64-char lowercase hex string, no `0x` prefix.
- */
-export function requestIdHex(requestId: RequestId): RequestIdHex {
-  return bytesToHex(requestId) as RequestIdHex;
-}
-
-/**
- * Validate and normalize an untrusted string (CLI argument, config value)
- * into a {@link RequestIdHex}: an optional `0x` prefix is stripped and
- * the digits lowercased before validation.
- *
- * @param value - The candidate request id string.
- * @returns The branded, normalized request id hex.
- * @throws Error if the value is not 64 hex chars after normalization.
- */
-export function parseRequestIdHex(value: string): RequestIdHex {
-  const hex = value.replace(/^0x/i, "").toLowerCase();
-  if (!/^[0-9a-f]{64}$/.test(hex)) {
-    throw new Error(`not a 32-byte request id in hex: "${value}"`);
-  }
-  return hex as RequestIdHex;
-}
-
-/**
- * Decode a request id back to its 32 raw bytes for the Compact boundary
- * (compiled-circuit calls, ledger lookups).
- *
- * @param id - The request id in canonical hex form.
- * @returns The 32-byte request id.
- */
-export function requestIdBytes(id: RequestIdHex): RequestId {
-  const bytes = new Uint8Array(32);
-  for (let i = 0; i < 32; i++) {
-    bytes[i] = Number.parseInt(id.slice(2 * i, 2 * i + 2), 16);
-  }
-  return bytes;
-}
-
-/** Byte width of the path field (Compact `Bytes<256>`). */
-export const PATH_BYTES = 256;
-
-/**
- * Build the canonical MPC derivation path for an identity commitment: the
- * lowercase hex of the commitment as ASCII, zero-padded to {@link PATH_BYTES}
- * — exactly what the contract's `assertPathCommitment` accepts. Use this to
- * populate {@link SignBidirectionalRequest.path} when constructing requests.
- *
- * @param commitment - 32-byte identity commitment.
- * @returns The 256-byte path field value.
- */
-export function signetPathOfCommitment(commitment: Uint8Array): Uint8Array {
-  const path = new Uint8Array(PATH_BYTES);
-  path.set(new TextEncoder().encode(bytesToHex(commitment)));
-  return path;
-}
-
-/**
- * Parse the on-ledger request map into a plain-JS index keyed by hex
- * request id.
- *
- * @param ledgerIndex - Iterable of `[requestId, request]` entries — e.g. a
- *   contract's `ledger(state).signetRequestsIndex` (any
- *   {@link SignBidirectionalRequestLedgerIndex}).
- * @returns A new `Map` from {@link requestIdHex} key to request record.
- */
-export function toSignBidirectionalRequestIndex(
-  ledgerIndex: Iterable<[RequestId, SignBidirectionalRequest]>,
-): SignBidirectionalRequestIndex {
-  const index: SignBidirectionalRequestIndex = new Map();
-  for (const [requestId, request] of ledgerIndex) {
-    index.set(requestIdHex(requestId), request);
-  }
-  return index;
-}