@openzeppelin/compact-contracts 0.4.0-alpha.5 → 0.4.0

package/multisig/ProposalManager.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/ProposalManager.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/ProposalManager.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -8,14 +8,15 @@ pragma language_version >= 0.26.0;
  * @description Token-agnostic proposal lifecycle management for multisig
  * governance contracts.
  *
- * Supports shielded and unshielded proposals through a unified
- * Recipient type with a RecipientKind tag. Typed helper circuits
- * provide safe construction of recipients without exposing the
- * internal Bytes<32> representation to consumers.
+ * Supports shielded and unshielded proposals through the `Recipient` type
+ * and its `RecipientKind` tag, declared in `RecipientTypes` and re-exported
+ * here. Typed helper circuits provide safe construction of recipients
+ * without exposing the internal Bytes<32> representation to consumers.
  *
  * @warning PROPOSALS ARE PUBLIC. `_proposals` is exported ledger state, so
- * every proposal's recipient address, token color, amount, and state is
- * readable off-chain, and `_nextProposalId` reveals how many have been created.
+ * every proposal's recipient address, token color, amount, expiry, and status
+ * is readable off-chain, and `_nextProposalId` reveals how many have been
+ * created.
  * This holds regardless of which treasury a consumer composes: pairing this
  * module with `ShieldedTreasuryStateless` still publishes the full intent of
  * every transfer, even though the transfer itself is shielded. The transfer is
