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

package/access/AccessControl.compact

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

package/access/Ownable.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (access/Ownable.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (access/Ownable.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -117,8 +117,6 @@ module Ownable {
    * @description Initializes the contract by setting the `initialOwner`.
    * This must be called in the contract's constructor.
    *
-   * @constraints k=10, rows=626
-   *
    * Requirements:
    *
    * - Contract is not already initialized.

package/access/ShieldedAccessControl.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (access/ShieldedAccessControl.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (access/ShieldedAccessControl.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -108,8 +108,8 @@ pragma language_version >= 0.26.0;
  *   depends on the number of plausible `(role, accountId)` pairings. Since role identifiers
  *   are public, the anonymity set is effectively the number of plausible account IDs per role.
  * - Outside observers will know when roles are granted and revoked.
- * - Outside observers can infer the total number of role grants made across all roles—not per-role counts,
- *   but the cumulative total.
+ * - Outside observers can infer the total number of distinct `(role, accountId)` pairings granted
+ *   across all roles, not per-role counts.
  * - Outside observers can link calls made by the same role instance across time.
  * - Users can be retroactively deanonymized if their secret key is exposed.
  * - Outside observers will NOT be able to identify the holder of any role
@@ -133,29 +133,20 @@ pragma language_version >= 0.26.0;
  * - It's strongly recommended to use cryptographically secure random values for the `_instanceSalt`.
  *   Failure to do so may weaken privacy guarantees.
  * - The `_instanceSalt` is immutable and used to differentiate deployments.
- * - The `_operatorRoles` Merkle tree has a fixed capacity of 2^20 leaf slots.
- *   Deployers should monitor slot consumption off-chain. A careless admin can exhaust
- *   capacity through repeated grants of the same active (role, accountId) pairing.
- *   Duplicate grants are benign from a security perspective. They produce identical
- *   commitments and a single nullifier invalidates all copies; however, they waste tree capacity.
- *   Implementing contracts are responsible for mitigating tree exhaustion risk.
+ * - The `_operatorRoles` Merkle tree has a fixed capacity of 2^20 leaf slots. Each distinct
+ *   `(role, accountId)` pairing consumes one slot; re-granting an active pairing is a no-op.
  * - A single `secretKey` compromise exposes all roles held by that user within the contract
  *   instance, since all roles share the same `accountId`. Users requiring compartmentalization
  *   between roles should use separate keys per role and accept the additional key management overhead.
  *   In the event of key compromise, the user should coordinate with admins to revoke all roles
  *   under the compromised `accountId` and re-grant under a new identity.
- * - Admins can revoke `(role, accountId)` pairings that were never granted, since on-chain
- *   non-membership proofs are not available for the Merkle tree. This permanently burns the
- *   nullifier for that pairing, blocking any future grant. Admin trust is a fundamental
- *   assumption of this system. Off-chain validation should confirm that a pairing was actually
- *   granted before submitting a revocation transaction.
- * - `renounceRole` allows burning nullifiers for roles the caller does not currently hold,
- *   provided they possess the correct `secretKey`. This requires knowledge of the secret key,
- *   at which point the `accountId` should be considered fully compromised regardless.
+ * - A `(role, accountId)` pairing can only be revoked after it was granted, so the nullifier
+ *   set holds at most one entry per granted pairing.
  * - The Merkle tree capacity of 2^20 leaf slots is a permanent, irrecoverable resource.
  *   There is no mechanism to reclaim slots after revocation, no upgrade path, and no emergency
  *   recovery. Once exhausted, the contract is permanently unable to grant new roles. Deployers
- *   must monitor slot consumption off-chain and plan capacity accordingly.
+ *   must monitor slot consumption off-chain and plan capacity accordingly. The exported tree
+ *   reports occupancy via `firstFree()` (TypeScript) and `isFull()` (circuit).
  *
  * @notice Using the SHA256 hashing function comes at a significant performance cost. In the future, we
  * plan on migrating to a ZK-friendly hashing function when an implementation is available.
@@ -213,6 +204,14 @@ module ShieldedAccessControl {
    */
   export ledger _roleCommitmentNullifiers: Set<RoleNullifier>;
 
+  /**
+   * @description Nullifiers of every pairing ever granted. Makes a repeated grant a no-op so
+   * one pairing can never consume more than one `_operatorRoles` slot, and gates revocation
+   * so a nullifier can only exist for a granted pairing.
+   * @type {Set<RoleNullifier>} _grantedRoleNullifiers
+   */
+  export ledger _grantedRoleNullifiers: Set<RoleNullifier>;
+
   /**
    * @sealed @ledger _instanceSalt
    * @description A per-instance value provided at initialization used to namespace
@@ -395,12 +394,11 @@ module ShieldedAccessControl {
 
   /**
    * @description Grants `role` to `accountId` by inserting a role commitment unique to the
-   * `(role, accountId)` pairing into the `_operatorRoles` Merkle tree. Duplicate role commitments can be issued
-   * so long as they remain unrevoked. This does not yield any additional authority and simply wastes
-   * limited Merkle tree storage slots. Once revoked, a role cannot be re-granted to the same `accountId`. A new
+   * `(role, accountId)` pairing into the `_operatorRoles` Merkle tree. Granting an already active
+   * pairing is a no-op. Once revoked, a role cannot be re-granted to the same `accountId`. A new
    * `accountId` must be generated to be re-authorized for a revoked `role`.
    *
-   * @constraints k=15, rows=28995
+   * @constraints k=15, rows=29071
    *
    * Requirements:
    *
@@ -429,9 +427,8 @@ module ShieldedAccessControl {
 
   /**
    * @description Grants `role` to `accountId` by inserting a role commitment unique to the
-   * `(role, accountId)` pairing into the `_operatorRoles` Merkle tree. Duplicate role commitments can be issued
-   * so long as they remain unrevoked. This does not yield any additional authority and simply wastes
-   * limited Merkle tree storage slots. Once revoked, a role cannot be re-granted to the same `accountId`. A new
+   * `(role, accountId)` pairing into the `_operatorRoles` Merkle tree. Granting an already active
+   * pairing is a no-op. Once revoked, a role cannot be re-granted to the same `accountId`. A new
    * `accountId` must be generated to be re-authorized for a revoked `role`.
    *
    * Internal circuit without access restriction.
@@ -439,12 +436,10 @@ module ShieldedAccessControl {
    * @warning Exposing this circuit directly in an implementing contract would allow anyone to grant
    * roles without authorization. It must be wrapped with appropriate access control.
    *
-   * @warning The `_operatorRoles` Merkle tree has a fixed capacity of 2^20 leaf slots.
-   * Deployers should monitor slot consumption off-chain. Duplicate grants waste tree capacity
-   * but are otherwise benign. A single nullifier invalidates all duplicate commitments.
-   * Implementing contracts are responsible for mitigating tree exhaustion risk.
+   * @warning The `_operatorRoles` Merkle tree has a fixed capacity of 2^20 leaf slots, one per
+   * distinct pairing. Deployers should monitor slot consumption off-chain.
    *
-   * @constraints k=14, rows=12250
+   * @constraints k=14, rows=12326
    *
    * Requirements:
    *
@@ -474,15 +469,17 @@ module ShieldedAccessControl {
    * @notice Roles are often managed via {grantRole} and {revokeRole}: this circuit's
    * purpose is to provide a mechanism for accounts to lose their privileges
    * if they are compromised (such as when a trusted device is misplaced).
+   * Consumers with no need for self-revocation should not export this circuit.
    *
    * @warning Outside observers may be able to use timing and pattern analysis to weaken pseudonymity
    * guarantees if renounceRole is used in tandem with other on-chain actions.
    *
-   * @constraints k=14, rows=14440
+   * @constraints k=14, rows=14442
    *
    * Requirements:
    *
    * - The caller must provide a valid `accountId` for the role.
+   * - The `(role, accountId)` pairing must have been granted.
    * - The `(role, accountId)` pairing must not be already revoked.
    * - Contract is initialized.
    *
@@ -508,15 +505,15 @@ module ShieldedAccessControl {
   /**
    * @description Permanently revokes `role` from `accountId` by inserting a role nullifier into the
    * `_roleCommitmentNullifiers` set. Once revoked, a new `accountId` must be generated to be re-authorized for
-   * `role`. At this time, proofs of non-membership on values in the Merkle tree LDT are not possible
-   * so a `(role, accountId)` pairing that does not exist can still be revoked.
+   * `role`.
    *
-   * @constraints k=15, rows=27005
+   * @constraints k=15, rows=27007
    *
    * Requirements:
    *
    * - caller must prove they're an admin for `role`.
    * - caller must not provide valid Merkle tree path for a different `(role, accountId)` pairing.
+   * - The `(role, accountId)` pairing must have been granted.
    * - The `(role, accountId)` pairing must not be already revoked.
    * - Contract is initialized.
    *
@@ -541,18 +538,18 @@ module ShieldedAccessControl {
   /**
    * @description Permanently revokes `role` from `accountId` by inserting a role nullifier into the
    * `_roleCommitmentNullifiers` set. Once revoked, a new `accountId` must be generated to be re-authorized for
-   * `role`. At this time, proofs of non-membership on values in the Merkle tree LDT are not possible
-   * so a `(role, accountId)` pairing that does not exist can still be revoked.
+   * `role`.
    *
    * Internal circuit without access restriction.
    *
    * @warning Exposing this circuit directly in an implementing contract would allow anyone to revoke
    * roles without authorization. It must be wrapped with appropriate access control.
    *
-   * @constraints k=14, rows=10260
+   * @constraints k=14, rows=10262
    *
    * Requirements:
    *
+   * - The `(role, accountId)` pairing must have been granted.
    * - The `(role, accountId)` pairing must not be already revoked.
    * - Contract is initialized.
    *
@@ -573,13 +570,14 @@ module ShieldedAccessControl {
   /**
    * @description Core business logic for the grant/revoke role circuits. Asserts that the
    * `(role, accountId)` pairing has not already been revoked. On success, dispatches on
-   * `updateType`: a `Grant` inserts the role commitment into `_operatorRoles`, and
-   * a `Revoke` inserts the nullifier into `_roleCommitmentNullifiers`.
+   * `updateType`: a `Grant` inserts the role commitment into `_operatorRoles` unless the
+   * nullifier is already in `_grantedRoleNullifiers`, and a `Revoke` asserts the nullifier
+   * is in `_grantedRoleNullifiers` before inserting it into `_roleCommitmentNullifiers`.
    *
    * Disclosures:
    *
    * - A nullifier for the respective role commitment.
-   * - A role commitment (on Grant only).
+   * - A role commitment (on first Grant only).
    *
    * @notice The nullifier is disclosed via `_roleCommitmentNullifiers.member` on every call,
    * regardless of the update type. Since `Set.member` publicly reveals its argument, the
@@ -602,9 +600,14 @@ module ShieldedAccessControl {
     const isRevoked = _roleCommitmentNullifiers.member(disclose(roleNullifier));
     assert(!isRevoked, "ShieldedAccessControl: role is already revoked");
 
+    const isGranted = _grantedRoleNullifiers.member(disclose(roleNullifier));
     if (updateType == UpdateType.Grant) {
-      _operatorRoles.insert(disclose(roleCommitment));
+      if (!isGranted) {
+        _grantedRoleNullifiers.insert(disclose(roleNullifier));
+        _operatorRoles.insert(disclose(roleCommitment));
+      }
     } else {
+      assert(isGranted, "ShieldedAccessControl: role was never granted");
       _roleCommitmentNullifiers.insert(disclose(roleNullifier));
     }
   }

package/access/ZOwnablePK.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (access/ZOwnablePK.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (access/ZOwnablePK.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -106,8 +106,6 @@ module ZOwnablePK {
    * @warning The `ownerId` must be calculated prior to contract deployment using the SHA256 hashing algorithm.
    * Using any other algorithm will result in a permanent loss of contract access.
    *
-   * @constraints k=13, rows=6765
-   *
    * Requirements:
    *
    * - Contract is not initialized.

package/crypto/EcdhMask.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (crypto/EcdhMask.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (crypto/EcdhMask.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -49,6 +49,8 @@ pragma language_version >= 0.26.0;
  * an out-of-range scalar: `g^e = identity` captures both `e = 0` and any
  * `e ≡ 0 (mod ℓ)`. (Guarding `e != 0` directly would instead lean on the runtime
  * faulting `ecMul` for scalars `≥ ℓ`; the point guard removes that dependency.)
+ * `decrypt` guards the same point, refusing an identity ephemeral rather than
+ * unmasking against that public constant.
  * These are the only weak inputs (for a subgroup key, `S = identity` iff the
  * ephemeral point is the identity).
  *
@@ -162,6 +164,10 @@ module EcdhMask {
    * @description Recovers the value from a ciphertext using the recipient's
    * secret scalar. Pure and off-chain (no proof needed to read a received value).
    *
+   * Requirements:
+   *
+   * - `ciphertext.ephemeralPk` is not the identity point.
+   *
    * @param ciphertext - The ciphertext to decrypt.
    * @param ekScalar - The recipient's secret scalar (`crypto/ElGamal`'s
    *                   `secretToScalar(EK)`).
@@ -170,6 +176,10 @@ module EcdhMask {
    *         which is `< 2^128`).
    */
   export pure circuit decrypt(ciphertext: Ciphertext, ekScalar: JubjubScalar, domain: Bytes<32>): Field {
+    // `encrypt` never emits an identity ephemeral; one here is a malformed
+    // ciphertext whose mask is a public constant, so refuse rather than decrypt.
+    assert(ciphertext.ephemeralPk != ecMulGenerator(0 as JubjubScalar),
+           "EcdhMask: identity ephemeral");
     const sShared = ecMul(ciphertext.ephemeralPk, ekScalar);
     const mask = kdf(sShared, domain);
     return ciphertext.ct - mask;

package/crypto/Ecdsa.compact

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

package/crypto/Eip712.compact

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

package/crypto/ElGamal.compact

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

package/multisig/ForwarderPrivate.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (multisig/ForwarderPrivate.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/ForwarderPrivate.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -10,15 +10,25 @@ pragma language_version >= 0.26.0;
  * Deposits accumulate at the contract (no atomic forward); the operator
  * drains coins by presenting the `(parent, opSecret)` preimage at drain
  * time. The drained coin is sent as a shielded note to the parent key, so
- * the parent stays hidden on-chain. The parent is deliberately a coin public
- * key and not a contract address: a shielded send to a contract publishes
- * that contract's address in cleartext, which would defeat the guarantee.
+ * the parent never appears on the ledger. The parent is deliberately a coin
+ * public key and not a contract address: a shielded send to a contract
+ * publishes that contract's address in cleartext, which would defeat the
+ * guarantee.
+ *
+ * @notice The commitment hides the parent from the public, not from a
+ * depositor. A contract-owned coin's nullifier is a hash of the coin and the
+ * contract 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 drain that spends it, recover
+ * the drained amount (on a partial drain the change commitment has the value
+ * as its only unknown), and test candidate parent keys against the sent
+ * coin's commitment. A depositor who can guess the parent can confirm it.
  *
  * Knowledge of the preimage is the sole authorization gate — there is
  * no signer set and no nullifier scheme. The operational secret is
  * held off-chain; the contract never sees it except during a drain.
  * Two forwarders bound to the same parent with different operational
- * secrets produce different commitments and are unlinkable on-chain.
+ * secrets produce different commitments, so the ledger does not link them.
  *
  * Underscore-prefixed circuits have no access control beyond the
  * preimage check inside `_drain`. State access is gated by the
@@ -103,7 +113,8 @@ module ForwarderPrivate {
    * @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 plain shielded note,
-   * so the parent stays hidden on-chain. If `coin.value` exceeds `value`,
+   * so the parent stays hidden from anyone who holds no deposited coin (see the
+   * module notice). If `coin.value` exceeds `value`,
    * `sendShielded` routes the change back to this contract as a self-owned
    * output; `_drain` returns it untouched via `result.change`. The
    * implementing contract chooses what to do with it: leave it dwelling at

package/multisig/ForwarderShielded.compact

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

package/multisig/ForwarderUnshielded.compact

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