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

package/multisig/ShieldedTreasury.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/ShieldedTreasury.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/ShieldedTreasury.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -82,13 +82,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 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).
+   * @warning Every deposit of a color replaces the coin that `_send` reads for
+   * that color, so a deposit that lands first invalidates every `_send` of the
+   * same color still waiting to be applied. A consumer that exposes `_deposit`
+   * without access control lets any depositor delay authorized sends for as
+   * long as they keep depositing; the sends must then be re-proven. No funds are
+   * lost. A zero-value coin is rejected, so each deposit costs at least one unit
+   * of the token plus the transaction fee.
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -96,6 +96,7 @@ module ShieldedTreasury {
    *
    * Requirements:
    *
+   * - The coin's value must be non-zero.
    * - Deposit must not cause received total overflow.
    *
    * @param {ShieldedCoinInfo} coin - The incoming shielded coin descriptor.
@@ -103,6 +104,8 @@ module ShieldedTreasury {
    * @returns {[]} Empty tuple.
    */
   export circuit _deposit(coin: ShieldedCoinInfo): [] {
+    assert(coin.value != 0, "ShieldedTreasury: zero value");
+
     const currentReceived = getReceivedTotal(coin.color);
     assert(currentReceived <= Utils_UINT128_MAX() - coin.value, "ShieldedTreasury: overflow");
 
@@ -142,12 +145,16 @@ module ShieldedTreasury {
    * 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.
    *
+   * @dev A self-addressed coin is auto-received by `sendShielded` but never recorded
+   * in _coins so it would be stranded. Therefore, this circuit rejects sends to self.
+   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy.
    *
    * Requirements:
    *
+   * - `recipient` must not be this contract's own address.
    * - A coin of the given `color` must exist in the treasury.
    * - The coin's value must be >= `amount`.
    * - Send must not cause sent total overflow.
@@ -163,6 +170,11 @@ module ShieldedTreasury {
     color: Bytes<32>,
     amount: Uint<128>
   ): ShieldedSendResult {
+    // `kernel.self()` stays outside the `||`: the compiler treats a ledger
+    // read behind a witness-conditioned branch as an undeclared disclosure
+    const self = kernel.self();
+    assert(recipient.is_left || recipient.right != self,
+           "ShieldedTreasury: self-send");
     assert(_coins.member(disclose(color)), "ShieldedTreasury: no balance");
 
     const coin = _coins.lookup(disclose(color));

package/multisig/ShieldedTreasuryStateless.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/ShieldedTreasuryStateless.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/ShieldedTreasuryStateless.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -22,10 +22,16 @@ pragma language_version >= 0.26.0;
  * 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
+ * @notice "No ledger state" is not the same as "unobservable". A coin's
+ * nullifier is a hash of the coin and this contract's address, and
+ * `sendShielded` derives the nonces of the sent coin and of the change from a
+ * public hash of the spent coin's nonce. Whoever knows a deposited coin can
+ * therefore find the spend that consumes it, recover the amount sent (on a
+ * partial spend the change commitment has the value as its only unknown),
+ * test candidate recipients against the sent coin's commitment, and repeat
+ * from the change coin for every later spend descending from it. `_send`
+ * declares the spent coin's 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.

package/multisig/Signer.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/Signer.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/Signer.compact)
 
 pragma language_version >= 0.26.0;
 

package/multisig/UnshieldedTreasury.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/UnshieldedTreasury.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/UnshieldedTreasury.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -61,6 +61,14 @@ module UnshieldedTreasury {
    * operation creates a zero-valued `_balances` entry, which
    * `getTokenBalance` reports the same as absence.
    *
+   * @warning Every non-zero deposit of a color rewrites the `_balances` entry
+   * that `_send` reads for that color, so a deposit that lands first
+   * invalidates every `_send` of the same color still waiting to be applied.
+   * A consumer that exposes `_deposit` without access control lets any
+   * depositor delay authorized sends for as long as they keep depositing; the
+   * sends must then be re-proven. No funds are lost. A zero-value deposit
+   * rewrites the entry with the same value and does not have this effect.
+   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy.
@@ -92,17 +100,16 @@ module UnshieldedTreasury {
   /**
    * @description Sends unshielded tokens from the treasury.
    *
-   * @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 Recipients other than this contract 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.
+   * @dev A self-addressed send is auto-received by `sendUnshielded` but
+   * still debited from `_balances`, so the funds would be stranded.
+   * Therefore, this circuit rejects sends to self.
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -110,6 +117,7 @@ module UnshieldedTreasury {
    *
    * Requirements:
    *
+   * - `recipient` must not be this contract's own address.
    * - The amount must be non-zero. The ledger rejects zero-value outputs.
    * - The treasury must hold sufficient balance for the given token color.
    *
@@ -124,6 +132,11 @@ module UnshieldedTreasury {
     color: Bytes<32>,
     amount: Uint<128>
   ): [] {
+    // `kernel.self()` stays outside the `||`: the compiler treats a ledger
+    // read behind a witness-conditioned branch as an undeclared disclosure
+    const self = kernel.self();
+    assert(!recipient.is_left || recipient.left != self,
+           "UnshieldedTreasury: self-send");
     assert(amount != 0, "UnshieldedTreasury: zero amount");
 
     const bal = getTokenBalance(color);

package/multisig/examples/ForwarderPrivateExample.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/examples/ForwarderPrivateExample.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/examples/ForwarderPrivateExample.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -54,7 +54,8 @@ export circuit deposit(coin: ShieldedCoinInfo): [] {
  * @description Spends a previously-deposited shielded coin to the parent,
  * a coin public key. The caller proves knowledge of `(parent, opSecret)`
  * matching the stored commitment; the coin is sent as a shielded note, so the
- * parent stays hidden on-chain. If the input coin's value exceeds `value`,
+ * parent stays hidden from anyone who holds no deposited coin (see the
+ * `ForwarderPrivate` module notice). If the input coin's value exceeds `value`,
  * change is re-emitted back to the contract for future drains.
  *
  * The parent is a `ZswapCoinPublicKey`, never a `ContractAddress`: a shielded

package/multisig/examples/ForwarderShieldedExample.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/examples/ForwarderShieldedExample.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/examples/ForwarderShieldedExample.compact)
 
 pragma language_version >= 0.26.0;
 

package/multisig/examples/ForwarderUnshieldedExample.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/examples/ForwarderUnshieldedExample.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/examples/ForwarderUnshieldedExample.compact)
 
 pragma language_version >= 0.26.0;
 

package/multisig/examples/NativeShieldedTokenIssuerExample.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/examples/NativeShieldedTokenIssuerExample.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/examples/NativeShieldedTokenIssuerExample.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -19,7 +19,7 @@ pragma language_version >= 0.26.0;
 
 import CompactStandardLibrary;
 
-import "../presets/NativeShieldedTokenIssuer" prefix NativeShieldedTokenIssuer_;
+import "../presets/NativeShieldedTokenIssuer"<2> prefix NativeShieldedTokenIssuer_;
 
 export { ZswapCoinPublicKey, ContractAddress, Either, Maybe };
 export { ShieldedCoinInfo, QualifiedShieldedCoinInfo };
@@ -39,7 +39,7 @@ import {
   _symbol,
   _decimals,
   _isInitialized,
-} from "../presets/NativeShieldedTokenIssuer";
+} from "../presets/NativeShieldedTokenIssuer"<2>;
 export {
   _counter,
   _domainSeparator,
@@ -79,7 +79,7 @@ constructor(
   decimals_: Uint<8>,
   signerCommitments: Vector<3, Bytes<32>>,
 ) {
-  NativeShieldedTokenIssuer_initialize(
+  NativeShieldedTokenIssuer_initialize<3>(
     instanceSalt,
     tokenDomain,
     name_,

package/multisig/examples/ShieldedMultiSigV2Example.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/examples/ShieldedMultiSigV2Example.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/examples/ShieldedMultiSigV2Example.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -15,28 +15,26 @@ pragma language_version >= 0.26.0;
 
 import CompactStandardLibrary;
 
-import "../presets/ShieldedMultiSigV2" prefix ShieldedMultiSigV2_;
+import "../presets/ShieldedMultiSigV2"<2> prefix ShieldedMultiSigV2_;
 
 export { ShieldedCoinInfo, QualifiedShieldedCoinInfo, ShieldedSendResult };
 
 // Surface the preset's domain separator unprefixed so `ledger()` readers see
 // the key name the preset published.
-import { _domainSeparator } from "../presets/ShieldedMultiSigV2";
+import { _domainSeparator } from "../presets/ShieldedMultiSigV2"<2>;
 export { _domainSeparator };
 
 /**
- * @description Deploys the wallet with 3 signer commitments and a threshold.
+ * @description Deploys the wallet with 3 signer commitments.
  *
  * @param {Bytes<32>} instanceSalt - Random salt for commitment derivation.
  * @param {Vector<3, Bytes<32>>} signerCommitments - Hashed signer identities.
- * @param {Uint<8>} thresh - Approvals required. Must be 2.
  */
 constructor(
   instanceSalt: Bytes<32>,
-  signerCommitments: Vector<3, Bytes<32>>,
-  thresh: Uint<8>,
+  signerCommitments: Vector<3, Bytes<32>>
 ) {
-  ShieldedMultiSigV2_initialize(instanceSalt, signerCommitments, thresh);
+  ShieldedMultiSigV2_initialize<3>(instanceSalt, signerCommitments);
 }
 
 export circuit deposit(coin: ShieldedCoinInfo): [] {
@@ -44,7 +42,7 @@ export circuit deposit(coin: ShieldedCoinInfo): [] {
 }
 
 export circuit execute(
-  to: ShieldedMultiSigV2_Proposal_Recipient,
+  to: ShieldedMultiSigV2_Recipient,
   amount: Uint<128>,
   coin: QualifiedShieldedCoinInfo,
   pubkeys: Vector<2, Secp256k1Point>,