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

package/README.md

@@ -1,4 +1,4 @@
-[![Generic badge](https://img.shields.io/badge/Compact%20Compiler-0.31.0-1abc9c.svg)](https://docs.midnight.network/relnotes/compact/minokawa-0-18-26-0)
+[![Generic badge](https://img.shields.io/badge/Compact%20Compiler-0.34.0-1abc9c.svg)](https://docs.midnight.network/relnotes/compact/)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
 
 This project is built on the Midnight Network.
@@ -37,8 +37,8 @@ Follow Midnight's [Compact Developer Tools installation guide](https://docs.midn
 ```bash
 $ compact compile --version
 
-Compactc version: 0.31.0
-0.31.0
+Compactc version: 0.34.0
+0.34.0
 ```
 
 ### Installation
@@ -64,7 +64,7 @@ Import the modules through `./node_modules/@openzeppelin/compact-contracts/...`.
 ```typescript
 // MyContract.compact
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.26.0;
 
 import CompactStandardLibrary;
 import "./node_modules/@openzeppelin/compact-contracts/access/Ownable"
@@ -189,6 +189,12 @@ Compiling 14 circuits:
 Overall progress [====================] 14/14
 ```
 
+ZKIR v3: the library targets ZKIR v2, the compiler 0.34.0 default. Pass
+`--feature-zkir-v3` only when the contract imports the secp256k1-based modules
+(`crypto/Ecdsa`, `multisig/EcdsaSignerManager`, `ShieldedMultiSigV2`,
+`ShieldedMultiSigV3`). Compiling the other modules under v3 currently hits
+upstream blockers, listed under [Known issues](CHANGELOG.md#known-issues).
+
 ## Development
 
 OpenZeppelin Contracts for Compact exists thanks to its contributors.

package/access/AccessControl.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (access/AccessControl.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (access/AccessControl.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module AccessControl

package/access/Ownable.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (access/Ownable.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (access/Ownable.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module Ownable

package/access/ShieldedAccessControl.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (access/ShieldedAccessControl.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (access/ShieldedAccessControl.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module ShieldedAccessControl

package/access/ZOwnablePK.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (access/ZOwnablePK.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (access/ZOwnablePK.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module ZOwnablePK

package/crypto/EcdhMask.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (crypto/EcdhMask.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (crypto/EcdhMask.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module EcdhMask
@@ -142,10 +142,10 @@ module EcdhMask {
   export pure circuit encrypt(
                         recipientPk: JubjubPoint,
                         value: Uint<128>,
-                        e: Field,
+                        e: JubjubScalar,
                         domain: Bytes<32>
                         ): Ciphertext {
-    const identity = ecMulGenerator(0 as Field);
+    const identity = ecMulGenerator(0 as JubjubScalar);
     assert(recipientPk != identity, "EcdhMask: identity pk");
     const ephemeralPk = ecMulGenerator(e);
     // Guard the ephemeral POINT, not the scalar: `ephemeralPk == identity`
@@ -169,7 +169,7 @@ module EcdhMask {
    * @return The recovered value as a `Field` (equal to the original `value`,
    *         which is `< 2^128`).
    */
-  export pure circuit decrypt(ciphertext: Ciphertext, ekScalar: Field, domain: Bytes<32>): Field {
+  export pure circuit decrypt(ciphertext: Ciphertext, ekScalar: JubjubScalar, domain: Bytes<32>): Field {
     const sShared = ecMul(ciphertext.ephemeralPk, ekScalar);
     const mask = kdf(sShared, domain);
     return ciphertext.ct - mask;

package/crypto/Ecdsa.compact

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (crypto/Ecdsa.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module Ecdsa
+ * @description The low-s rule for secp256k1 ECDSA signatures.
+ *
+ * `secp256k1EcdsaVerify` accepts both `(r, s)` and `(r, n - s)`, so every valid
+ * signature has a second valid encoding that anyone can derive without the
+ * signing key. Its own documentation leaves the low-s constraint to the caller.
+ * This module is that constraint: reject `s > n / 2` and each signature has one
+ * encoding, which is what replay sets, nullifiers, and signature-derived
+ * identifiers rely on.
+ */
+module Ecdsa {
+  import CompactStandardLibrary;
+
+  /**
+   * @description Returns whether `s` is canonical, i.e. `s <= n / 2` where `n`
+   * is the secp256k1 group order.
+   *
+   * @circuitInfo k=13, rows=5125
+   *
+   * @param {Secp256k1Scalar} s - The `s` component of a signature.
+   * @returns {Boolean} True if `s` is in the low half.
+   */
+  export pure circuit isLowS(s: Secp256k1Scalar): Boolean {
+    const sBytes = (s as Bytes<32>) as Vector<32, Uint<8>>;
+    return fold(compareByteLe, true, sBytes, SECP256K1_HALF_ORDER_LE());
+  }
+
+  /**
+   * @description Fold callback over one little-endian byte pair. A differing
+   * pair overrides the running result, so the accumulator ends up holding the
+   * comparison at the most significant byte where `s` and `n / 2` differ. All
+   * pairs equal leaves the seed untouched, which is what makes the comparison
+   * inclusive.
+   *
+   * @param {Boolean} isLow - Result from the less significant bytes.
+   * @param {Uint<8>} sByte - Byte of `s`.
+   * @param {Uint<8>} halfByte - Byte of `n / 2`.
+   * @returns {Boolean} Updated result.
+   */
+  pure circuit compareByteLe(
+    isLow: Boolean,
+    sByte: Uint<8>,
+    halfByte: Uint<8>
+  ): Boolean {
+    return sByte == halfByte ? isLow : sByte < halfByte;
+  }
+
+  /**
+   * @description `n / 2` as little-endian bytes, matching the byte order of
+   * `Secp256k1Scalar as Bytes<32>`.
+   *
+   * @returns {Vector<32, Uint<8>>} The bytes of `n / 2`, least significant first.
+   */
+  pure circuit SECP256K1_HALF_ORDER_LE(): Vector<32, Uint<8>> {
+    // 0x7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b20a0
+    return [
+      160, 32, 27, 104, 70, 47, 233, 223,
+      29, 80, 164, 87, 115, 110, 87, 93,
+      255, 255, 255, 255, 255, 255, 255, 255,
+      255, 255, 255, 255, 255, 255, 255, 127
+    ];
+  }
+
+  // ─── Verification ───────────────────────────────────────────────────────────
+
+  /**
+   * @description Rejects a signature in the high half.
+   *
+   * @circuitInfo k=13, rows=5156
+   *
+   * Requirements:
+   *
+   * - `sig.s` must satisfy `s <= n / 2`.
+   *
+   * @param {Secp256k1EcdsaSignature} sig - The signature to check.
+   * @returns {[]} Empty tuple.
+   */
+  export pure circuit assertLowS(sig: Secp256k1EcdsaSignature): [] {
+    assert(isLowS(sig.s), "Ecdsa: high-s signature");
+  }
+
+  /**
+   * @description Verifies `sig` over `msgHash` under `pk`, accepting only the
+   * low-s encoding. Reports the result instead of asserting, so a caller can
+   * fold it into a count or a threshold.
+   *
+   * @circuitInfo k=16, rows=34056
+   *
+   * @param {Bytes<32>} msgHash - The digest that was signed.
+   * @param {Secp256k1EcdsaSignature} sig - The signature over `msgHash`.
+   * @param {Secp256k1Point} pk - The signer's public key.
+   * @returns {Boolean} True if the signature is valid and canonical.
+   */
+  export pure circuit secp256k1EcdsaVerifyLowS(
+    msgHash: Bytes<32>,
+    sig: Secp256k1EcdsaSignature,
+    pk: Secp256k1Point
+  ): Boolean {
+    // TODO: inline into the return once a guarded stdlib verify compiles.
+    // Short-circuiting `&&` puts it behind a guard, which trips an internal
+    // error in the compiler's missing-guard-workarounds pass.
+    const verified = secp256k1EcdsaVerify(msgHash, sig, pk);
+    return isLowS(sig.s) && verified;
+  }
+}

package/crypto/ElGamal.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (crypto/ElGamal.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (crypto/ElGamal.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module ElGamal
@@ -32,7 +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 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
@@ -43,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 —
@@ -103,10 +106,10 @@ module ElGamal {
    * module-level hash-to-scalar note for why `degradeToTransient` is required.
    *
    * @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<1, Bytes<32>>>([secret]));
+  export pure circuit secretToScalar(secret: Bytes<32>): JubjubScalar {
+    return degradeToTransient(persistentHash<Vector<1, Bytes<32>>>([secret])) as JubjubScalar;
   }
 
   /**
@@ -129,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
   // ---------------------------------------------------------------------------
@@ -186,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 };
   }
 
@@ -214,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);
@@ -226,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:
    *
@@ -239,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);
   }
 
   /**
@@ -310,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) };
   }
 
@@ -329,7 +299,7 @@ module ElGamal {
                         old: Ciphertext,
                         pk: JubjubPoint,
                         value: Uint<128>,
-                        r: Field
+                        r: JubjubScalar
                         ): Ciphertext {
     return add(old, encrypt(pk, value, r));
   }
@@ -352,7 +322,7 @@ module ElGamal {
                         old: Ciphertext,
                         pk: JubjubPoint,
                         value: Uint<128>,
-                        r: Field
+                        r: JubjubScalar
                         ): Ciphertext {
     return sub(old, encrypt(pk, value, r));
   }
@@ -380,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));
   }
 
@@ -428,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");
@@ -468,6 +435,6 @@ module ElGamal {
                    ek: Bytes<32>,
                    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,229 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (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. 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.
+ *
+ * The module's ledger is not exported, so a contract importing it under a
+ * prefix keeps the salt and the signer registry out of its generated
+ * `ledger()` reader.
+ */
+module EcdsaSignerManager {
+  import CompactStandardLibrary;
+  import "../crypto/Ecdsa" prefix Ecdsa_;
+  import "./Signer"<Bytes<32>> prefix Signer_;
+
+  // ─── State ──────────────────────────────────────────────────────────────────
+
+  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.
+   *
+   * 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>
+  ): [] {
+    _instanceSalt = disclose(instanceSalt);
+    assert(threshold <= 2, "EcdsaSignerManager: threshold cannot exceed 2 (assertApprovals verifies 2 signatures)");
+    Signer_initialize<n>(signerCommitments, 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.
+   *
+   * @circuitInfo k=17, rows=64916
+   *
+   * 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.
+   *
+   * @circuitInfo k=6, rows=34
+   *
+   * @returns {Uint<8>} The signer count.
+   */
+  export circuit getSignerCount(): Uint<8> {
+    return Signer_getSignerCount();
+  }
+
+  /**
+   * @description Returns the approval threshold.
+   *
+   * @circuitInfo k=6, rows=34
+   *
+   * @returns {Uint<8>} The threshold.
+   */
+  export circuit getThreshold(): Uint<8> {
+    return Signer_getThreshold();
+  }
+
+  /**
+   * @description Returns whether the given commitment is a registered signer.
+   *
+   * @circuitInfo k=8, rows=129
+   *
+   * @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);
+  }
+}