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

package/multisig/Signer.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (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 (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 (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 ───────────────────────────────────────────────────────────────
 
@@ -187,17 +187,12 @@ export circuit getProposal(id: Uint<64>): Proposal_Proposal {
   return Proposal_getProposal(id);
 }
 
-export circuit getProposalRecipient(id: Uint<64>): Proposal_Recipient {
-  return Proposal_getProposalRecipient(id);
-}
-
-export circuit getProposalAmount(id: Uint<64>): Uint<128> {
-  return Proposal_getProposalAmount(id);
-}
-
-export circuit getProposalColor(id: Uint<64>): Bytes<32> {
-  return Proposal_getProposalColor(id);
-}
+// NOTE: the per-field proposal getters (getProposalRecipient / getProposalAmount
+// / getProposalColor) and getReceivedMinusSent were dropped to bring the deploy
+// transaction under the block-weight limit (the full 19-circuit deploy is
+// rejected with "Transaction would exhaust the block limits"). They are all
+// redundant: read the proposal fields via `getProposal(id).to / .amount / .color`,
+// and the net balance via `getReceivedTotal(color) - getSentTotal(color)`.
 
 export circuit getProposalStatus(id: Uint<64>): Proposal_ProposalStatus {
   return Proposal_getProposalStatus(id);
@@ -217,11 +212,7 @@ export circuit getSentTotal(color: Bytes<32>): Uint<128> {
   return Treasury_getSentTotal(color);
 }
 
-export circuit getReceivedMinusSent(color: Bytes<32>): Uint<128> {
-  return Treasury_getReceivedMinusSent(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 (multisig/presets/ShieldedMultiSigV2.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (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 (multisig/presets/forwarder/ForwarderPrivate.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (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 (multisig/presets/forwarder/ForwarderShielded.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (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 (multisig/presets/forwarder/ForwarderUnshielded.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (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",
+  "version": "0.3.0-alpha.2",
   "description": "OpenZeppelin Compact contract library",
   "keywords": [
     "openzeppelin",
@@ -21,23 +21,24 @@
   "homepage": "https://docs.openzeppelin.com/contracts-compact/",
   "type": "module",
   "imports": {
-    "#test-utils/address.js": "./test-utils/address.js"
+    "#test-utils/*": "./test-utils/*"
   },
   "scripts": {
-    "compact": "compact-compiler --exclude '*/archive/*'",
-    "compact:access": "compact-compiler --dir access",
-    "compact:archive": "compact-compiler --dir archive",
-    "compact:crypto": "compact-compiler --dir crypto",
-    "compact:multisig": "compact-compiler --dir multisig",
-    "compact:security": "compact-compiler --dir security",
-    "compact:token": "compact-compiler --dir token",
-    "compact:utils": "compact-compiler --dir utils",
+    "compile": "compact-compiler --exclude '*/archive/*'",
+    "compile:access": "compact-compiler --dir access",
+    "compile:archive": "compact-compiler --dir archive",
+    "compile:crypto": "compact-compiler --dir crypto",
+    "compile:multisig": "compact-compiler --dir multisig",
+    "compile:security": "compact-compiler --dir security",
+    "compile:token": "compact-compiler --dir token",
+    "compile:utils": "compact-compiler --dir utils",
+    "compile:integration": "SKIP_ZK=true compact-compiler --src test/integration/_mocks",
     "build": "compact-builder --hierarchical --out dist --clean-dist --exclude '*/archive/*' --exclude 'Mock*' --exclude '*.mock.compact' --copy package.json --copy ../README.md && find dist -type d -empty -delete",
-    "test": "SKIP_ZK=true yarn run compact && vitest run",
-    "test:coverage": "SKIP_ZK=true yarn run compact && vitest run --coverage",
-    "test:live": "yarn run compact && MIDNIGHT_BACKEND=live vitest run --config vitest.live.config.ts",
-    "compact:integration": "SKIP_ZK=true compact compile test/integration/_mocks/SharedInitCollision.compact artifacts/SharedInitCollision && SKIP_ZK=true compact compile test/integration/_mocks/ComposedTokens.compact artifacts/ComposedTokens",
-    "test:integration": "yarn run compact:integration && vitest run --config vitest.integration.config.ts",
+    "test": "vitest run --project unit",
+    "test:coverage": "vitest run --project unit --coverage",
+    "test:integration": "vitest run --project integration",
+    "test:harness": "vitest run --project harness",
+    "test:harness:live": "MIDNIGHT_BACKEND=live vitest run --project harness-live",
     "types": "tsc -p tsconfig.json --noEmit",
     "clean": "git clean -fXd"
   },
@@ -48,13 +49,24 @@
     "@openzeppelin/compact-cli": "^0.0.2"
   },
   "devDependencies": {
-    "@openzeppelin/compact-simulator": "^0.2.0",
+    "@midnight-ntwrk/compact-js": "2.5.1",
+    "@midnight-ntwrk/compact-runtime": "0.16.0",
+    "@midnight-ntwrk/ledger-v8": "8.1.0",
+    "@midnight-ntwrk/midnight-js-contracts": "4.1.1",
+    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "4.1.1",
+    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "4.1.1",
+    "@midnight-ntwrk/midnight-js-network-id": "4.1.1",
+    "@midnight-ntwrk/midnight-js-node-zk-config-provider": "4.1.1",
+    "@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.3.1",
     "@tsconfig/node24": "^24.0.4",
-    "@types/node": "25.9.3",
-    "@vitest/coverage-v8": "^4.1.9",
-    "fast-check": "^4.8.0",
+    "@types/node": "26.1.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    "fast-check": "^4.9.0",
     "ts-node": "^10.9.2",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   }
 }

package/security/Allowlist.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (security/Allowlist.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (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 (security/Blocklist.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (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 (security/Initializable.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (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 (security/Pausable.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (security/Pausable.compact)
 
 pragma language_version >= 0.23.0;