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

package/access/AccessControl.compact

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

package/access/Ownable.compact

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

package/access/ShieldedAccessControl.compact

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

package/access/ZOwnablePK.compact

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

package/crypto/EcdhMask.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (crypto/EcdhMask.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (crypto/EcdhMask.compact)
 
 pragma language_version >= 0.23.0;
 

package/crypto/ElGamal.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (crypto/ElGamal.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (crypto/ElGamal.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -34,6 +34,13 @@ pragma language_version >= 0.23.0;
  * scalar. Feeding a raw `persistentHash` output into `ecMulGenerator` would
  * occasionally exceed the Jubjub scalar field order and fault at runtime.
  *
+ * @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 TRUST ASSUMPTION — subgroup membership. This is the module's most
  * load-bearing assumption. Every `JubjubPoint` reaching a curve operation is
  * assumed to be in the Jubjub prime-order subgroup, including points supplied by
@@ -102,11 +109,34 @@ 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.
    */
   export pure circuit secretToScalar(secret: Bytes<32>): Field {
-    return degradeToTransient(persistentHash<Vector<1, Bytes<32>>>([secret]));
+    return degradeToTransient(
+             persistentHash<Vector<2, Bytes<32>>>(
+               [pad(32, "ElGamal:secretToScalar"), secret]
+             )
+           );
   }
 
   /**
@@ -452,6 +482,17 @@ 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`.
@@ -466,7 +507,7 @@ module ElGamal {
                    ct: Ciphertext,
                    pk: JubjubPoint,
                    ek: Bytes<32>,
-                   claimedValue: Uint<128>
+                   claimedValue: Uint<248>
                    ): [] {
     assertDecryptsToPoint(ct, pk, ek, ecMulGenerator(claimedValue as Field));
   }

package/multisig/ForwarderPrivate.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ForwarderPrivate.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (multisig/ForwarderPrivate.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -110,7 +110,7 @@ module ForwarderPrivate {
    * would defeat the private-parent guarantee. A coin public key is encrypted
    * inside the Zswap output and never appears on the public transcript.
    *
-   * @circuitInfo k=16, rows=41961
+   * @circuitInfo k=15, rows=23937
    *
    * Requirements:
    *

package/multisig/ForwarderShielded.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ForwarderShielded.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (multisig/ForwarderShielded.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -103,7 +103,7 @@ module ForwarderShielded {
    * `sendImmediateShielded` to the stored parent recipient (always the
    * `left` / coin-public-key arm today).
    *
-   * @circuitInfo k=15, rows=18573
+   * @circuitInfo k=15, rows=24446
    *
    * Requirements:
    *

package/multisig/ForwarderUnshielded.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ForwarderUnshielded.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (multisig/ForwarderUnshielded.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -105,7 +105,7 @@ module ForwarderUnshielded {
    * forwards it to `_parent` via `sendUnshielded` (always the `right` /
    * user-address arm today).
    *
-   * @circuitInfo k=9, rows=436
+   * @circuitInfo k=10, rows=565
    *
    * Requirements:
    *

package/multisig/ProposalManager.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ProposalManager.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (multisig/ProposalManager.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -12,12 +12,33 @@ pragma language_version >= 0.23.0;
  * Recipient type with a RecipientKind tag. 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 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
+ * private; the plan is not.
+ *
+ * @notice `RecipientKind` is the only thing distinguishing what a recipient's
+ * 32 bytes mean, the same value is read as a Zswap coin public key, a contract
+ * address, or a user address depending on the tag. `Contract` is accepted by
+ * both `toShieldedRecipient` and `toUnshieldedRecipient`, so the tag alone does
+ * not determine the rail; a consumer composing both treasuries could route the
+ * same proposal either way.
  */
 module ProposalManager {
   import CompactStandardLibrary;
 
   // ─── Types ──────────────────────────────────────────────────────
 
+  /**
+   * @description Proposal lifecycle states. `Inactive` is the zero value and is
+   * never stored: `_createProposal` writes `Active`, and every view asserts the
+   * proposal exists before reading, so a stored proposal can never read
+   * `Inactive`.
+   */
   export enum ProposalStatus {
     Inactive,
     Active,
@@ -176,6 +197,19 @@ module ProposalManager {
   /**
    * @description Creates a new proposal.
    *
+   * @warning The recipient is NOT validated beyond being well-typed. Two
+   * consequences the consumer must handle:
+   *
+   * - A `kind` the execution rail cannot accept (an `UnshieldedUser` recipient
+   *   on a shielded treasury, say) creates a proposal that passes here and then
+   *   reverts in `toShieldedRecipient` at execution. It stays `Active` and
+   *   unexecutable on that rail until `_cancelProposal` retires it.
+   * - A zero or otherwise unspendable `address` is accepted, and funds sent to
+   *   it on execution are unrecoverable.
+   *
+   * @notice `_nextProposalId` is incremented and then read back for the map key,
+   * making this a pinned read-modify-write.
+   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy.

package/multisig/ShieldedTreasury.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ShieldedTreasury.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (multisig/ShieldedTreasury.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -18,6 +18,19 @@ pragma language_version >= 0.23.0;
  * purposes. The canonical balance query is `getTokenBalance`, which
  * reads the actual coin value from the UTXO map.
  *
+ * @warning This treasury's HOLDINGS ARE PUBLIC. `_coins` is exported ledger
+ * state, so every coin it holds is readable off-chain in plaintext (nonce,
+ * color, value, and Merkle index) as are the cumulative `_received` and
+ * `_sent` totals. "Shielded" here refers to the token rail, not to the
+ * treasury's balance: individual transfers are shielded, but what this
+ * contract holds is not. Anyone can observe the treasury's balance per color
+ * and identify the exact UTXO backing it.
+ *
+ * Storing the coin is what buys the convenience: the contract can spend later
+ * without the caller supplying the UTXO. If public holdings are unacceptable,
+ * use `ShieldedTreasuryStateless`, which stores nothing and has the operator
+ * supply the coin at spend time.
+ *
  * Underscore-prefixed circuits (_deposit, _send) have no access control
  * enforcement. The consuming contract must gate these behind its own
  * authorization policy.
@@ -42,9 +55,13 @@ module ShieldedTreasury {
    * The coin is then merged with any existing coin of the same color,
    * or inserted as a new entry if no coin of that color exists.
    *
-   * Zero-value deposits are permitted. While currently a no-op
-   * economically, they may serve as signaling mechanisms when events
-   * are supported, or as decoy transactions for privacy.
+   * Zero-value deposits are permitted and are not always a no-op. On a color the
+   * treasury does not yet hold, a zero-value coin is inserted and occupies that
+   * color's single slot until a later deposit merges into it; if a coin of that
+   * color already exists, the zero merges into it via `mergeCoinImmediate` and
+   * the stored value is unchanged. They may serve as signaling mechanisms when
+   * events are supported. They are not useful as privacy decoys, this
+   * treasury's holdings are public (see the module header).
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -92,6 +109,12 @@ module ShieldedTreasury {
    * belongs to the treasury and must not be re-spent by the caller (doing
    * so would double-spend the recorded coin).
    *
+   * @notice The returned `ShieldedSendResult` carries the sent and change coins
+   * in plaintext, so sinking it (returning it from an entry point, writing it
+   * to ledger, passing it cross-contract) discloses them. `_coins` publishes only
+   * the retained change coin, and nothing at all when the send leaves no change,
+   * so the sent coin's plaintext is disclosed beyond anything in public state.
+   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy.
@@ -194,6 +217,13 @@ module ShieldedTreasury {
    * and cumulative sent totals for a color. Should equal
    * `getTokenBalance` if accounting is consistent.
    *
+   * @notice The subtraction is unguarded. `_send` cannot drive the sent total
+   * past the received total. Change re-insertion never increments `_received`
+   * so the invariant holds for any consumer that goes through `_deposit` and
+   * `_send`. A consumer that writes the exported `_coins` directly can break
+   * it, and this circuit then fails as an unprovable range violation rather
+   * than a named assert.
+   *
    * @param {Bytes<32>} color - The token color.
    *
    * @returns {Uint<128>} Received minus sent.

package/multisig/ShieldedTreasuryStateless.compact

@@ -1,22 +1,38 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ShieldedTreasuryStateless.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (multisig/ShieldedTreasuryStateless.compact)
 
 pragma language_version >= 0.23.0;
 
 /**
- * @module ShieldedTreasury
- * @description Manages shielded (private) token deposits, accounting,
- * and transfers for multisig governance contracts.
+ * @module ShieldedTreasuryStateless
+ * @description Manages shielded (private) token deposits and transfers for
+ * multisig governance contracts, without any ledger state.
  *
- * Coins are stored on the contract ledger in a map keyed by token color,
- * with one UTXO per color. Deposits are merged with existing coins of
- * the same color via `mergeCoinImmediate`. This simplifies coin selection
- * at spend time — the executor doesn't need to choose between multiple
- * UTXOs of the same color.
+ * This module holds NO state: no coin map, no balances, no received/sent
+ * totals. Deposits call `receiveShielded` only, and spends take the coin as a
+ * circuit parameter. The operator discovers coin indices from `ZswapOutput`
+ * events via the indexer, constructs the `QualifiedShieldedCoinInfo` off-chain,
+ * and supplies it at spend time. Coin data therefore never reaches the public
+ * ledger, and there is no on-chain balance to query — contrast
+ * `ShieldedTreasury`, which stores one merged UTXO per color and tracks
+ * cumulative totals.
  *
- * Cumulative received and sent totals are tracked per color for audit
- * purposes. The canonical balance query is `getTokenBalance`, which
- * reads the actual coin value from the UTXO map.
+ * @notice Because nothing is tracked on-chain, this module cannot detect a
+ * double spend or a coin it does not own; the protocol rejects both at
+ * application time. Sufficiency is likewise enforced by `sendShielded` rather
+ * than by an assert here.
+ *
+ * @notice "No ledger state" is not the same as "unobservable". A coin
+ * commitment is a hash of the coin's data, so `sendShielded` can link a coin
+ * receive to its later spend; `_send` declares that disclosure on the
+ * consumer's behalf. Consumers that need to make the trade-off themselves
+ * should note it is only declared here for convenience — it could be moved to
+ * the caller. Separately, see `_send`'s warning about its return value, which
+ * carries coin plaintext.
+ *
+ * Underscore-prefixed circuits (_deposit, _send) have no access control
+ * enforcement. The consuming contract must gate these behind its own
+ * authorization policy.
  */
 module ShieldedTreasuryStateless {
   import CompactStandardLibrary;
@@ -40,13 +56,24 @@ module ShieldedTreasuryStateless {
    * Executes the shielded send and returns the result untouched.
    * `sendShielded` already routes any change back to this contract as a
    * self-owned output, so `result.change` is a live, spendable coin. The
-   * implementing contract chooses what to do with it: persist it and pass
-   * it back as the `coin` for a later spend, or spend it onward to a
+   * implementing contract chooses what to do with it: retain it off-chain and
+   * pass it back as the `coin` for a later spend, or spend it onward to a
    * different recipient in the same transaction via `sendImmediateShielded`.
    * (Re-spending change is only meaningful when it goes somewhere other than
    * self — `sendShielded` already routes it to self.) No balance or
    * received/sent accounting is tracked on the ledger.
    *
+   * @warning The returned `ShieldedSendResult` holds the sent and change coins
+   * in plaintext (`nonce`, `color`, `value`). Consuming it in-circuit is safe
+   * (passing `result.change` to `sendImmediateShielded`, for instance). Returning
+   * it from your entry point, writing it to ledger, or passing it to another
+   * contract publishes those coin details, including the amount left over from
+   * the coin that was spent. Note the compiler will NOT stop you: the
+   * `disclose` calls below clear the witness taint, so such a return compiles
+   * with no `disclose` of your own and no marker at the disclosure site. If you
+   * do not need in-circuit change handling, ignore the result. The change is
+   * recoverable off-chain from the transaction's private proving state.
+   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy.
@@ -72,9 +99,11 @@ module ShieldedTreasuryStateless {
     // `_send` returns it untouched: it must not re-spend the change here and
     // then hand that same (now-nullified) coin back via `result.change`. That
     // is the double spend a node rejects on the next spend. The implementing
-    // contract decides what to do with the returned change: persist it and
-    // spend it later, or route it onward itself. The rule is only that the
-    // change must never be re-spent AND still treated as held.
+    // contract decides what to do with the returned change: retain it off-chain
+    // and spend it later, or route it onward itself. The rule is only that the
+    // change must never be re-spent AND still treated as held. "Retain" means
+    // off-chain. This module keeps no state, and writing the coin to ledger
+    // would publish its nonce, color, and value.
     return result;
   }
 }

package/multisig/Signer.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/Signer.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (multisig/Signer.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -42,6 +42,25 @@ pragma language_version >= 0.23.0;
  * call `initialize` in the contract's constructor. Contracts MUST NOT
  * call `initialize` outside of the constructor context because
  * this could corrupt the signer set and threshold configuration.
+ *
+ * `_isInitialized` records only whether `initialize` has run; it gates
+ * re-entry into `initialize` and nothing else. No other circuit consults it,
+ * so a contract that configures signers through its own flow
+ * (`_addSigner` / `_setThreshold`) is fully functional without ever calling
+ * `initialize`. Provided it gates those circuits behind its own
+ * authorization policy. Leaving them ungated lets the first caller register
+ * their own signer set and take control of the contract.
+ *
+ * @notice Not asserting initialization on the guard and view circuits is a
+ * deliberate divergence from the other modules in this library, which do.
+ * Those modules gate a zero-valued identity (an owner, a role holder); this
+ * one gates an empty collection, which rejects by absence. Safety here comes
+ * from the state rather than from a flag: an empty registry makes `isSigner`
+ * false for every input, so `assertSigner` rejects every caller, and a zero
+ * `_threshold` makes `assertThresholdMet` reject before it compares any
+ * approval count regardless of how the threshold came to be zero. Contracts
+ * needing a "configured" signal beyond that should track one at the contract
+ * layer.
  */
 module Signer<T> {
   import CompactStandardLibrary;
@@ -66,8 +85,6 @@ module Signer<T> {
    * and an initial set of signers.
    * If used, it should only be called in the contract's constructor.
    *
-   * @circuitInfo k=11, rows=1815
-   *
    * Requirements:
    *
    * - If used, can only be called once (in the constructor).
@@ -98,37 +115,43 @@ module Signer<T> {
   /**
    * @description Asserts that the given caller is an active signer.
    *
-   * @circuitInfo k=10, rows=585
-   *
    * Requirements:
    *
-   * - Contract must be initialized.
    * - `caller` must be a member of the signers registry.
    *
    * @param {T} caller - The identity to validate.
    * @returns {[]} Empty tuple.
    */
   export circuit assertSigner(caller: T): [] {
-    assertInitialized();
     assert(isSigner(caller), "Signer: not a signer");
   }
 
   /**
    * @description Asserts that the given approval count meets the threshold.
    *
+   * @notice `approvalCount` is supplied by the consuming contract and is
+   * compared against the threshold only. This circuit never consults the signer
+   * registry. Ensuring the count reflects distinct, currently-registered signers
+   * is the consuming contract's responsibility, and a contract whose approval
+   * accounting is not itself gated by `assertSigner` gets no protection here.
+   *
+   * The count is deliberately left unbounded by `_signerCount`: approvals
+   * collected before a signer was removed must still count toward a threshold
+   * the remaining signers satisfy, and bounding the count would reject those.
+   * See the stale-signer-set guidance in the module header.
+   *
    * @circuitInfo k=9, rows=54
    *
    * Requirements:
    *
-   * - Contract must be initialized.
-   * - Ledger threshold must be set (not be zero).
+   * - Ledger threshold must be set (not be zero). An unconfigured module has a
+   *   zero threshold, so this rejects before any approval count is compared.
    * - `approvalCount` must be >= threshold.
    *
    * @param {Uint<8>} approvalCount - The current number of approvals.
    * @returns {[]} Empty tuple.
    */
   export circuit assertThresholdMet(approvalCount: Uint<8>): [] {
-    assertInitialized();
     assert(_threshold != 0, "Signer: threshold not set");
     assert(approvalCount >= _threshold, "Signer: threshold not met");
   }
@@ -136,42 +159,32 @@ module Signer<T> {
   // ─── View ──────────────────────────────────────────────────────────
 
   /**
-   * @description Returns the current signer count.
+   * @description Returns the current signer count. Returns zero when no
+   * signers have been registered.
    *
    * @circuitInfo k=6, rows=26
    *
-   * Requirements:
-   *
-   * - Contract must be initialized.
-   *
    * @returns {Uint<8>} The number of active signers.
    */
   export circuit getSignerCount(): Uint<8> {
-    assertInitialized();
     return _signerCount;
   }
 
   /**
-   * @description Returns the approval threshold.
+   * @description Returns the approval threshold. Returns zero when the
+   * threshold has not been set.
    *
    * @circuitInfo k=6, rows=26
    *
-   * Requirements:
-   *
-   * - Contract must be initialized.
-   *
    * @returns {Uint<8>} The threshold.
    */
   export circuit getThreshold(): Uint<8> {
-    assertInitialized();
     return _threshold;
   }
 
   /**
    * @description Returns whether the given account is an active signer.
    *
-   * @circuitInfo k=10, rows=605
-   *
    * @param {T} account - The account to check.
    * @returns {Boolean} True if the account is an active signer.
    */
@@ -188,8 +201,6 @@ module Signer<T> {
    * The consuming contract must gate this behind its own
    * authorization policy.
    *
-   * @circuitInfo k=10, rows=598
-   *
    * Requirements:
    *
    * - `signer` must not already be an active signer.
@@ -214,8 +225,6 @@ module Signer<T> {
    * The consuming contract must gate this behind its own
    * authorization policy.
    *
-   * @circuitInfo k=10, rows=612
-   *
    * Requirements:
    *
    * - `signer` must be an active signer.
@@ -263,6 +272,14 @@ module Signer<T> {
    * @warning This is intended for use during contract construction
    * or custom setup flows where signers may not yet be registered.
    *
+   * Leaving `newThreshold` above the signer count is permitted and expected
+   * mid-setup, and is not self-enforcing: `assertThresholdMet` compares
+   * `approvalCount` against the threshold alone, so a caller supplying a matching
+   * count satisfies it even against an empty registry. Contracts must not gate
+   * operations on `assertThresholdMet` while setup is incomplete. Lower the
+   * threshold with `_setThreshold`; `_changeThreshold` cannot lower one while the
+   * signer count is zero, because that would require a zero threshold.
+   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy. Use `_changeThreshold` for
@@ -284,19 +301,6 @@ module Signer<T> {
 
   // ─── Init guards ─────────────────────────────────────────────────────────
 
-  /**
-   * @description Asserts that the contract has been initialized, throwing an error if not.
-   *
-   * Requirements:
-   *
-   * - Contract must be initialized.
-   *
-   * @return {[]} - Empty tuple.
-   */
-  circuit assertInitialized(): [] {
-    assert(_isInitialized, "Signer: contract not initialized");
-  }
-
   /**
    * @description Asserts that the contract has not been initialized, throwing an error if it has.
    *