@openzeppelin/compact-contracts 0.4.0 → 0.5.0-alpha.2

package/crypto/EcdhMask.compact

@@ -1,23 +1,44 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0 (crypto/EcdhMask.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (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<248>`. 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.
+ *   `kdf` is `kdfFromDigest(pointDigest(S), domain)`, a one-step hash KDF
+ *   (the `H(Z ‖ FixedInfo)` shape of NIST SP 800-56C §4, one block, 248-bit
+ *   output); a consumer deriving several masks from one `S` digests it once.
+ * - `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 +46,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,21 +60,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.)
- * `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).
+ * @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
@@ -62,21 +74,29 @@ 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. For plaintexts well below
+ * the pad's width (see the hiding bound below) 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
- * treating the KDF output as uniform the value is hidden with about `2^-120`
- * statistical slack, leaving only the assumption that the hash of the DH secret
- * 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.
+ * the value it commits to elsewhere. Hiding depends on the plaintext width. The
+ * `kdf` output is a `degradeToTransient` value in `[0, 2^248)`. Taken as
+ * uniform, it hides a value below `2^w` within `2^(w-248)` statistical slack. A
+ * `Uint<128>` keeps about `2^-120`, leaving only the assumption that the hash of
+ * the DH secret is PRF-like. A full `Uint<248>` has no margin: a random one
+ * loses under one bit on average, but two chosen values far apart are
+ * distinguishable. The type excludes anything at or above `2^248`.
+ * 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 (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-
@@ -84,6 +104,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
@@ -92,37 +115,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;
   }
 
   /**
@@ -130,57 +138,111 @@ module EcdhMask {
    *
    * @notice `e` MUST be fresh per call (see the module freshness precondition).
    *
+   * @constraints k=14, rows=9318 (zkir-v3)
+   *
    * 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 value - The value to deliver (any `Uint<128>`; no `2^48` bound).
+   * @param value - The value to deliver, any `Uint<248>`. The hiding margin
+   *                shrinks as its width grows (see the module security note).
    * @param e - A fresh ephemeral scalar.
    * @param domain - The consumer's domain-separation tag (must match decrypt).
    * @return The ciphertext `{ ephemeralPk = g^e, ct = value + KDF(pk^e) }`.
    */
   export pure circuit encrypt(
                         recipientPk: JubjubPoint,
-                        value: Uint<128>,
+                        value: Uint<248>,
                         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=7914 (zkir-v3)
+   *
+   * @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 {
+    return kdfFromDigest(pointDigest(sShared), domain);
+  }
+
+  /**
+   * @description `H(sShared)`, the secret input of `kdf`. A consumer deriving
+   * several masks from one shared point digests it once and calls
+   * `kdfFromDigest` per tag.
+   *
+   * @constraints k=13, rows=4098 (zkir-v3)
+   *
+   * @param sShared - The ECDH shared secret point.
+   * @return The point's digest, secret while `sShared` is.
+   */
+  export pure circuit pointDigest(sShared: JubjubPoint): Bytes<32> {
+    return persistentHash<JubjubPoint>(sShared);
+  }
+
+  /**
+   * @description The mask for `domain` from a point digest:
+   * `kdf(S, domain) == kdfFromDigest(pointDigest(S), domain)`.
+   *
+   * @notice One mask per `(digest, domain)`. Pad one value under each pair,
+   * and give every mask drawn from one digest its own tag; two values under
+   * one pair share the pad and leak their difference.
+   *
+   * @constraints k=13, rows=3956 (zkir-v3)
+   *
+   * @param digest - `pointDigest` of the shared point.
+   * @param domain - The consumer's domain-separation tag.
+   * @return The field mask.
+   */
+  export pure circuit kdfFromDigest(digest: Bytes<32>, domain: Bytes<32>): Field {
+    return degradeToTransient(
+      persistentHash<Vector<2, Bytes<32>>>([digest, 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).
    *
-   * Requirements:
+   * @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.
    *
-   * - `ciphertext.ephemeralPk` is not the identity point.
+   * @constraints k=14, rows=8976 (zkir-v3)
    *
    * @param ciphertext - The ciphertext to decrypt.
    * @param ekScalar - The recipient's secret scalar (`crypto/ElGamal`'s
    *                   `secretToScalar(EK)`).
    * @param domain - The consumer's domain-separation tag (must match encrypt).
    * @return The recovered value as a `Field` (equal to the original `value`,
-   *         which is `< 2^128`).
+   *         which is `< 2^248`).
    */
   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 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 (crypto/Ecdsa.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (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 (crypto/Eip712.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (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 (crypto/ElGamal.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (crypto/ElGamal.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -71,16 +71,17 @@ pragma language_version >= 0.26.0;
  * @dev Weak keys. Encrypting under the identity point yields `c2 = m` with no
  * masking (the plaintext is exposed), and the identity is a valid subgroup
  * point so the runtime subgroup guarantee does NOT catch it. `encryptPoint`
- * therefore asserts `pk != identity`, and every encryption path routes through
- * it, so confidentiality is protected regardless of the importer. An importing
+ * therefore takes its mask from `crypto/Ecdh`'s `deriveShared`, which rejects
+ * an identity `pk`, and every encryption path routes through it, so
+ * confidentiality is protected regardless of the importer. An importing
  * module MAY additionally reject an identity `pk` where keys enter the system
  * (e.g. at registration) to fail fast with a clear error rather than at first
  * encryption — a UX nicety, not a confidentiality requirement.
  *
- * @dev Randomness. `encryptPoint` asserts `r != 0` — like `pk = identity`,
- * `r = 0` zeros the mask (`r*pk = O`), yielding the non-hiding `(O, m)`; it is
- * the unique mask-zeroing randomness, so the two asserts together guarantee a
- * non-trivial mask. The remaining obligations the circuit CANNOT enforce:
+ * @dev Randomness. `r = 0` zeros the mask (`r*pk = O`), yielding the
+ * non-hiding `(O, m)`; `deriveShared` rejects it as a zero ephemeral, so
+ * together with the identity-`pk` guard the mask is always non-trivial. The
+ * remaining obligations the circuit CANNOT enforce:
  * every `r` MUST be a valid Jubjub scalar (`< ℓ`, the subgroup order; larger
  * values fault `ecMul`), and MUST be fresh and secret. Reusing an `r` under the
  * same `pk` leaks the difference of the two plaintexts (`c1` collides, so
@@ -89,6 +90,7 @@ pragma language_version >= 0.26.0;
  */
 module ElGamal {
   import CompactStandardLibrary;
+  import "./Ecdh" prefix Ecdh_;
 
   // ---------------------------------------------------------------------------
   // Types
@@ -215,12 +217,10 @@ module ElGamal {
    * @return The ciphertext `(g^r, pk^r * m)`.
    */
   export pure circuit encryptPoint(pk: JubjubPoint, m: JubjubPoint, r: JubjubScalar): Ciphertext {
-    assert(pk != ecMulGenerator(0 as JubjubScalar), "ElGamal: identity pk");
-    assert(r != 0 as JubjubScalar, "ElGamal: zero randomness");
-    const c1 = ecMulGenerator(r);
-    const mask = ecMul(pk, r);
-    const c2 = ecAdd(mask, m);
-    return Ciphertext { c1: c1, c2: c2 };
+    // The weak-input guards come from `deriveShared`, not repeated here.
+    const shared = Ecdh_deriveShared(pk, r);
+    const c2 = ecAdd(shared.sShared, m);
+    return Ciphertext { c1: shared.ephemeralPk, c2: c2 };
   }
 
   /**

package/math/UintN.compact

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (math/UintN.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module UintN
+ * @description Wrapping arithmetic on `Uint<N>` for any width `N`: results
+ * are reduced modulo `2^N`, and no input fails. Instantiate with a width, e.g.
+ * `UintN<64>`, `UintN<248>`.
+ *
+ * @dev Names and semantics follow Rust's `wrapping_add` and `wrapping_sub`.
+ * The `Field` shape follows Noir's `WrappingAdd` and `WrappingSub`, with
+ * arkworks' `UInt<N>` as the generic-width precedent. Noir's `as` truncates,
+ * but `as Uint<N>` fails out of range. Each circuit therefore reduces
+ * explicitly, selects between two `Field` arms, and casts once, outside the
+ * select.
+ *
+ * @dev The `Field` arithmetic is exact while `a + b` stays below the field
+ * modulus, which holds for `N <= 253` and so for every width `Uint<N>` admits.
+ *
+ * Supported Operations:
+ * - MODULUS(): `2^N` as a `Field`.
+ * - wrappingAdd(a, b): `(a + b) mod 2^N`.
+ * - wrappingSub(a, b): `(a - b) mod 2^N`.
+ */
+module UintN<#N> {
+  /**
+   * @description `2^N` as a `Field`: the modulus of every circuit in this
+   * module.
+   *
+   * @constraints k=5, rows=23 (zkir-v2, any N)
+   * @constraints k=6, rows=31 (zkir-v3, any N)
+   *
+   * @returns {Field} `2^N`.
+   */
+  export pure circuit MODULUS(): Field {
+    return fold((acc: Field, _bit: Boolean): Field => acc * 2,
+                1 as Field,
+                default<Vector<N, Boolean>>);
+  }
+
+  /**
+   * @description Wrapping (modular) addition. Computes `a + b`, wrapping
+   * around at the boundary of the type.
+   *
+   * @dev The wrap test is `a > MAX - b`, which needs no `Uint<N + 1>`.
+   *
+   * @constraints depends on N:
+   * - UintN<8>: k=9, rows=98 (zkir-v2), k=9, rows=85 (zkir-v3)
+   * - UintN<64>: k=9, rows=308 (zkir-v2), k=9, rows=133 (zkir-v3)
+   * - UintN<248>: k=10, rows=980 (zkir-v2), k=9, rows=307 (zkir-v3)
+   *
+   * @param {Uint<N>} a - The first operand.
+   * @param {Uint<N>} b - The second operand.
+   * @returns {Uint<N>} `(a + b) mod 2^N`.
+   */
+  export pure circuit wrappingAdd(a: Uint<N>, b: Uint<N>): Uint<N> {
+    const modulus = MODULUS();
+    const wraps = a > ((modulus - 1) as Uint<N>) - b;
+    const sum = (a as Field) + (b as Field);
+    return (wraps ? sum - modulus : sum) as Uint<N>;
+  }
+
+  /**
+   * @description Wrapping (modular) subtraction. Computes `a - b`, wrapping
+   * around at the boundary of the type.
+   *
+   * @constraints depends on N:
+   * - UintN<8>: k=9, rows=84 (zkir-v2), k=9, rows=73 (zkir-v3)
+   * - UintN<64>: k=9, rows=273 (zkir-v2), k=9, rows=118 (zkir-v3)
+   * - UintN<248>: k=10, rows=885 (zkir-v2), k=9, rows=274 (zkir-v3)
+   *
+   * @param {Uint<N>} a - The minuend.
+   * @param {Uint<N>} b - The subtrahend.
+   * @returns {Uint<N>} `(a - b) mod 2^N`.
+   */
+  export pure circuit wrappingSub(a: Uint<N>, b: Uint<N>): Uint<N> {
+    const diff = (a as Field) - (b as Field);
+    return (a < b ? diff + MODULUS() : diff) as Uint<N>;
+  }
+}

package/multisig/ForwarderPrivate.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0 (multisig/ForwarderPrivate.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (multisig/ForwarderPrivate.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -10,25 +10,15 @@ 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 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.
+ * 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.
  *
  * 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, so the ledger does not link them.
+ * secrets produce different commitments and are unlinkable on-chain.
  *
  * Underscore-prefixed circuits have no access control beyond the
  * preimage check inside `_drain`. State access is gated by the
@@ -113,8 +103,7 @@ 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 from anyone who holds no deposited coin (see the
-   * module notice). If `coin.value` exceeds `value`,
+   * so the parent stays hidden on-chain. 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 (multisig/ForwarderShielded.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (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 (multisig/ForwarderUnshielded.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (multisig/ForwarderUnshielded.compact)
 
 pragma language_version >= 0.26.0;