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

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-rc.1 (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-rc.1 (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();

package/multisig/presets/ShieldedMultiSigV2.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/presets/ShieldedMultiSigV2.compact)
+// OpenZeppelin Compact Contracts v0.3.0-rc.1 (multisig/presets/ShieldedMultiSigV2.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -24,7 +24,7 @@ import CompactStandardLibrary;
 
 import "../ProposalManager" prefix Proposal_;
 import "../ShieldedTreasuryStateless" prefix Treasury_;
-import "../SignerManager"<Bytes<32>> prefix Signer_;
+import "../Signer"<Bytes<32>> prefix Signer_;
 
 // ─── Types ──────────────────────────────────────────────────────
 

package/multisig/presets/ShieldedMultiSigV3.compact

@@ -20,7 +20,7 @@ pragma language_version >= 0.23.0;
  *
  * - `mint` creates a new UTXO via `mintShieldedToken`, addressed to the
  *   contract. No external coin input; supply is produced on-chain.
- * - `burn` consumes a UTXO via `sendShielded` to `burnAddress()`. Only
+ * - `burn` consumes a UTXO via `sendShielded` to `shieldedBurnAddress()`. Only
  *   coins of this contract's token type can be burned. Change is handled
  *   automatically by the transaction layer.
  *
@@ -194,7 +194,7 @@ export circuit mint(
  * @description Burns a shielded coin of this contract's token type,
  * authorized by threshold signatures.
  *
- * Sends the specified amount of the supplied coin to `burnAddress()` via
+ * Sends the specified amount of the supplied coin to `shieldedBurnAddress()` via
  * `sendShielded`. The nullifier is submitted on-chain, permanently marking
  * the UTXO as spent.
  *

package/multisig/presets/forwarder/ForwarderPrivate.compact

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

package/multisig/presets/forwarder/ForwarderShielded.compact

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

package/multisig/presets/forwarder/ForwarderUnshielded.compact

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openzeppelin/compact-contracts",
-  "version": "0.3.0-alpha.1",
+  "version": "0.3.0-rc.1",
   "description": "OpenZeppelin Compact contract library",
   "keywords": [
     "openzeppelin",
@@ -60,9 +60,9 @@
     "@midnight-ntwrk/midnight-js-protocol": "4.1.1",
     "@midnight-ntwrk/midnight-js-types": "4.1.1",
     "@midnight-ntwrk/testkit-js": "4.1.1",
-    "@openzeppelin/compact-simulator": "^0.2.0",
+    "@openzeppelin/compact-simulator": "^0.3.1",
     "@tsconfig/node24": "^24.0.4",
-    "@types/node": "26.1.1",
+    "@types/node": "26.1.2",
     "@vitest/coverage-v8": "^4.1.10",
     "fast-check": "^4.9.0",
     "ts-node": "^10.9.2",

package/security/Allowlist.compact

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

package/security/Blocklist.compact

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

package/security/Initializable.compact

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

package/security/Pausable.compact

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