@openzeppelin/compact-contracts 0.3.0-rc.1 → 0.4.0-alpha.2

package/crypto/Eip712.compact

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (crypto/Eip712.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module Eip712
+ * @description The EIP-712 typed-data envelope, for verifying signatures
+ * produced by Ethereum signing infrastructure.
+ *
+ * A typed-data signature covers `keccak256(0x1901 || domainSeparator ||
+ * structHash)`. The domain separator binds the signature to one application,
+ * so a signature obtained for any other domain cannot be replayed here — the
+ * property `personal_sign` does not provide, since it signs an opaque hash
+ * with no application binding.
+ *
+ * Build `structHash` from EVM ABI words (see `utils/EvmAbi`), with the
+ * operation's type hash as the first word.
+ *
+ * @notice The domain is `(name, version, salt)`. `chainId` and
+ * `verifyingContract` are omitted, which EIP-712 permits — every domain field
+ * is optional. They are omitted because neither is expressible: a Midnight
+ * contract address is 32 bytes and does not fit `verifyingContract`'s
+ * `address` type, and no network identifier is available in-circuit.
+ *
+ * On an EVM chain `verifyingContract` is what makes a domain identify one
+ * deployment rather than one application. Without it, a consumer has to get
+ * that binding elsewhere. There are two places to put it, and they are not
+ * equivalent:
+ *
+ * - As a field of the operation struct, holding the contract's own address.
+ *   This is the stronger option and the one to reach for by default: a
+ *   Midnight address is randomised at deployment and cannot be predicted, so
+ *   no two instances share one, and a signature for one deployment cannot
+ *   authorise another.
+ * - As `salt`, a per-deployment value in the domain. This is weaker, because
+ *   it separates domains rather than messages. It is worth adding when the
+ *   signer gates on domains but cannot read struct fields, since that is the
+ *   only level at which it is visible.
+ *
+ * A consumer doing neither has one domain shared by every deployment of the
+ * contract, and nothing distinguishing them.
+ *
+ * @notice Requires ZKIR v3: `keccak256` is unavailable on the v2 backend.
+ */
+module Eip712 {
+  import CompactStandardLibrary;
+
+  /**
+   * @description The 66-byte typed-data preimage: the two-byte prefix, the
+   * domain separator, then the struct hash. `Bytes<n>` is emitted at exactly
+   * `n` bytes, so this hashes as the concatenation an EVM signer produces.
+   */
+  struct TypedDataPreimage {
+    prefixBytes: Bytes<2>,
+    domainSeparator: Bytes<32>,
+    structHash: Bytes<32>
+  }
+
+  /**
+   * @description The four words of the domain separator's preimage.
+   */
+  struct DomainFields {
+    typeHash: Bytes<32>,
+    hashedName: Bytes<32>,
+    hashedVersion: Bytes<32>,
+    salt: Bytes<32>
+  }
+
+  /**
+   * @description `0x1901`, the EIP-191 version byte `0x01` behind the `0x19`
+   * marker, which is how EIP-712 identifies itself.
+   *
+   * @dev Written as byte values because the bytes are not printable. The
+   * version byte is what keeps a typed-data digest from colliding with a
+   * `personal_sign` one (version `0x45`) or an intended-validator one (`0x00`).
+   *
+   * @returns {Bytes<2>} The typed-data prefix.
+   */
+  pure circuit TYPED_DATA_PREFIX(): Bytes<2> {
+    const raw: Vector<2, Uint<8>> = [25, 1];
+
+    return raw as Bytes<2>;
+  }
+
+  /**
+   * @description `keccak256("EIP712Domain(string name,string version,bytes32 salt)")`.
+   *
+   * @dev Written as a literal word. `compactc` emits a full keccak
+   * permutation even for a constant argument, so hashing the type string
+   * in-circuit would roughly double `domainSeparator`. The spec checks this
+   * word against the type string above.
+   *
+   * The string must match the domain's field set exactly: a difference of one
+   * character yields a different separator and every signature fails.
+   *
+   * @returns {Bytes<32>} The domain type hash.
+   */
+  pure circuit DOMAIN_TYPEHASH(): Bytes<32> {
+    // keccak256("EIP712Domain(string name,string version,bytes32 salt)")
+    // = 0x599a80fcaa47b95e2323ab4d34d34e0cc9feda4b843edafcc30c7bdf60ea15bf
+    const typeHash: Vector<32, Uint<8>> = [
+      0x59, 0x9a, 0x80, 0xfc, 0xaa, 0x47, 0xb9, 0x5e,
+      0x23, 0x23, 0xab, 0x4d, 0x34, 0xd3, 0x4e, 0x0c,
+      0xc9, 0xfe, 0xda, 0x4b, 0x84, 0x3e, 0xda, 0xfc,
+      0xc3, 0x0c, 0x7b, 0xdf, 0x60, 0xea, 0x15, 0xbf
+    ];
+
+    return typeHash as Bytes<32>;
+  }
+
+  /**
+   * @description Computes the domain separator for `(name, version, salt)`.
+   *
+   * EIP-712 encodes a `string` field as the keccak hash of its UTF-8 bytes,
+   * so the name and version arrive already hashed. Compact has no dynamic
+   * types, so a consumer hashes its own fixed-length literals.
+   *
+   * @constraints k=14, rows=4561 (zkir-v3)
+   *
+   * @param {Bytes<32>} hashedName - `keccak256(bytes(name))`.
+   * @param {Bytes<32>} hashedVersion - `keccak256(bytes(version))`.
+   * @param {Bytes<32>} salt - Per-deployment, per-network random value.
+   * @returns {Bytes<32>} The domain separator.
+   */
+  export pure circuit domainSeparator(
+    hashedName: Bytes<32>,
+    hashedVersion: Bytes<32>,
+    salt: Bytes<32>
+  ): Bytes<32> {
+    return keccak256<DomainFields>(DomainFields {
+      typeHash: DOMAIN_TYPEHASH(),
+      hashedName: hashedName,
+      hashedVersion: hashedVersion,
+      salt: salt
+    });
+  }
+
+  /**
+   * @description Wraps a struct hash in the typed-data envelope, yielding the
+   * digest an EVM signer actually signs.
+   *
+   * @constraints k=14, rows=4463 (zkir-v3)
+   *
+   * Requirements:
+   *
+   * - `separator` must be non-zero, which an initialized domain always is.
+   *
+   * @param {Bytes<32>} separator - The domain separator, fixed at deployment.
+   * @param {Bytes<32>} structHash - `keccak256(typeHash || the operation's ABI words)`.
+   * @returns {Bytes<32>} The digest to verify signatures against.
+   */
+  export pure circuit hashTypedData(
+    separator: Bytes<32>,
+    structHash: Bytes<32>
+  ): Bytes<32> {
+    // A zero separator is what an uninitialized ledger cell reads as, and a
+    // digest built from one still verifies signatures. Fail closed rather than
+    // authorize an operation under an unset domain.
+    assert(separator != pad(32, ""), "Eip712: domain separator not set");
+
+    return keccak256<TypedDataPreimage>(TypedDataPreimage {
+      prefixBytes: TYPED_DATA_PREFIX(),
+      domainSeparator: separator,
+      structHash: structHash
+    });
+  }
+}

package/crypto/ElGamal.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-rc.1 (crypto/ElGamal.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (crypto/ElGamal.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module ElGamal
@@ -32,14 +32,11 @@ pragma language_version >= 0.23.0;
  * and compared against on every later verification; `degradeToTransient`
  * truncates the Field to 31 bytes so the result is ALWAYS a valid Jubjub
  * scalar. Feeding a raw `persistentHash` output into `ecMulGenerator` would
- * occasionally exceed the Jubjub scalar field order and fault at runtime.
+ * occasionally exceed the Jubjub scalar field order and be rejected.
  *
- * @dev Domain separation. `persistentHash<Vector<N, Bytes<32>>>` is NOT
- * domain-separating on its own. Two circuits hashing the same arity and
- * element type share one hash domain, and the hash cannot tell which slot was
- * "meant" as a tag. `secretToScalar` therefore prefixes a fixed constant, and
- * that constant is placed FIRST so no call to `expandRandomness` (whose two
- * slots are both caller-supplied) can reproduce the tuple by ordinary use.
+ * @dev Scalars are typed `JubjubScalar`, not `Field`. A `Field as JubjubScalar`
+ * cast reduces modulo the subgroup order, so casting at a call site would
+ * silently accept an out-of-range scalar the typed parameter rejects.
  *
  * @dev TRUST ASSUMPTION — subgroup membership. This is the module's most
  * load-bearing assumption. Every `JubjubPoint` reaching a curve operation is
@@ -50,9 +47,8 @@ pragma language_version >= 0.23.0;
  * off-curve / low-order / mixed-order point makes the circuit unsatisfiable.
  * The module therefore performs NO in-circuit subgroup check: the runtime
  * already constrains membership (so it is unnecessary), and the direct test
- * `ℓ*P == O` is unavailable anyway because `ecMul` by `ℓ` faults (verified — `ℓ`
- * exceeds the valid scalar range, while `ℓ-1` is accepted). The `ecNeg` identity
- * (`(ℓ-1)*P = -P`) and the homomorphic algebra depend on this holding.
+ * `ℓ*P == O` is unavailable anyway because `ecMul` by `ℓ` is out of scalar
+ * range. The homomorphic algebra depends on this holding.
  *
  * Basis (and its limits): source-verified against `midnight-circuits` 6.0.0 —
  * the version vendored by the Midnight onchain-runtime we compile against —
@@ -109,34 +105,11 @@ module ElGamal {
    * @description Maps a 32-byte secret to a valid Jubjub scalar. See the
    * module-level hash-to-scalar note for why `degradeToTransient` is required.
    *
-   * @dev Domain separation here is load-bearing, not cosmetic. This output is
-   * the private key protecting every ciphertext held under an account. Public
-   * account identifiers derived from `Utils.computeAccountId`, for example,
-   * are computed as `persistentHash([secretKey])`, and that identifier
-   * is stored in the clear as a ledger map key. Untagged, this circuit
-   * would compute that same hash, so a secret used in both roles would
-   * have its encryption key recoverable from a published identifier by applying
-   * `degradeToTransient`. The tag makes the two derivations unrelated, so a
-   * wallet MAY safely derive its account secret and its encryption secret from
-   * common key material.
-   *
-   * @dev The tag is FIRST, deliberately. `expandRandomness` hashes
-   * `[seed, tag]` with both slots caller-supplied, so tagging this circuit as
-   * `[secret, tag]` would make `secretToScalar(x)` identical to
-   * `expandRandomness(x, <this tag>)` reachable by passing this domain string
-   * to the parameter that exists to receive domain strings. Leading with the
-   * tag means reproducing this output through `expandRandomness` would require
-   * passing the domain constant as the *seed*. Do not normalise the orderings.
-   *
    * @param secret - The 32-byte secret to map.
-   * @return A Field guaranteed to be a valid Jubjub scalar.
+   * @return A valid Jubjub scalar.
    */
-  export pure circuit secretToScalar(secret: Bytes<32>): Field {
-    return degradeToTransient(
-             persistentHash<Vector<2, Bytes<32>>>(
-               [pad(32, "ElGamal:secretToScalar"), secret]
-             )
-           );
+  export pure circuit secretToScalar(secret: Bytes<32>): JubjubScalar {
+    return degradeToTransient(persistentHash<Vector<1, Bytes<32>>>([secret])) as JubjubScalar;
   }
 
   /**
@@ -159,49 +132,16 @@ module ElGamal {
    *
    * @param seed - The seed to expand.
    * @param tag - A 32-byte tag distinguishing this expansion from its siblings.
-   * @return A Field suitable for use as encryption randomness.
+   * @return A scalar suitable for use as encryption randomness.
    */
-  export pure circuit expandRandomness(seed: Bytes<32>, tag: Bytes<32>): Field {
-    return degradeToTransient(persistentHash<Vector<2, Bytes<32>>>([seed, tag]));
+  export pure circuit expandRandomness(seed: Bytes<32>, tag: Bytes<32>): JubjubScalar {
+    return degradeToTransient(persistentHash<Vector<2, Bytes<32>>>([seed, tag])) as JubjubScalar;
   }
 
   // ---------------------------------------------------------------------------
   // Curve helpers
   // ---------------------------------------------------------------------------
 
-  /**
-   * @description The order of the Jubjub prime-order subgroup (`EmbeddedFr`
-   * modulus `ℓ`), minus one. Used as the scalar for point negation: for any `P`
-   * in the subgroup, `(ℓ - 1) * P = ℓ*P - P = O - P = -P`.
-   *
-   * @notice The negation identity this enables (`P + (ℓ-1)*P == O`) is exercised
-   * by the `negate` round-trip tests. Compact has no module-level constants, so
-   * the value is exposed as a pure circuit returning the literal.
-   */
-  pure circuit JUBJUB_SUBGROUP_ORDER_MINUS_ONE(): Field {
-    return 6554484396890773809930967563523245729705921265872317281365359162392183254198 as Field;
-  }
-
-  /**
-   * @description Negates a Jubjub point.
-   *
-   * @notice Implemented as scalar multiplication by `ℓ-1` (via
-   * `JUBJUB_SUBGROUP_ORDER_MINUS_ONE`) rather than the obvious `ecMul(p, -1)`:
-   * the scalar `-1` computed in the `Field` type is `BLS_modulus - 1`, which
-   * exceeds the Jubjub scalar field order and faults `ecMul` ("failed to decode
-   * for built-in type EmbeddedFr"). (Coordinate negation `(-x, y)` via
-   * `constructJubjubPoint`/`jubjubPointX`/`jubjubPointY` is an equivalent
-   * alternative that does not depend on the subgroup assumption.) The
-   * `(ℓ-1)*P = -P` identity holds only in the prime-order subgroup, but that
-   * always applies here: the runtime constrains every assigned `JubjubPoint`
-   * into the prime-order subgroup (the embedded-curve gadget assigns points via
-   * cofactor clearing), so no in-subgroup precondition needs to be checked or
-   * assumed. See the module-level subgroup note.
-   */
-  pure circuit ecNeg(p: JubjubPoint): JubjubPoint {
-    return ecMul(p, JUBJUB_SUBGROUP_ORDER_MINUS_ONE());
-  }
-
   // ---------------------------------------------------------------------------
   // Encryption & homomorphic operations
   // ---------------------------------------------------------------------------
@@ -216,7 +156,7 @@ module ElGamal {
    * before treating it as private.
    */
   export pure circuit encryptZero(): Ciphertext {
-    const id = ecMulGenerator(0 as Field);
+    const id = ecMulGenerator(0 as JubjubScalar);
     return Ciphertext { c1: id, c2: id };
   }
 
@@ -244,9 +184,9 @@ module ElGamal {
    * @param r - The encryption randomness.
    * @return The ciphertext `(g^r, pk^r * m)`.
    */
-  export pure circuit encryptPoint(pk: JubjubPoint, m: JubjubPoint, r: Field): Ciphertext {
-    assert(pk != ecMulGenerator(0 as Field), "ElGamal: identity pk");
-    assert(r != 0 as Field, "ElGamal: zero randomness");
+  export pure circuit encryptPoint(pk: JubjubPoint, m: JubjubPoint, r: JubjubScalar): Ciphertext {
+    assert(pk != ecMulGenerator(0 as JubjubScalar), "ElGamal: identity pk");
+    assert(r != 0 as JubjubScalar, "ElGamal: zero randomness");
     const c1 = ecMulGenerator(r);
     const mask = ecMul(pk, r);
     const c2 = ecAdd(mask, m);
@@ -256,8 +196,8 @@ module ElGamal {
   /**
    * @description Produces a fresh ciphertext of `value` under `pk` with
    * randomness `r`, lifting `value` to the point `g^value`. Randomness is taken
-   * as a `Field` directly to avoid a redundant `Bytes<32> -> Field` conversion
-   * at every call site; `expandRandomness` produces `Field` for the same reason.
+   * as a scalar directly to avoid a redundant conversion at every call site;
+   * `expandRandomness` produces one for the same reason.
    *
    * Requirements:
    *
@@ -269,8 +209,8 @@ module ElGamal {
    * @param r - The encryption randomness.
    * @return The ciphertext `(g^r, pk^r * g^value)`.
    */
-  export pure circuit encrypt(pk: JubjubPoint, value: Uint<128>, r: Field): Ciphertext {
-    return encryptPoint(pk, ecMulGenerator(value as Field), r);
+  export pure circuit encrypt(pk: JubjubPoint, value: Uint<128>, r: JubjubScalar): Ciphertext {
+    return encryptPoint(pk, ecMulGenerator(value as JubjubScalar), r);
   }
 
   /**
@@ -340,7 +280,7 @@ module ElGamal {
    * @param k - The public scalar multiplier (a valid Jubjub scalar).
    * @return A ciphertext of `k * v`.
    */
-  export pure circuit scalarMul(ct: Ciphertext, k: Field): Ciphertext {
+  export pure circuit scalarMul(ct: Ciphertext, k: JubjubScalar): Ciphertext {
     return Ciphertext { c1: ecMul(ct.c1, k), c2: ecMul(ct.c2, k) };
   }
 
@@ -359,7 +299,7 @@ module ElGamal {
                         old: Ciphertext,
                         pk: JubjubPoint,
                         value: Uint<128>,
-                        r: Field
+                        r: JubjubScalar
                         ): Ciphertext {
     return add(old, encrypt(pk, value, r));
   }
@@ -382,7 +322,7 @@ module ElGamal {
                         old: Ciphertext,
                         pk: JubjubPoint,
                         value: Uint<128>,
-                        r: Field
+                        r: JubjubScalar
                         ): Ciphertext {
     return sub(old, encrypt(pk, value, r));
   }
@@ -410,7 +350,7 @@ module ElGamal {
    * @param r - Fresh, nonzero randomness for the rerandomization.
    * @return A fresh ciphertext of the same plaintext.
    */
-  export pure circuit rerandomize(ct: Ciphertext, pk: JubjubPoint, r: Field): Ciphertext {
+  export pure circuit rerandomize(ct: Ciphertext, pk: JubjubPoint, r: JubjubScalar): Ciphertext {
     return add(ct, encrypt(pk, 0, r));
   }
 
@@ -458,17 +398,14 @@ module ElGamal {
                    m: JubjubPoint
                    ): [] {
     // Inlines the same key check as `assertKeyPair` (rather than calling it) so
-    // `ekField` is computed once and reused for the decryption below, avoiding
+    // `ekScalar` is computed once and reused for the decryption below, avoiding
     // a second `secretToScalar` hash in this hot verification path.
-    const ekField = secretToScalar(ek);
-    assert(ecMulGenerator(ekField) == pk,
+    const ekScalar = secretToScalar(ek);
+    assert(ecMulGenerator(ekScalar) == pk,
            "ElGamal: ek/pk mismatch");
 
-    // m = c2 - ek*c1. ek*c1 is negated via ecNeg (scalar mul by ℓ-1) rather
-    // than ecMul by a negative scalar, which would exceed the Jubjub scalar
-    // field. ekField < ℓ (the subgroup order), so ecMul(ct.c1, ekField) is a
-    // valid scalar mul.
-    const ekC1 = ecMul(ct.c1, ekField);
+    // m = c2 - ek*c1, with ek*c1 negated via ecNeg.
+    const ekC1 = ecMul(ct.c1, ekScalar);
     const mPoint = ecAdd(ct.c2, ecNeg(ekC1));
     assert(mPoint == m,
            "ElGamal: plaintext mismatch");
@@ -482,17 +419,6 @@ module ElGamal {
    * wrong plaintext fails the decryption check. Lifted special case of
    * `assertDecryptsToPoint` with the message point `g^claimedValue`.
    *
-   * @notice `claimedValue` is the widest `Uint` Compact offers, so this parameter
-   * never bounds a caller. A narrower value costs proportionally fewer rows: the
-   * range constraint belongs to where the value is declared, not to this
-   * signature.
-   *
-   * @warning The claim domain must stay below the Jubjub subgroup order `l`:
-   * verification compares `g^claimedValue`, so two claims congruent mod `l` are
-   * indistinguishable. `Uint<248>` clears `l` (~2^251.86) by under 4 bits, and
-   * that width is set by Compact's cap rather than by this bound. 251 is the
-   * widest sound `Uint` if the cap ever rises.
-   *
    * Requirements:
    *
    * - `ek` is the secret for `pk`.
@@ -507,8 +433,8 @@ module ElGamal {
                    ct: Ciphertext,
                    pk: JubjubPoint,
                    ek: Bytes<32>,
-                   claimedValue: Uint<248>
+                   claimedValue: Uint<128>
                    ): [] {
-    assertDecryptsToPoint(ct, pk, ek, ecMulGenerator(claimedValue as Field));
+    assertDecryptsToPoint(ct, pk, ek, ecMulGenerator(claimedValue as JubjubScalar));
   }
 }

package/multisig/EcdsaSignerManager.compact

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (multisig/EcdsaSignerManager.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module EcdsaSignerManager
+ * @description Threshold authorization over secp256k1 ECDSA approvals for
+ * multisig contracts.
+ *
+ * Signer identities are stored as commitments: `persistentHash` over the
+ * signer's public-key coordinates, an instance salt, and a domain separator.
+ * The salt is per-deployment, so the same public key yields a different
+ * commitment in every instance and cannot be correlated across contracts.
+ *
+ * Wraps `Signer<Bytes<32>>` for the registry and threshold and configures it
+ * from `initialize`. Consuming contracts own the digest: they compute the
+ * message hash their signers signed, then hand it to `assertApprovals` with
+ * the parallel public-key and signature vectors.
+ *
+ * @notice Consuming contracts must not import `Signer` alongside this module.
+ * A second import instantiates a separate registry that `assertApprovals`
+ * never reads.
+ */
+module EcdsaSignerManager {
+  import CompactStandardLibrary;
+  import "../crypto/Ecdsa" prefix Ecdsa_;
+  import "./Signer"<Bytes<32>> prefix Signer_;
+
+  // Named import/re-export of the registry state only, so a consuming
+  // contract's ledger keys read as `_signers` rather than `Signer__signers`.
+  // The circuits stay behind the `Signer_` prefix.
+  import { _signers, _signerCount, _threshold } from "./Signer"<Bytes<32>>;
+  export { _signers, _signerCount, _threshold };
+
+  // ─── State ──────────────────────────────────────────────────────────────────
+
+  /**
+   * @description Deployment-supplied salt for signer commitments. Set at
+   * initialization and never changed. The registered commitments must have been
+   * derived under this same salt.
+   */
+  export sealed ledger _instanceSalt: Bytes<32>;
+
+  // ─── Types ──────────────────────────────────────────────────────────────────
+
+  /**
+   * @description Input to `persistentHash` for computing signer commitments.
+   */
+  struct SignerCommitmentInput {
+    pkX: Bytes<32>,
+    pkY: Bytes<32>,
+    salt: Bytes<32>,
+    domain: Bytes<32>
+  }
+
+  /**
+   * @description Accumulator threaded through the approval fold: the running
+   * valid count, the previous commitment (for duplicate detection), and the
+   * digest every signature is checked against.
+   */
+  struct VerificationState {
+    validCount: Uint<8>,
+    prevCommitment: Bytes<32>,
+    msgHash: Bytes<32>
+  }
+
+  // ─── Initialization ─────────────────────────────────────────────────────────
+
+  /**
+   * @description Stores the instance salt and registers the initial signer set.
+   * Call from the consuming contract's constructor only. Writes the `sealed`
+   * salt, so it cannot be reached from an exported circuit.
+   *
+   * Requirements:
+   *
+   * - Can only be called once.
+   * - `instanceSalt` should be cryptographically random.
+   * - `signerCommitments` must not contain duplicates.
+   * - `threshold` must be non-zero and must not exceed `n`.
+   * - `threshold` must not exceed 2, the number of approvals `assertApprovals`
+   *   verifies.
+   *
+   * @param {Bytes<32>} instanceSalt - Per-deployment salt for commitment derivation.
+   * @param {Vector<n, Bytes<32>>} signerCommitments - Hashed signer identities.
+   * @param {Uint<8>} threshold - Minimum approvals required.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit initialize<#n>(
+    instanceSalt: Bytes<32>,
+    signerCommitments: Vector<n, Bytes<32>>,
+    threshold: Uint<8>
+  ): [] {
+    assert(Signer_getSignerCount() == 0, "EcdsaSignerManager: signers already registered");
+    _instanceSalt = disclose(instanceSalt);
+    assert(threshold <= 2, "EcdsaSignerManager: threshold cannot exceed 2 (assertApprovals verifies 2 signatures)");
+
+    for (const commitment of signerCommitments) {
+      Signer__addSigner(commitment);
+    }
+    Signer__changeThreshold(threshold);
+  }
+
+  // ─── Commitments ────────────────────────────────────────────────────────────
+
+  /**
+   * @description Computes a signer commitment from a secp256k1 public key,
+   * as `persistentHash(pkX, pkY, salt, "multisig:signer:")`.
+   *
+   * Pure, so the deployer can derive constructor commitments off-chain the
+   * same way the circuits derive them in-circuit.
+   *
+   * Requirements:
+   *
+   * - `pk` must not be the secp256k1 identity point, which has no coordinates.
+   *
+   * @param {Secp256k1Point} pk - The secp256k1 public key.
+   * @param {Bytes<32>} salt - The instance salt.
+   * @returns {Bytes<32>} The signer commitment.
+   */
+  export pure circuit calculateSignerId(
+    pk: Secp256k1Point,
+    salt: Bytes<32>
+  ): Bytes<32> {
+    return persistentHash<SignerCommitmentInput>(SignerCommitmentInput {
+      pkX: secp256k1PointX(pk) as Bytes<32>,
+      pkY: secp256k1PointY(pk) as Bytes<32>,
+      salt: salt,
+      domain: pad(32, "multisig:signer:")
+    });
+  }
+
+  // ─── Approvals ──────────────────────────────────────────────────────────────
+
+  /**
+   * @description Verifies two approvals over `msgHash` and asserts the
+   * threshold is met.
+   *
+   * `pubkeys` and `signatures` are parallel: entry `i` of each belongs to the
+   * same signer.
+   *
+   * @dev Both entries are asserted, so the count handed to the threshold check
+   * is always 2 and a threshold below 2 admits nothing extra.
+   *
+   * @constraints k=17, rows=64916 (zkir-v3)
+   *
+   * Requirements:
+   *
+   * - Every public key must hash to a registered signer commitment.
+   * - Every signature must be valid over `msgHash` and use the low-s encoding.
+   * - Signers must not be duplicates.
+   *
+   * @param {Bytes<32>} msgHash - The digest the signers approved.
+   * @param {Vector<2, Secp256k1Point>} pubkeys - Public keys of approving signers.
+   * @param {Vector<2, Secp256k1EcdsaSignature>} signatures - Signatures over `msgHash`.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertApprovals(
+    msgHash: Bytes<32>,
+    pubkeys: Vector<2, Secp256k1Point>,
+    signatures: Vector<2, Secp256k1EcdsaSignature>
+  ): [] {
+    const initialState = VerificationState {
+      validCount: 0 as Uint<8>,
+      prevCommitment: pad(32, ""),
+      msgHash: msgHash
+    };
+
+    const finalState = fold(verifySignature, initialState, pubkeys, signatures);
+    Signer_assertThresholdMet(finalState.validCount);
+  }
+
+  /**
+   * @description Fold callback. Verifies one signer's approval.
+   *
+   * @notice Verification goes through `Ecdsa`'s low-s wrapper, so the high-s
+   * encoding of an approval is rejected as an invalid signature.
+   *
+   * @dev Duplicates are caught by comparing against the previous commitment
+   * alone, which is exhaustive only at width 2. Widening the approval vectors
+   * requires an all-pairs check.
+   *
+   * @param {VerificationState} state - Accumulator threaded through fold.
+   * @param {Secp256k1Point} pubkey - The signer's secp256k1 public key.
+   * @param {Secp256k1EcdsaSignature} signature - The signer's signature over `msgHash`.
+   * @returns {VerificationState} Updated accumulator.
+   */
+  circuit verifySignature(
+    state: VerificationState,
+    pubkey: Secp256k1Point,
+    signature: Secp256k1EcdsaSignature
+  ): VerificationState {
+    const commitment = calculateSignerId(pubkey, _instanceSalt);
+
+    assert(commitment != state.prevCommitment, "Multisig: duplicate signer");
+
+    Signer_assertSigner(commitment);
+
+    assert(
+      Ecdsa_secp256k1EcdsaVerifyLowS(state.msgHash, signature, pubkey),
+      "Multisig: invalid signature"
+    );
+
+    return VerificationState {
+      validCount: state.validCount + 1 as Uint<8>,
+      prevCommitment: commitment,
+      msgHash: state.msgHash
+    };
+  }
+
+  // ─── View ───────────────────────────────────────────────────────────────────
+
+  /**
+   * @description Returns the number of registered signers.
+   *
+   * @constraints k=6, rows=34 (zkir-v3)
+   *
+   * @returns {Uint<8>} The signer count.
+   */
+  export circuit getSignerCount(): Uint<8> {
+    return Signer_getSignerCount();
+  }
+
+  /**
+   * @description Returns the approval threshold.
+   *
+   * @constraints k=6, rows=34 (zkir-v3)
+   *
+   * @returns {Uint<8>} The threshold.
+   */
+  export circuit getThreshold(): Uint<8> {
+    return Signer_getThreshold();
+  }
+
+  /**
+   * @description Returns whether the given commitment is a registered signer.
+   *
+   * @constraints k=8, rows=129 (zkir-v3)
+   *
+   * @param {Bytes<32>} commitment - The signer commitment to check.
+   * @returns {Boolean} True if registered.
+   */
+  export circuit isSigner(commitment: Bytes<32>): Boolean {
+    return Signer_isSigner(commitment);
+  }
+}