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

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.5.0-alpha.1 (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.5.0-alpha.1 (access/Ownable.compact)
 
 pragma language_version >= 0.26.0;
 

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.5.0-alpha.1 (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,12 +133,8 @@ 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.
@@ -155,7 +151,8 @@ pragma language_version >= 0.26.0;
  * - 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 +210,13 @@ 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.
+   * @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 +399,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 +432,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 +441,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:
    *
@@ -573,13 +573,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` inserts the nullifier
+   * 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
@@ -603,7 +604,10 @@ module ShieldedAccessControl {
     assert(!isRevoked, "ShieldedAccessControl: role is already revoked");
 
     if (updateType == UpdateType.Grant) {
-      _operatorRoles.insert(disclose(roleCommitment));
+      if (!_grantedRoleNullifiers.member(disclose(roleNullifier))) {
+        _grantedRoleNullifiers.insert(disclose(roleNullifier));
+        _operatorRoles.insert(disclose(roleCommitment));
+      }
     } else {
       _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.5.0-alpha.1 (access/ZOwnablePK.compact)
 
 pragma language_version >= 0.26.0;
 

package/crypto/Ecdh.compact

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (crypto/Ecdh.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module Ecdh
+ * @description Stateless Diffie-Hellman key agreement over Jubjub. Splits into
+ * the two halves of one exchange: `deriveShared` runs the sender side and
+ * returns the ephemeral public key to publish alongside the shared secret, and
+ * `recoverShared` runs the recipient side from that published point. The module
+ * agrees on a point and nothing more: deriving keys, masks or nonces from it
+ * belongs to the consumer (`crypto/EcdhMask` for hybrid encryption).
+ *
+ * @see https://www.secg.org/sec1-v2.pdf#page=33 SEC 1 v2.0 §3.3.1, Elliptic Curve Diffie-Hellman Primitive
+ * @see https://www.secg.org/sec1-v2.pdf#page=30 SEC 1 v2.0 §3.2.2.1, Elliptic Curve Public Key Validation Primitive
+ * @see https://www.secg.org/sec1-v2.pdf#page=29 SEC 1 v2.0 §3.2.1, Elliptic Curve Key Pair Generation Primitive
+ *
+ * @dev Construction and notation. SEC 1's symbol follows in brackets.
+ * - `g`: the Jubjub prime-order subgroup generator, of order `ℓ` [`G`, `n`].
+ * - `ek`: the recipient's secret scalar in `[1, ℓ-1]` [`d`, §3.2.1].
+ * - `e`: the sender's ephemeral scalar in `[1, ℓ-1]`, fresh per call [`d`, §3.2.1].
+ * - `pk = g^ek`: the recipient's public key [`Q`, §3.2.1].
+ * - `E = g^e`: the ephemeral public key, published [`Q`, §3.2.1].
+ * - `S = pk^e = g^{ek*e} = E^ek`: the shared secret point, never published
+ *   [`P = d * Q`, §3.3.1]. §3.3.1 outputs `z = x_P`; this module returns `P`
+ *   itself and leaves the KDF to the consumer.
+ * - `identity`: the point at infinity, `ecMulGenerator(0)` [`O`]. §3.2.2.1
+ *   action 1 rejects it as a key; §3.3.1 action 2 rejects it as `P`.
+ *   `deriveShared` does the first; the second cannot fire in a prime-order
+ *   group once the first holds and `e ≢ 0 (mod ℓ)`.
+ * - Jubjub only. A second curve gets its own module with the same circuit names.
+ *
+ * @dev Future APIs.
+ * - `deriveEphemeral(seed: Bytes<32>, nonce: Field): JubjubScalar` — a canonical
+ *   `e` for consumers, making the uniqueness half of the freshness rule true by
+ *   construction rather than a precondition.
+ * - `assertValidPk(pk)` / `isIdentity(pk): Boolean` — reject an identity key
+ *   where it is registered. The `deriveShared` guard fires on the sender's
+ *   transaction, so a bad key costs the sender, not the registrant.
+ * - Jubjub key-pair derivation lives in `crypto/ElGamal` (`derivePk`,
+ *   `secretToScalar`); a shared key module is its natural home.
+ *
+ * @dev Freshness and secrecy precondition (CRITICAL). `e` MUST be both unique per
+ * call to the same recipient AND secret (unpredictable to observers), even across
+ * circuit invocations that reuse a randomness seed.
+ *
+ * Uniqueness: a repeated `e` to one recipient repeats `S`, so every key, mask or
+ * nonce a consumer derives from `S` repeats too. Where that derivation is a
+ * one-time pad (`crypto/EcdhMask`) the reuse is catastrophic: subtracting two
+ * ciphertexts reveals the plaintext difference, and either plaintext once the
+ * other is known or constrained.
+ *
+ * Secrecy: `recipientPk` is public, so anyone who learns `e` recomputes
+ * `S = recipientPk^e` and everything derived from it. A unique but PREDICTABLE
+ * `e` (a plain counter, a public nonce) therefore breaks confidentiality
+ * completely. `e` must be high-entropy and secret, exactly like an ElGamal
+ * encryption randomness (see `crypto/ElGamal`), not merely distinct.
+ *
+ * The caller supplies `e` and owns both properties, e.g. by expanding a secret
+ * per-invocation seed bound to a per-recipient-unique nonce (a monotonic index).
+ * This is stronger than exponential ElGamal's uniqueness requirement (there,
+ * reuse merely leaks plaintext equality); do not treat `e` as "any randomness."
+ *
+ * @dev Weak inputs. Two degenerate inputs collapse `S` to the identity point,
+ * which every observer can compute: `recipientPk = identity` gives `S = identity`
+ * for any `e`, and `e = 0` gives `S = identity` for any key. Anything a consumer
+ * derives from such an `S` is public. The identity is a valid subgroup point, so
+ * the runtime subgroup guarantee does NOT catch it; `deriveShared` therefore
+ * asserts `recipientPk != identity` and `ephemeralPk (= g^e) != identity`, and
+ * every sender path reaches both through it. Guarding the ephemeral POINT rather
+ * than the scalar subsumes `e != 0` and stays correct regardless of how the
+ * runtime treats 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.) These are the only weak inputs (for a subgroup key,
+ * `S = identity` iff the ephemeral point is the identity).
+ *
+ * @dev Subgroup membership. Secrecy of `S` relies on the runtime constraining
+ * every `JubjubPoint` into the prime-order subgroup (argued in `crypto/ElGamal`),
+ * so a caller cannot hand in a low-order point that leaks `ekScalar`.
+ *
+ * @dev No ledger state, no witnesses. Both circuits are pure and take their keys
+ * and randomness as explicit arguments. `recoverShared` is exposed for
+ * wallet/off-chain use (recovering a received value needs no proof); the on-chain
+ * path only ever calls `deriveShared`.
+ */
+module Ecdh {
+  import CompactStandardLibrary;
+
+  /**
+   * @description One sender-side ECDH step: the ephemeral public key to publish
+   * and the shared secret point to derive from.
+   *
+   * @notice `sShared` is secret. Keep it a circuit local; disclosing it opens
+   * everything derived from it.
+   */
+  export struct SharedSecret {
+    /** `E = g^e`, public. The recipient recovers `S = E^ek` from it. */
+    ephemeralPk: JubjubPoint;
+
+    /** `S = pk^e`, secret. Never disclose; derive from it in-circuit. */
+    sShared: JubjubPoint;
+  }
+
+  /**
+   * @description Runs the sender's ECDH step: the ephemeral public key `g^e` to
+   * publish and the shared secret `pk^e` to derive from. The single site of the
+   * weak-input guards.
+   *
+   * @notice `e` MUST be fresh per call and secret (see the module freshness
+   * precondition).
+   *
+   * @constraints k=11, rows=1385
+   *
+   * Requirements:
+   *
+   * - `recipientPk` is not the identity point.
+   * - `e` is non-zero, a valid Jubjub scalar (`< ℓ`), secret, and fresh per call.
+   *
+   * @param recipientPk - The recipient's Jubjub public key (`g^ek`).
+   * @param e - A fresh ephemeral scalar.
+   * @return `{ ephemeralPk = g^e, sShared = recipientPk^e }`.
+   */
+  export pure circuit deriveShared(recipientPk: JubjubPoint, e: JubjubScalar): SharedSecret {
+    const identity = ecMulGenerator(0 as JubjubScalar);
+    // An identity key gives S = identity for every `e`.
+    assert(recipientPk != identity, "Ecdh: identity pk");
+    const ephemeralPk = ecMulGenerator(e);
+    // Guarding the POINT subsumes `e == 0` and any `e ≡ 0 (mod ℓ)` (see the
+    // weak-inputs note).
+    assert(ephemeralPk != identity, "Ecdh: zero ephemeral");
+    return SharedSecret { ephemeralPk: ephemeralPk, sShared: ecMul(recipientPk, e) };
+  }
+
+  /**
+   * @description The recipient's half of `deriveShared`: recomputes `S = E^ek`
+   * from a published ephemeral public key.
+   *
+   * @dev Never asserts. A wrong `ekScalar` yields an unrelated point, so a wallet
+   * scanning exchanges not addressed to it learns nothing from this circuit and
+   * the module exposes no key-correctness oracle.
+   *
+   * @constraints k=9, rows=440
+   *
+   * @param ephemeralPk - The sender's published `g^e`.
+   * @param ekScalar - The recipient's secret scalar.
+   * @return The ECDH shared secret point.
+   */
+  export pure circuit recoverShared(ephemeralPk: JubjubPoint, ekScalar: JubjubScalar): JubjubPoint {
+    return ecMul(ephemeralPk, ekScalar);
+  }
+}

package/crypto/EcdhMask.compact

@@ -1,23 +1,41 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (crypto/EcdhMask.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (crypto/EcdhMask.compact)
 
 pragma language_version >= 0.26.0;
 
 /**
  * @module EcdhMask
  * @description Stateless ECDH hybrid encryption of a single field element to a
- * Jubjub public key. Delivers a value to whoever holds the secret behind a
- * Jubjub public key WITHOUT encoding it in the exponent, so recovery needs no
- * discrete-log search and the value is unbounded within `Uint<128>`. This is the
- * direct-decrypt counterpart to the homomorphic `crypto/ElGamal`: use ElGamal to
- * accumulate ciphertexts, use this to hand a recipient the plaintext.
+ * Jubjub public key, built on the key agreement in `crypto/Ecdh`. Delivers a
+ * value to whoever holds the secret behind a Jubjub public key WITHOUT encoding
+ * it in the exponent, so recovery needs no discrete-log search and the value is
+ * unbounded within `Uint<128>`. This is the direct-decrypt counterpart to the
+ * homomorphic `crypto/ElGamal`: use ElGamal to accumulate ciphertexts, use this
+ * to hand a recipient the plaintext.
  *
- * Construction (recipient key `pk = g^ek`, ephemeral scalar `e` fresh per call):
- *   E    = g^e                      (ephemeral public key)
- *   S    = pk^e = g^{ek*e}          (ECDH shared secret point)
- *   mask = KDF(S)                   (domain-separated Field, see `kdf`)
- *   ct   = value + mask             (field one-time-pad)
- * Recipient recovers: S = E^ek, mask = KDF(S), value = ct - mask.
+ * @see https://crypto.stanford.edu/~dabo/cryptobook/BonehShoup_0_6.pdf#page=461 Boneh and Shoup, A Graduate Course in Applied Cryptography v0.6, §11.5 ElGamal encryption (E_EG), Remark 11.1 (E'_EG), Theorem 11.4
+ * @see https://crypto.stanford.edu/~dabo/cryptobook/BonehShoup_0_6.pdf#page=495 Boneh and Shoup, §12.4 CCA-secure ElGamal encryption, Theorem 12.4
+ * @see https://www.shoup.net/papers/twindh.pdf Cash, Kiltz and Shoup, The Twin Diffie-Hellman Problem and Applications, §1.1 Hashed ElGamal Encryption
+ * @see https://cseweb.ucsd.edu/~mihir/papers/dhies.pdf Abdalla, Bellare and Rogaway, DHIES, §8 ODH and SDH
+ * @see https://www.secg.org/sec1-v2.pdf#page=58 SEC 1 v2.0 §5.1.3, Encryption Operation
+ * @see https://www.secg.org/sec1-v2.pdf#page=59 SEC 1 v2.0 §5.1.4, Decryption Operation, action 3
+ *
+ * @dev Construction and notation. Boneh and Shoup's E'_EG symbol follows in
+ * brackets (§11.5, Remark 11.1).
+ * - `pk = g^ek`: the recipient's public key [`u = g^α`].
+ * - `e`: the ephemeral scalar, fresh per call [`β`].
+ * - `E = g^e`: the ephemeral public key [`v = g^β`].
+ * - `S = pk^e = g^{ek*e}`: the shared point, from `crypto/Ecdh` [`w = u^β`].
+ * - `mask = KDF(S, domain)`: the domain-separated field mask, see `kdf`
+ *   [`k = H(w)`]. E_EG hashes `(v, w)`; E'_EG hashes `w` alone, as here.
+ * - `ct = value + mask`: the field one-time pad [`c = E_s(k, m)`].
+ * - `Ciphertext { ephemeralPk: E, ct }`: the ciphertext [`(v, c)`].
+ * - Recipient recovers `S = E^ek`, `mask = KDF(S, domain)`, `value = ct - mask`.
+ *
+ * @dev Key agreement. `deriveShared`, `recoverShared` and the `SharedSecret`
+ * struct live in `crypto/Ecdh` and are not re-exported here; a consumer that
+ * needs them imports that module directly. It owns the weak-input guards every
+ * sender path here inherits.
  *
  * @dev Freshness and secrecy precondition (CRITICAL). `e` MUST be both unique per
  * call to the same recipient AND secret (unpredictable to observers), even across
@@ -25,7 +43,8 @@ pragma language_version >= 0.26.0;
  *
  * Uniqueness: the mask is a one-time pad, so a repeated `e` repeats `S` and
  * `mask`, and reusing a pad is catastrophic (subtracting two ciphertexts recovers
- * both values).
+ * both values). Padding two values under the same `(S, domain)` reuses the pad
+ * the same way (see `kdf`).
  *
  * Secrecy: `recipientPk` is public, so anyone who learns `e` recomputes
  * `S = recipientPk^e`, hence the mask, and opens the ciphertext. A unique but
@@ -38,19 +57,11 @@ pragma language_version >= 0.26.0;
  * This is stronger than exponential ElGamal's uniqueness requirement (there,
  * reuse merely leaks plaintext equality); do not treat `e` as "any randomness."
  *
- * @dev Weak inputs. Two degenerate inputs zero the shared secret and expose the
- * value: `recipientPk = identity` gives `S = identity` for any `e`, and `e = 0`
- * gives `S = identity` for any key. Both yield `mask = KDF(identity, domain)`, a
- * value any observer can recompute, so `ct = value + mask` opens trivially. The
- * identity is a valid subgroup point, so the runtime subgroup guarantee does NOT
- * catch it; `encrypt` therefore asserts `recipientPk != identity` and
- * `ephemeralPk (= g^e) != identity`. Guarding the ephemeral POINT rather than the
- * scalar subsumes `e != 0` and stays correct regardless of how the runtime treats
- * 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.)
- * These are the only weak inputs (for a subgroup key, `S = identity` iff the
- * ephemeral point is the identity).
+ * @dev Weak inputs. An identity `recipientPk` or a zero `e` collapses `S` to the
+ * identity point, giving `mask = KDF(identity, domain)`, a value any observer can
+ * recompute, so `ct = value + mask` opens trivially. `crypto/Ecdh.deriveShared`
+ * rejects both, and `encrypt` reaches them only through it; that module's
+ * weak-inputs note carries the full argument.
  *
  * @dev Integrity. The pad is malleable and NO authentication is added here. This
  * is safe in the intended on-chain use, where the ciphertext is computed
@@ -60,10 +71,13 @@ pragma language_version >= 0.26.0;
  * enable theft. Consumers with a different threat model (mutable storage,
  * in-transit tampering) MUST add their own authentication.
  *
- * @dev Security. This is hashed ElGamal (ECIES without a MAC) over Jubjub and
- * inherits its guarantees: IND-CPA under the Oracle Diffie-Hellman assumption in
- * the random-oracle model (the `persistentHash` KDF keyed by the secret point
- * `S`). It is NOT IND-CCA: the additive pad is malleable (see Integrity), which
+ * @dev Security. This is hashed ElGamal over Jubjub: Boneh and Shoup, *A
+ * Graduate Course in Applied Cryptography* v0.6, §11.5, in the Remark 11.1
+ * form that keys the KDF on the shared point alone. It inherits that scheme's
+ * guarantee: IND-CPA under CDH in the random-oracle model (Theorem 11.4, the
+ * `persistentHash` KDF keyed by the secret point `S`), and so also under the
+ * stronger Oracle Diffie-Hellman assumption. It is NOT IND-CCA: Theorem 12.4
+ * needs a MAC, and the additive pad is malleable (see Integrity), which
  * is acceptable here only because the on-chain ciphertext is bound in-circuit to
  * the value it commits to elsewhere. Hiding carries a large margin: `kdf` returns
  * a `degradeToTransient` output in `[0, 2^248)` while `value < 2^128`, so even
@@ -72,9 +86,10 @@ pragma language_version >= 0.26.0;
  * is PRF-like. Confidentiality relies on the runtime constraining every
  * `JubjubPoint` into the prime-order subgroup (see `crypto/ElGamal`), so `S`
  * cannot be a low-order point that leaks `ek`. Binding the ephemeral `E` into the
- * KDF is deliberately omitted: for a fixed `recipientPk`, `E = g^e` and
- * `S = pk^e` are both determined by `e`, so `KDF(S)` already varies with `E` and
- * folding it in buys nothing.
+ * KDF is deliberately omitted (Remark 11.1): for a fixed `recipientPk`, `E = g^e`
+ * and `S = pk^e` are both determined by `e`, so `KDF(S)` already varies with `E`;
+ * folding it in only tightens the CCA reduction (Remark 12.2)
+ * which this module does not claim.
  *
  * @dev Shared key with `crypto/ElGamal` (in scope). A consumer MAY use the same
  * recipient Jubjub key for both these memos (hashed ElGamal) and exponential-
@@ -82,6 +97,9 @@ pragma language_version >= 0.26.0;
  * safe: the two schemes share only the public key, this KDF is domain-separated
  * and keyed by the secret DH point, and neither exposes a decryption oracle, so
  * under CPA / ODH a ciphertext of one scheme does not help attack the other.
+ * The per-encryption scalars MUST be independent (e.g. distinct
+ * `expandRandomness` tags over one seed): a shared scalar shares `S`, so the
+ * memo becomes a plaintext-check oracle for the ElGamal ciphertext.
  *
  * @dev No ledger state, no witnesses. Every circuit is pure and takes its keys,
  * value, and randomness as explicit arguments. `decrypt` is exposed as a pure
@@ -90,37 +108,22 @@ pragma language_version >= 0.26.0;
  */
 module EcdhMask {
   import CompactStandardLibrary;
+  import "./Ecdh" prefix Ecdh_;
 
   /**
-   * @description An ECDH one-time-pad ciphertext: the ephemeral public key and
-   * the field-masked value.
+   * @description An ECDH one-time-pad ciphertext, `(v, c)` in Boneh and Shoup.
+   * Public once written; neither field is secret on its own.
+   *
+   * @notice `ephemeralPk` is never the identity for a ciphertext `encrypt`
+   * produced, and `decrypt` rejects one that is. A consumer that hand-builds a
+   * placeholder with an identity `ephemeralPk` must document it as a sentinel.
    */
   export struct Ciphertext {
+    /** `E = g^e`, the sender's ephemeral public key. Never the identity. */
     ephemeralPk: JubjubPoint;
-    ct: Field;
-  }
 
-  /**
-   * @description Derives the field mask from the ECDH shared secret point,
-   * domain-separated by a caller-supplied `domain` tag. Hashes the point to
-   * `Bytes<32>`, then re-hashes it with the domain tag and truncates into the
-   * field via `degradeToTransient`. The consumer chooses `domain` (so this
-   * module is not tied to any one protocol) and MUST use the same value on
-   * encrypt and decrypt.
-   *
-   * @dev Uses `persistentHash` deliberately: the recipient reproduces this mask
-   * to decrypt, possibly across a platform upgrade, so it must be upgrade-stable.
-   *
-   * @param sShared - The ECDH shared secret point (`pk^e` for the sender,
-   *                  `E^ek` for the recipient; equal by construction).
-   * @param domain - The consumer's domain-separation tag.
-   * @return The field mask.
-   */
-  export pure circuit kdf(sShared: JubjubPoint, domain: Bytes<32>): Field {
-    const pointHash = persistentHash<JubjubPoint>(sShared);
-    return degradeToTransient(
-      persistentHash<Vector<2, Bytes<32>>>([pointHash, domain])
-    );
+    /** `value + KDF(S, domain)`, the field one-time pad over the value. */
+    ct: Field;
   }
 
   /**
@@ -128,6 +131,8 @@ module EcdhMask {
    *
    * @notice `e` MUST be fresh per call (see the module freshness precondition).
    *
+   * @constraints k=14, rows=9269
+   *
    * Requirements:
    *
    * - `recipientPk` is not the identity point.
@@ -145,23 +150,47 @@ module EcdhMask {
                         e: JubjubScalar,
                         domain: Bytes<32>
                         ): Ciphertext {
-    const identity = ecMulGenerator(0 as JubjubScalar);
-    assert(recipientPk != identity, "EcdhMask: identity pk");
-    const ephemeralPk = ecMulGenerator(e);
-    // Guard the ephemeral POINT, not the scalar: `ephemeralPk == identity`
-    // captures `e == 0` and any `e` that reduces to 0 mod l, so the guard is
-    // correct regardless of how the runtime treats an out-of-range scalar. This
-    // subsumes `e != 0` (see the weak-inputs note).
-    assert(ephemeralPk != identity, "EcdhMask: zero ephemeral");
-    const sShared = ecMul(recipientPk, e);
-    const mask = kdf(sShared, domain);
-    return Ciphertext { ephemeralPk: ephemeralPk, ct: (value as Field) + mask };
+    // The weak-input guards come from `deriveShared`, not repeated here.
+    const shared = Ecdh_deriveShared(recipientPk, e);
+    const mask = kdf(shared.sShared, domain);
+    return Ciphertext { ephemeralPk: shared.ephemeralPk, ct: (value as Field) + mask };
+  }
+
+  /**
+   * @description Derives the field mask from the ECDH shared secret point and
+   * a caller-supplied `domain` tag: hashes the point to `Bytes<32>`, re-hashes
+   * it with the tag, and truncates into the field via `degradeToTransient`.
+   * The mask is a pure function of `(sShared, domain)`, so the pair MUST match
+   * on encrypt and decrypt, and MUST be distinct for every value it pads. Two
+   * values padded under one pair share the pad and leak their difference.
+   *
+   * @dev Uses `persistentHash` deliberately: the recipient reproduces this mask
+   * to decrypt, possibly across a platform upgrade, so it must be upgrade-stable.
+   *
+   * @constraints k=13, rows=7917
+   *
+   * @param sShared - The ECDH shared secret point (`pk^e` for the sender,
+   *                  `E^ek` for the recipient; equal by construction).
+   * @param domain - The consumer's domain-separation tag.
+   * @return The field mask.
+   */
+  export pure circuit kdf(sShared: JubjubPoint, domain: Bytes<32>): Field {
+    const pointHash = persistentHash<JubjubPoint>(sShared);
+    return degradeToTransient(
+      persistentHash<Vector<2, Bytes<32>>>([pointHash, domain])
+    );
   }
 
   /**
    * @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).
    *
+   * @notice Rejects a ciphertext whose `ephemeralPk` is the identity point
+   * (SEC 1 §5.1.4, action 3). `encrypt` cannot produce one, so a wallet that
+   * meets one holds a placeholder, not an encryption.
+   *
+   * @constraints k=14, rows=8976
+   *
    * @param ciphertext - The ciphertext to decrypt.
    * @param ekScalar - The recipient's secret scalar (`crypto/ElGamal`'s
    *                   `secretToScalar(EK)`).
@@ -170,7 +199,11 @@ module EcdhMask {
    *         which is `< 2^128`).
    */
   export pure circuit decrypt(ciphertext: Ciphertext, ekScalar: JubjubScalar, domain: Bytes<32>): Field {
-    const sShared = ecMul(ciphertext.ephemeralPk, ekScalar);
+    // `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 = Ecdh_recoverShared(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.5.0-alpha.1 (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.5.0-alpha.1 (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.5.0-alpha.1 (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.5.0-alpha.1 (multisig/ForwarderPrivate.compact)
 
 pragma language_version >= 0.26.0;
 

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.5.0-alpha.1 (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.5.0-alpha.1 (multisig/ForwarderUnshielded.compact)
 
 pragma language_version >= 0.26.0;
 

package/multisig/ProposalManager.compact

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

package/multisig/Secp256k1EcdsaMultisig.compact

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

package/multisig/ShieldedTreasury.compact

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