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

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-alpha.2 (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-alpha.2 (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-alpha.2 (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-alpha.2 (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-alpha.2 (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-alpha.2 (crypto/ElGamal.compact)
 
 pragma language_version >= 0.23.0;
 

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-alpha.2 (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-alpha.2 (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-alpha.2 (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-alpha.2 (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-alpha.2 (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-alpha.2 (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-alpha.2 (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.
    *

package/multisig/UnshieldedTreasury.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/UnshieldedTreasury.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (multisig/UnshieldedTreasury.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -8,10 +8,24 @@ pragma language_version >= 0.23.0;
  * @description Manages unshielded (transparent) token deposits and
  * transfers for multisig governance contracts.
  *
- * Balances are tracked per token color in a single map. Protocol-level
- * balance comparison circuits (`unshieldedBalanceLte`,
- * `unshieldedBalanceGte`) are used for overflow and sufficiency checks,
- * avoiding the exact-match problem of `unshieldedBalance`.
+ * Balances are tracked per token color in `_balances`, this module's own
+ * accounting and the authority for its overflow and sufficiency guards. The
+ * protocol balance remains authoritative for what the contract actually holds,
+ * and the ledger independently enforces conservation — a contract cannot send
+ * funds it does not have.
+ *
+ * @notice The guards deliberately do NOT consult `unshieldedBalance` or its
+ * comparison circuits. That balance is fixed to the value provided at the start
+ * of execution, so it cannot observe a credit or debit made earlier in the same
+ * transaction: guarding on it rejects a legitimate receive-then-spend and misses
+ * an intra-transaction overspend. Guarding on `_balances` (the same value the
+ * arithmetic mutates) is correct in both cases, and keeps the named asserts
+ * reachable for the conditions they describe.
+ *
+ * @notice Consumers must route every unshielded credit and debit through
+ * `_deposit` / `_send`. A flow that calls `receiveUnshielded` or
+ * `sendUnshielded` directly leaves `_balances` out of step with the protocol
+ * balance, and `getTokenBalance` will misreport.
  *
  * Underscore-prefixed circuits (_deposit, _send) have no access control
  * enforcement. The consuming contract must gate these behind its own
@@ -35,7 +49,9 @@ module UnshieldedTreasury {
    *
    * Zero-value deposits are permitted. While currently a no-op
    * economically, they may serve as signaling mechanisms when events
-   * are supported.
+   * are supported. On a color the treasury has not held, a zero-value
+   * operation creates a zero-valued `_balances` entry, which
+   * `getTokenBalance` reports the same as absence.
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -51,21 +67,35 @@ module UnshieldedTreasury {
    * @returns {[]} Empty tuple.
    */
   export circuit _deposit(color: Bytes<32>, amount: Uint<128>): [] {
-    assert(
-      unshieldedBalanceLte(disclose(color), Utils_UINT128_MAX() - disclose(amount)),
-      "UnshieldedTreasury: overflow"
-    );
+    // `Utils_UINT128_MAX() - amount` stays in-circuit. Passing it to a protocol
+    // balance comparison would hand that built-in an operand near 2^128, which
+    // fails at runtime with "failed to decode for built-in type u64" despite the
+    // circuit's declared `Uint<128>` parameter.
+    const bal = getTokenBalance(color);
+    assert(bal <= Utils_UINT128_MAX() - amount, "UnshieldedTreasury: overflow");
 
     receiveUnshielded(disclose(color), disclose(amount));
 
-    const bal = getTokenBalance(color);
     _balances.insert(disclose(color), disclose(bal + amount as Uint<128>));
   }
 
   // ─── Send ───────────────────────────────────────────────────────
 
   /**
-   * @description Sends unshielded tokens from the treasury.
+   * @description Sends unshielded tokens from the treasury. Zero-amount sends
+   * are permitted and are value-preserving no-ops.
+   *
+   * @warning Recipients are not validated. An unspendable recipient (such as a
+   * zero address) is accepted and permanently removes the funds from the
+   * contract. This is not a sanctioned burn — no unshielded equivalent of
+   * `shieldedBurnAddress` is exposed to contracts — so treat recipient
+   * validation as the consuming contract's responsibility.
+   *
+   * @warning Sending to this contract's own address zeroes the tracked balance
+   * while the funds stay held and spendable at the protocol level, after which
+   * `_send` will refuse to touch them. Recovery is only possible outside this
+   * module: a consumer may reconcile the exported `_balances`, or spend the
+   * funds through its own `sendUnshielded` call.
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -86,12 +116,9 @@ module UnshieldedTreasury {
     color: Bytes<32>,
     amount: Uint<128>
   ): [] {
-    assert(
-      unshieldedBalanceGte(disclose(color), disclose(amount)),
-      "UnshieldedTreasury: insufficient balance"
-    );
-
     const bal = getTokenBalance(color);
+    assert(bal >= amount, "UnshieldedTreasury: insufficient balance");
+
     _balances.insert(disclose(color), disclose(bal - amount as Uint<128>));
     sendUnshielded(disclose(color), disclose(amount), disclose(recipient));
   }

package/multisig/presets/ShieldedMultiSig.compact

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/presets/ShieldedMultiSig.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (multisig/presets/ShieldedMultiSig.compact)
 
 pragma language_version >= 0.23.0;
 
 /**
  * @module ShieldedMultiSig
- * @description A shielded multisig preset composing `SignerManager`,
+ * @description A shielded multisig preset composing `Signer`,
  * `ProposalManager`, and `ShieldedTreasury`. Signers approve proposals that
  * transfer shielded tokens out of the treasury once the configured threshold
  * is met.
@@ -29,7 +29,7 @@ import CompactStandardLibrary;
 
 import "../ProposalManager" prefix Proposal_;
 import "../ShieldedTreasury" prefix Treasury_;
-import "../SignerManager"<Either<ZswapCoinPublicKey, ContractAddress>> prefix Signer_;
+import "../Signer"<Either<ZswapCoinPublicKey, ContractAddress>> prefix Signer_;
 
 // ─── State ───────────────────────────────────────────────────────────────
 
@@ -212,7 +212,7 @@ export circuit getSentTotal(color: Bytes<32>): Uint<128> {
   return Treasury_getSentTotal(color);
 }
 
-// ISignerManager
+// ISigner
 
 export circuit getSignerCount(): Uint<8> {
   return Signer_getSignerCount();