@@ -30,18 +31,23 @@ pragma language_version >= 0.26.0;
  */
 module ProposalManager {
   import CompactStandardLibrary;
+  import "./RecipientTypes";
+
+  export { Recipient, RecipientKind };
 
   // ─── Types ──────────────────────────────────────────────────────
 
   /**
-   * @description Proposal lifecycle states, derived from `Proposal.state` by
-   * `getProposalStatus`. Not stored on the ledger.
-   *
-   * - `Inactive`: no proposal with that id exists.
-   * - `Active`: `state` is an expiry in the future.
-   * - `Executed`: `state` is `executedState()`.
-   * - `Cancelled`: `state` is `cancelledState()`.
-   * - `Expired`: `state` is an expiry at or before the current block time.
+   * @description Proposal lifecycle status. `Proposal.status` stores `Active`,
+   * `Executed`, or `Cancelled`; `getProposalStatus` derives the other two.
+   *
+   * - `Inactive`: no proposal with that id exists. Never stored.
+   * - `Active`: created and not retired. Stored. Executable only while the
+   *   block time is below `Proposal.expiry`.
+   * - `Executed`: `_markExecuted` ran. Stored, terminal.
+   * - `Cancelled`: `_cancelProposal` ran. Stored, terminal.
+   * - `Expired`: stored `Active` with an `expiry` at or before the current
+   *   block time. Never stored.
    */
   export enum ProposalStatus {
     Inactive,
@@ -52,69 +58,30 @@ module ProposalManager {
   }
 
   /**
-   * @description What a `Recipient`'s bytes are and which rail accepts them.
-   *
-   * - `ShieldedUser`: a Zswap coin public key. `toShieldedRecipient` only.
-   * - `UnshieldedUser`: a user address. `toUnshieldedRecipient` only.
-   * - `Contract`: a contract address. Accepted by both.
-   *
-   * @warning `toShieldedRecipient` rejects `UnshieldedUser` and
-   * `toUnshieldedRecipient` rejects `ShieldedUser`, both at execution rather
-   * than at creation. That mismatch is the hazard noted in `_createProposal`.
-   */
-  export enum RecipientKind {
-    ShieldedUser,
-    UnshieldedUser,
-    Contract
-  }
-
-  /**
-   * @description A transfer target.
-   *
-   * @warning `address` is raw 32 bytes. `kind` alone decides whether they are
-   * read as a Zswap coin public key, a user address, or a contract address.
-   */
-  export struct Recipient {
-    kind: RecipientKind,
-    address: Bytes<32>
-  }
-
-  /**
-   * @description A proposal. `state` holds both the lifecycle stage and the
-   * expiry in a single field:
+   * @description A proposal. `status` is the stored lifecycle stage and
+   * `expiry` is the deadline, as seconds since the Unix epoch. Reaching a
+   * terminal stage changes `status` only, so an executed or cancelled proposal
+   * keeps the deadline it was created with.
    *
-   * - `executedState()` (1): executed.
-   * - `cancelledState()` (2): cancelled.
-   * - any greater value: the expiry, as seconds since the Unix epoch. The
-   *   proposal is active while the block time is below it and expired
-   *   afterwards.
-   *
-   * `_createProposal` rejects an `expiry` in the reserved range, so a proposal
-   * that has not reached a terminal state always has `state` greater than
-   * `cancelledState()`. Note that `Expired` is NOT terminal: a lapsed proposal
-   * still carries its original deadline, which is what tells a reader when it
-   * lapsed.
-   *
-   * @warning In the deadline range, `state` marks when a proposal STOPS being
-   * executable, not when it starts: it is executable while `blockTime < state`
-   * and inert once `blockTime >= state`.
+   * @warning `expiry` marks when a proposal STOPS being executable, not when it
+   * starts: an `Active` proposal is executable while `blockTime < expiry` and
+   * inert once `blockTime >= expiry`.
    *
    * @notice This module implements no execution delay. `expiry` bounds how long
    * a proposal stays valid; it does not impose a minimum wait before it may be
    * executed. A consumer that needs a delay must compose one.
    *
-   * @notice Off-chain readers decode `state` themselves, applying the sentinel
-   * checks and the deadline comparison above. `_proposals` is exported ledger
-   * state and readable without a proof. `executedState` and
-   * `cancelledState` are pure, so a reader can obtain the sentinel values without
-   * hardcoding them. A state-reading accessor will be revisited once contract-to-contract
-   * interactions are available.
+   * @notice `_proposals` is exported ledger state and readable without a proof.
+   * An off-chain reader takes `status` as stored and, when it is `Active`,
+   * compares `expiry` with the current block time. A state-reading accessor
+   * will be revisited once contract-to-contract interactions are available.
    */
   export struct Proposal {
     to: Recipient,
     color: Bytes<32>,
     amount: Uint<128>,
-    state: Uint<64>
+    expiry: Uint<64>,
+    status: ProposalStatus
   }
 
   // ─── State ──────────────────────────────────────────────────────
@@ -136,43 +103,23 @@ module ProposalManager {
 
   /**
    * @description Proposals by id, keyed by the value `_nextProposalId` produced
-   * at creation. Each entry carries the recipient, token color, amount, and the
-   * overlaid lifecycle/expiry encoding documented on `Proposal`.
+   * at creation. Each entry carries the recipient, token color, amount, expiry,
+   * and lifecycle status documented on `Proposal`.
    * @type {Uint<64>} id - The proposal identifier, issued by `_nextProposalId`.
    * @type {Proposal} proposal - The proposal record.
    * @type {Map<id, proposal>}
    * @type {Map<Uint<64>, Proposal>} _proposals
    *
-   * @notice Entries are never deleted. Reaching a terminal state overwrites
-   * `state` in place so the map only grows, and no circuit here prunes it.
+   * @notice Entries are never deleted. Reaching a terminal stage overwrites
+   * `status` in place so the map only grows, and no circuit here prunes it.
    * A consumer that needs cleanup must compose its own.
    *
    * @notice Readable off-chain without a proof so integrators read this map
-   * directly rather than calling a circuit. Decoding `state` is the reader's
-   * job. See `Proposal`
+   * directly rather than calling a circuit. See `Proposal` for how `status`
+   * and `expiry` combine.
    */
   export ledger _proposals: Map<Uint<64>, Proposal>;
 
-  // ─── State Sentinels ────────────────────────────────────────────
-
-  /**
-   * @description The `Proposal.state` value marking a proposal as executed.
-   *
-   * @returns {Uint<64>} 1.
-   */
-  export pure circuit executedState(): Uint<64> {
-    return 1;
-  }
-
-  /**
-   * @description The `Proposal.state` value marking a proposal as cancelled.
-   *
-   * @returns {Uint<64>} 2.
-   */
-  export pure circuit cancelledState(): Uint<64> {
-    return 2;
-  }
-
   // ─── Recipient Helpers ──────────────────────────────────────────
 
   /**
@@ -278,8 +225,8 @@ module ProposalManager {
 
   /**
    * @description Asserts that a proposal exists and is still executable. The two
-   * checks are separate: a terminal `state` (executed or cancelled) fails the
-   * first, and a deadline that has passed fails the second, so the error message
+   * checks are separate: a `status` other than `Active` fails the first, and a
+   * deadline that has passed fails the second, so the error message
    * distinguishes the two.
    *
    * @notice Expiry is terminal, unlike a conflicting read. A tx rejected
@@ -290,10 +237,10 @@ module ProposalManager {
    * Requirements:
    *
    * - Proposal must exist.
-   * - Proposal must not be executed or cancelled.
+   * - Proposal `status` must be `Active`.
    * - Proposal must not have expired.
    *
-   * @constraints k=9, rows=129
+   * @constraints k=7, rows=103
    *
    * @param {Uint<64>} id - The proposal ID.
    *
@@ -302,13 +249,13 @@ module ProposalManager {
   export circuit assertProposalActive(id: Uint<64>): [] {
     assertProposalExists(id);
 
-    const state = _proposals.lookup(disclose(id)).state;
+    const proposal = _proposals.lookup(disclose(id));
     assert(
-      state > cancelledState(),
+      proposal.status == ProposalStatus.Active,
       "ProposalManager: proposal not active"
     );
     assert(
-      blockTimeLt(state),
+      blockTimeLt(proposal.expiry),
       "ProposalManager: proposal expired"
     );
   }
@@ -341,11 +288,6 @@ module ProposalManager {
    * reintroducing the immortal proposal this field exists to prevent. Consuming
    * contracts that need a bounded lifetime must impose their own cap.
    *
-   * @notice `expiry` is also rejected if it falls in the sentinel range, keeping
-   * the two domains `state` overlays disjoint. That check is enforced here rather
-   * than left to the future check, so disjointness holds for whatever block time
-   * the executing environment reports.
-   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy.
@@ -353,10 +295,9 @@ module ProposalManager {
    * Requirements:
    *
    * - `amount` must be greater than 0.
-   * - `expiry` must be greater than `cancelledState()`.
    * - `expiry` must be in the future.
    *
-   * @constraints k=10, rows=913
+   * @constraints k=10, rows=883
    *
    * @param {Recipient} to - The recipient (constructed via helper circuits).
    * @param {Bytes<32>} color - The token color.
@@ -373,10 +314,6 @@ module ProposalManager {
     expiry: Uint<64>
   ): Uint<64> {
     assert(amount > 0, "ProposalManager: zero amount");
-    assert(
-      expiry > cancelledState(),
-      "ProposalManager: expiry in reserved range"
-    );
     assert(
       blockTimeLt(disclose(expiry)),
       "ProposalManager: expiry not in the future"
@@ -391,7 +328,8 @@ module ProposalManager {
       to: to,
       color: color,
       amount: amount,
-      state: expiry
+      expiry: expiry,
+      status: ProposalStatus.Active
     }));
 
     return id;
@@ -420,7 +358,8 @@ module ProposalManager {
       to: proposal.to,
       color: proposal.color,
       amount: proposal.amount,
-      state: cancelledState()
+      expiry: proposal.expiry,
+      status: ProposalStatus.Cancelled
     });
   }
 
@@ -447,16 +386,17 @@ module ProposalManager {
       to: proposal.to,
       color: proposal.color,
       amount: proposal.amount,
-      state: executedState()
+      expiry: proposal.expiry,
+      status: ProposalStatus.Executed
     });
   }
 
   // ─── View ───────────────────────────────────────────────────────
 
   /**
-   * @description Returns the full proposal data. The returned `state` is the
-   * raw encoded field. See `Proposal` for how to read it, and prefer
-   * `getProposalStatus` when the lifecycle stage is what is wanted.
+   * @description Returns the full proposal data. The returned `status` is the
+   * stored stage, so an `Active` entry may already be past its `expiry`.
+   * Prefer `getProposalStatus` when the effective status is what is wanted.
    *
    * @param {Uint<64>} id - The proposal ID.
    *
@@ -504,9 +444,10 @@ module ProposalManager {
   }
 
   /**
-   * @description Derives the lifecycle status of a proposal from its `state`
-   * field and the current block time. Returns `Inactive` for an id that was
-   * never created rather than failing.
+   * @description Derives the effective lifecycle status of a proposal: the
+   * stored `status` unless it is `Active`, in which case `expiry` and the
+   * current block time decide between `Active` and `Expired`. Returns
+   * `Inactive` for an id that was never created rather than failing.
    *
    * @constraints k=9, rows=252
    *
@@ -519,14 +460,11 @@ module ProposalManager {
       return ProposalStatus.Inactive;
     }
 
-    const state = _proposals.lookup(disclose(id)).state;
-    if (state == executedState()) {
-      return ProposalStatus.Executed;
-    }
-    if (state == cancelledState()) {
-      return ProposalStatus.Cancelled;
+    const proposal = _proposals.lookup(disclose(id));
+    if (proposal.status != ProposalStatus.Active) {
+      return proposal.status;
     }
-    if (blockTimeLt(state)) {
+    if (blockTimeLt(proposal.expiry)) {
       return ProposalStatus.Active;
     }
     return ProposalStatus.Expired;

package/multisig/RecipientTypes.compact

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/RecipientTypes.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module RecipientTypes
+ * @description The transfer-target types shared by the multisig modules.
+ *
+ * This module holds no ledger state. Importing a module allocates every
+ * ledger field it declares, so a contract that needs only the recipient
+ * types imports this module rather than `ProposalManager`, which would add
+ * a `_nextProposalId` and `_proposals` the contract never writes.
+ * `ProposalManager` re-exports both types and provides the typed helper
+ * circuits that build and route recipients.
+ */
+module RecipientTypes {
+  import CompactStandardLibrary;
+
+  /**
+   * @description What a `Recipient`'s bytes are and which rail accepts them.
+   *
+   * - `ShieldedUser`: a Zswap coin public key. `ProposalManager.toShieldedRecipient` only.
+   * - `UnshieldedUser`: a user address. `ProposalManager.toUnshieldedRecipient` only.
+   * - `Contract`: a contract address. Accepted by both.
+   *
+   * @warning `toShieldedRecipient` rejects `UnshieldedUser` and
+   * `toUnshieldedRecipient` rejects `ShieldedUser`, both at execution rather
+   * than at creation. That mismatch is the hazard noted in
+   * `ProposalManager._createProposal`.
+   */
+  export enum RecipientKind {
+    ShieldedUser,
+    UnshieldedUser,
+    Contract
+  }
+
+  /**
+   * @description A transfer target.
+   *
+   * @warning `address` is raw 32 bytes. `kind` alone decides whether they are
+   * read as a Zswap coin public key, a user address, or a contract address.
+   */
+  export struct Recipient {
+    kind: RecipientKind,
+    address: Bytes<32>
+  }
+}

package/multisig/Secp256k1EcdsaMultisig.compact

@@ -0,0 +1,275 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/Secp256k1EcdsaMultisig.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module Secp256k1EcdsaMultisig<#t>
+ * @description
+ * A `t`-of-`n` accountable multisignature over secp256k1 ECDSA: `n` signer
+ * commitments are registered at deploy, and a call passes when `t` distinct
+ * registered signers have signed the digest. The threshold `t` is the module
+ * generic, so it is also the approval count every gated call carries.
+ *
+ * @dev Notation:
+ * - `H(...)`: `persistentHash` (SHA-256), a `Bytes<32>` digest.
+ * - `cm = H(pkX, pkY, salt, "Secp256k1EcdsaMultisig:signer")`: a signer
+ *   commitment, over the affine coordinates of the secp256k1 public key.
+ * - `n`: signers registered at `initialize`.
+ * - `t`: the threshold and the `assertApprovals` width.
+ *
+ * @dev Derivations:
+ * `H` hashes the `SignerCommitmentInput` struct in Compact's encoding, not a
+ * byte concatenation. Do not reimplement it: `calculateSignerId` is the
+ * exported pure circuit, and the consumer test suites pin its vectors. A
+ * wrong derivation registers commitments no key can satisfy.
+ *
+ * @dev Parameterization:
+ * `t` is fixed at import (`import "./Secp256k1EcdsaMultisig"<2> prefix
+ * Secp256k1EcdsaMultisig_;`) and `n` per `initialize<#n>` call. `Signer`
+ * enforces `n >= t` at `initialize`. No circuit takes a threshold argument.
+ * `t = 0` does not compile.
+ *
+ * @dev Compatibility:
+ * The wire format is the `Secp256k1EcdsaMultisig:signer` domain, the
+ * `SignerCommitmentInput` layout, and the salt. Changing any of them orphans
+ * every registered signer set. The digest is the consumer's and is not part
+ * of this module's format.
+ *
+ * @notice Privacy:
+ * - Public, per tx: the `t` commitments (`disclose(commitment)` in
+ *   `Signer_assertSigner`), so WHICH signers approved.
+ * - Public, as state: `_signers`, `_signerCount`, `_threshold`,
+ *   `_instanceSalt`. All exported.
+ * - Private: public keys and signatures, verified in-circuit and never
+ *   disclosed; the digest, beyond what the consumer publishes.
+ * - Signer identity: keys sit behind `cm` with a public salt, so an observer
+ *   holding a candidate key can test membership; one without cannot
+ *   correlate a signer across deployments.
+ *
+ * @notice Security:
+ * - Order: `assertApprovals` runs `Signer_assertThresholdMet(t)` first, so an
+ *   uninitialized registry fails before any signature work. Then pairwise
+ *   distinct commitments, then per entry a registered commitment and a valid
+ *   signature.
+ * - Low-s: verification goes through `Ecdsa_secp256k1EcdsaVerifyLowS`, so a
+ *   high-s encoding is an invalid signature.
+ * - Distinct signers: all `t(t-1)/2` pairs are compared, so no key counts
+ *   twice.
+ * - Bounds: `Signer` rejects `t > n` at `initialize`.
+ * - Once-only: `initialize` rejects a second call while signers are
+ *   registered, and writes the `sealed` salt, so it is constructor-only.
+ * - Immutable to the deployed circuit set: no signer or threshold change is
+ *   exported. Losing more than `n - t` keys freezes every gated circuit.
+ * - Digest binding is the consumer's: this module verifies signatures over
+ *   whatever `msgHash` it is handed. Replay, domain and instance binding
+ *   belong in the digest.
+ * - Atomicity: a failed assert rejects the whole tx before any state moves,
+ *   and the sender pays no fee.
+ *
+ * @notice Concurrency:
+ * - Every read (`_threshold`, `_signers.member(cm)`, `_instanceSalt`) is
+ *   state written only by `initialize`, so `assertApprovals` and the views
+ *   commute with everything, including each other.
+ *
+ * @notice Scope:
+ * Registry and verification only: no digest construction, no nonce, no
+ * roles, no signer rotation. The consumer builds the digest and gates its
+ * circuits with `assertApprovals`.
+ *
+ * @notice Client-side duties:
+ * - Before deploy: pick a random `instanceSalt`, derive each `cm` with
+ *   `calculateSignerId(pk, salt)`, pass them as `signerCommitments`.
+ * - Per call: collect exactly `t` low-s signatures from distinct signers over
+ *   the consumer's digest, submit keys and signatures in matching `Vector<t>`
+ *   positions.
+ *
+ * @dev Performance:
+ * - Cost is per entry: one ECDSA verify and one `H` for each of the `t`
+ *   approvals, plus `t(t-1)/2` `Bytes<32>` compares.
+ * - `assertApprovals` (zkir-v3): `t = 1` is k=16, rows=40538; `t = 2` is
+ *   k=17, rows=64908; `t = 3` is k=17, rows=94995.
+ *
+ * @dev Composition:
+ * - Import this module at exactly one width per contract. Two widths
+ *   instantiate two `Secp256k1EcdsaMultisig` modules over one shared
+ *   `Signer<Bytes<32>>` registry, so the second `initialize` trips the
+ *   once-only guard and that width's `_instanceSalt` is never written.
+ * - Do not import `Signer` alongside this module. A direct import
+ *   instantiates a separate registry that `assertApprovals` never reads.
+ */
+module Secp256k1EcdsaMultisig<#t> {
+  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 };
+
+  /**
+   * @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>;
+
+  /**
+   * @description Input to `persistentHash` for computing signer commitments.
+   */
+  struct SignerCommitmentInput {
+    pkX: Bytes<32>,
+    pkY: Bytes<32>,
+    salt: Bytes<32>,
+    domain: Bytes<32>
+  }
+
+  /**
+   * @description Stores the instance salt and registers the signer set at
+   * threshold `t`. Call from the consuming contract's constructor only.
+   * Writes the `sealed` salt, so it cannot be reached from an exported
+   * circuit. The set is final: signers must be known at deploy and no circuit
+   * adds, removes or replaces one afterwards.
+   *
+   * Requirements:
+   *
+   * - Can only be called once.
+   * - `instanceSalt` should be cryptographically random.
+   * - `signerCommitments` must not contain duplicates.
+   * - `n` must be at least `t`.
+   *
+   * @param {Bytes<32>} instanceSalt - Per-deployment salt for commitment derivation.
+   * @param {Vector<n, Bytes<32>>} signerCommitments - Hashed signer identities.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit initialize<#n>(
+    instanceSalt: Bytes<32>,
+    signerCommitments: Vector<n, Bytes<32>>
+  ): [] {
+    assert(Signer_getSignerCount() == 0, "Secp256k1EcdsaMultisig: signers already registered");
+    _instanceSalt = disclose(instanceSalt);
+
+    for (const commitment of signerCommitments) {
+      Signer__addSigner(commitment);
+    }
+    Signer__changeThreshold(t);
+  }
+
+  /**
+   * @description Verifies `t` approvals over `msgHash`: distinct registered
+   * signers, each with a valid low-s signature.
+   *
+   * `pubkeys` and `signatures` are parallel: entry `i` of each belongs to the
+   * same signer.
+   *
+   * Requirements:
+   *
+   * - The module must be initialized.
+   * - No two entries may be the same signer.
+   * - Every public key must hash to a registered signer commitment.
+   * - Every signature must be valid over `msgHash` and use the low-s encoding.
+   *
+   * @param {Bytes<32>} msgHash - The digest the signers approved.
+   * @param {Vector<t, Secp256k1Point>} pubkeys - Public keys of approving signers.
+   * @param {Vector<t, Secp256k1EcdsaSignature>} signatures - Signatures over `msgHash`.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertApprovals(
+    msgHash: Bytes<32>,
+    pubkeys: Vector<t, Secp256k1Point>,
+    signatures: Vector<t, Secp256k1EcdsaSignature>
+  ): [] {
+    Signer_assertThresholdMet(t);
+
+    const commitments = map(signerCommitment, pubkeys);
+
+    for (const i of 0..t) {
+      for (const j of 0..t) {
+        if (i < j) {
+          assert(commitments[i] != commitments[j], "Secp256k1EcdsaMultisig: duplicate signer");
+        }
+      }
+    }
+
+    for (const i of 0..t) {
+      Signer_assertSigner(commitments[i]);
+      assert(
+        Ecdsa_secp256k1EcdsaVerifyLowS(msgHash, signatures[i], pubkeys[i]),
+        "Secp256k1EcdsaMultisig: invalid signature"
+      );
+    }
+  }
+
+  /**
+   * @description `map` callback. Commits `pk` under the instance salt.
+   *
+   * @param {Secp256k1Point} pk - The signer's secp256k1 public key.
+   * @returns {Bytes<32>} The signer commitment.
+   */
+  circuit signerCommitment(pk: Secp256k1Point): Bytes<32> {
+    return calculateSignerId(pk, _instanceSalt);
+  }
+
+  /**
+   * @description Computes a signer commitment from a secp256k1 public key,
+   * as `persistentHash(pkX, pkY, salt, "Secp256k1EcdsaMultisig: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, "Secp256k1EcdsaMultisig:signer")
+    });
+  }
+
+  /**
+   * @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);
+  }
+}