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

package/README.md

@@ -10,7 +10,7 @@ This project is built on the Midnight Network.
 
 > ## ⚠️ WARNING! ⚠️
 >
-> This repo contains highly experimental code.
+> Pre-release versions (`-alpha`, `-rc`) contain experimental, unaudited code.
 > Expect rapid iteration.
 > **Use at your own risk.**
 
@@ -193,7 +193,7 @@ ZKIR v3: the library targets ZKIR v2, the compiler 0.34.0 default.
 Pass `--feature-zkir-v3` only when the contract reaches a module that needs it:
 the secp256k1-based `crypto/Ecdsa` and `multisig/Secp256k1EcdsaMultisig`,
 or the `keccak256`-based `crypto/Eip712`.
-`multisig/presets/ShieldedMultiSigV2`, `multisig/presets/NativeShieldedTokenIssuer`
+`multisig/presets/NativeShieldedStatelessTreasury`, `multisig/presets/NativeShieldedTokenIssuer`
 and the `multisig/examples/` contracts reach both.
 `utils/EvmAbi` needs no `keccak256` of its own and compiles on either backend.
 Compiling the other modules under v3 currently hits upstream blockers,
@@ -233,6 +233,8 @@ yarn compile
 yarn test
 ```
 
+Integration and live suites are described in [TESTING.md](TESTING.md).
+
 ### Check/apply Biome formatter
 
 ```bash
@@ -247,6 +249,7 @@ yarn lint:fix
 ```bash
 yarn compile:access
 yarn compile:archive
+yarn compile:math
 ...
 ```
 
@@ -278,9 +281,11 @@ rm -rf .turbo/
 
 ## Security
 
-This project is still in a very early and experimental phase. It has never been audited nor thoroughly reviewed for security vulnerabilities. DO NOT USE IT IN PRODUCTION.
+For production, use a stable release (no `-alpha` or `-rc` suffix) on the Midnight ledger it targets. Pre-releases are not audited and should not be used in production.
+
+Scopes and audited commits are listed in [audits](./audits/README.md).
 
-Please report any security issues you find to <security@openzeppelin.com>.
+Please report any security issues you find to <security@openzeppelin.com>. See [SECURITY.md](SECURITY.md).
 
 ### Provenance
 

package/access/AccessControl.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (access/AccessControl.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (access/AccessControl.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -61,18 +61,17 @@ pragma language_version >= 0.26.0;
  * through the main role approval circuits (`grantRole` and `_grantRole`).
  * In other words, role approvals to contract addresses are disallowed through these
  * circuits.
- * This is because Compact currently does not support contract-to-contract calls which means
- * if a contract is granted a role, the contract cannot directly call the protected
- * circuit.
+ * This is because this library has not yet migrated to contract-to-contract calls, which means
+ * a contract granted a role cannot directly call the protected circuit.
  *
  * @notice This module does offer an experimental circuit that allows roles to be granted
  * to contract addresses (`_unsafeGrantRole`).
  * Note that the circuit name is very explicit ("unsafe") with this experimental circuit.
- * Until contract-to-contract calls are supported,
+ * Until this library migrates to contract-to-contract calls,
  * there is no direct way for a contract to call protected circuits.
  *
- * @notice The unsafe circuits are planned to become deprecated once contract-to-contract calls
- * are supported.
+ * @notice The unsafe circuits are planned to become deprecated once this library migrates to
+ * contract-to-contract calls.
  *
  * @dev Migration plan (safe -> C2C-capable role grants)
  *
@@ -84,8 +83,8 @@ pragma language_version >= 0.26.0;
  * which is the only kind of upgrade the CMA supports. Widening the type later would instead force
  * a ledger-layout rewrite, which the CMA cannot perform.
  *
- * When C2C lands, an already-deployed contract migrates without changing its address or ledger
- * state:
+ * When the C2C migration lands, an already-deployed contract migrates without changing its address
+ * or ledger state:
  *
  * - Minor release: mark `_unsafeGrantRole` deprecated (and emit a warning if possible); keep its
  *   implementation intact so existing callers continue to work.

package/access/Ownable.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (access/Ownable.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (access/Ownable.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -28,18 +28,17 @@ pragma language_version >= 0.26.0;
  * through the main transfer circuits (`transferOwnership` and `_transferOwnership`).
  * In other words, ownership transfers to contract addresses are disallowed through these
  * circuits.
- * This is because Compact currently does not support contract-to-contract calls which means
- * if a contract is granted ownership, the owner contract cannot directly call the protected
- * circuit.
+ * This is because this library has not yet migrated to contract-to-contract calls, which means
+ * a contract granted ownership cannot directly call the protected circuit.
  *
  * @notice This module does offer experimental circuits that allow ownership to be granted
  * to contract addresses (`_unsafeTransferOwnership` and `_unsafeUncheckedTransferOwnership`).
  * Note that the circuit names are very explicit ("unsafe") with these experimental circuits.
- * Until contract-to-contract calls are supported, there is no direct way for a contract
+ * Until this library migrates to contract-to-contract calls, there is no direct way for a contract
  * to authenticate as an owner.
  *
- * @notice The unsafe circuits are planned to become deprecated once contract-to-contract calls
- * are supported.
+ * @notice The unsafe circuits are planned to become deprecated once this library migrates to
+ * contract-to-contract calls.
  *
  * @dev Migration plan (safe -> C2C-capable ownership transfers)
  *
@@ -51,8 +50,8 @@ pragma language_version >= 0.26.0;
  * which is the only kind of upgrade the CMA supports. Widening the type later would instead force
  * a ledger-layout rewrite, which the CMA cannot perform.
  *
- * When C2C lands, an already-deployed contract migrates without changing its address or ledger
- * state:
+ * When the C2C migration lands, an already-deployed contract migrates without changing its address
+ * or ledger state:
  *
  * - Minor release: mark `_unsafeTransferOwnership` (and `_unsafeUncheckedTransferOwnership`)
  *   deprecated (and emit a warning if possible); keep their implementation intact so existing
@@ -180,8 +179,8 @@ module Ownable {
   /**
    * @description Transfers ownership of the contract to `newOwner`.
    *
-   * @notice Ownership transfers to contract addresses are currently disallowed until contract-to-contract
-   * interactions are supported in Compact.
+   * @notice Ownership transfers to contract addresses are disallowed until this library migrates to
+   * contract-to-contract calls.
    * This restriction prevents permanently disabling access to a circuit.
    *
    * @constraints k=13, rows=2947
@@ -206,10 +205,10 @@ module Ownable {
   /**
    * @description Unsafe variant of `transferOwnership`.
    *
-   * @warning Ownership transfers to contract addresses are considered unsafe because contract-to-contract
-   * calls are not currently supported.
+   * @warning Ownership transfers to contract addresses are considered unsafe because this library
+   * has not yet migrated to contract-to-contract calls.
    * Ownership privileges sent to a contract address may become uncallable.
-   * Once contract-to-contract calls are supported, this circuit may be deprecated.
+   * Once this library migrates to contract-to-contract calls, this circuit may be deprecated.
    *
    * @constraints k=13, rows=2944
    *
@@ -248,7 +247,7 @@ module Ownable {
     assertOnlyOwner();
 
     // We use `left` here because `assertOnlyOwner` would return a misleading
-    // error msg (c2c is not currently supported)
+    // error msg (this library has not yet migrated to c2c)
     const zero = Either<Bytes<32>, ContractAddress> {
       is_left: true, left: default<Bytes<32>>, right: default<ContractAddress>
     };
@@ -284,8 +283,8 @@ module Ownable {
    * @description Transfers ownership of the contract to `newOwner` without
    * enforcing permission checks on the caller.
    *
-   * @notice Ownership transfers to contract addresses are currently disallowed until contract-to-contract
-   * interactions are supported in Compact.
+   * @notice Ownership transfers to contract addresses are disallowed until this library migrates to
+   * contract-to-contract calls.
    * This restriction prevents circuits from being inadvertently locked in contracts.
    *
    * @constraints k=10, rows=598
@@ -308,10 +307,10 @@ module Ownable {
   /**
    * @description Unsafe variant of `_transferOwnership`.
    *
-   * @warning Ownership transfers to contract addresses are considered unsafe because contract-to-contract
-   * calls are not currently supported.
+   * @warning Ownership transfers to contract addresses are considered unsafe because this library
+   * has not yet migrated to contract-to-contract calls.
    * Ownership privileges sent to a contract address may become uncallable.
-   * Once contract-to-contract calls are supported, this circuit may be deprecated.
+   * Once this library migrates to contract-to-contract calls, this circuit may be deprecated.
    *
    * @constraints k=10, rows=595
    *

package/access/ShieldedAccessControl.compact

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

package/access/ZOwnablePK.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (access/ZOwnablePK.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (access/ZOwnablePK.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -15,8 +15,8 @@ pragma language_version >= 0.26.0;
  * For the strongest security guarantees, use an Air-Gapped Public Key.
  *
  * @notice This module explicitly supports commitments derived from public keys;
- * however, it may be possible to use contract addresses when contract-to-contract
- * calls become available. This will be revisited when it's known if/how witnesses
+ * however, it may be possible to use contract addresses once this library migrates to
+ * contract-to-contract calls. This will be revisited when it's known if/how witnesses
  * are used from a contract address context.
  *
  * @dev Features:

package/crypto/Ecdh.compact

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

package/crypto/EcdhMask.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (crypto/EcdhMask.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (crypto/EcdhMask.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -9,7 +9,7 @@ pragma language_version >= 0.26.0;
  * 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
+ * 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.
  *
@@ -28,6 +28,9 @@ pragma language_version >= 0.26.0;
  * - `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`.
@@ -73,23 +76,27 @@ pragma language_version >= 0.26.0;
  *
  * @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
+ * 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 (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.
+ * 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-
@@ -131,7 +138,7 @@ module EcdhMask {
    *
    * @notice `e` MUST be fresh per call (see the module freshness precondition).
    *
-   * @constraints k=14, rows=9269
+   * @constraints k=14, rows=9318 (zkir-v3)
    *
    * Requirements:
    *
@@ -139,14 +146,15 @@ module EcdhMask {
    * - `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 {
@@ -167,7 +175,7 @@ module EcdhMask {
    * @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
+   * @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).
@@ -175,9 +183,40 @@ module EcdhMask {
    * @return The field mask.
    */
   export pure circuit kdf(sShared: JubjubPoint, domain: Bytes<32>): Field {
-    const pointHash = persistentHash<JubjubPoint>(sShared);
+    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>>>([pointHash, domain])
+      persistentHash<Vector<2, Bytes<32>>>([digest, domain])
     );
   }
 
@@ -189,14 +228,14 @@ module EcdhMask {
    * (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
+   * @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

package/crypto/Ecdsa.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (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.5.0-alpha.1 (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.5.0-alpha.1 (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.5.0-alpha.1 (multisig/ForwarderPrivate.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (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.5.0-alpha.1 (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.5.0-alpha.1 (multisig/ForwarderUnshielded.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (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.5.0-alpha.1 (multisig/ProposalManager.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (multisig/ProposalManager.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -107,8 +107,8 @@ module ProposalManager {
    * checks and the deadline comparison above. `_proposals` is exported ledger
    * state and readable without a proof. `executedState` and
    * `cancelledState` are pure, so a reader can obtain the sentinel values without
-   * hardcoding them. A state-reading accessor will be revisited once contract-to-contract
-   * interactions are available.
+   * hardcoding them. A state-reading accessor will be revisited once this library migrates to
+   * contract-to-contract calls.
    */
   export struct Proposal {
     to: Recipient,

package/multisig/Secp256k1EcdsaMultisig.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (multisig/Secp256k1EcdsaMultisig.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (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.5.0-alpha.1 (multisig/ShieldedTreasury.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (multisig/ShieldedTreasury.compact)
 
 pragma language_version >= 0.26.0;
 

package/multisig/ShieldedTreasuryStateless.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.5.0-alpha.1 (multisig/ShieldedTreasuryStateless.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (multisig/ShieldedTreasuryStateless.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -63,16 +63,10 @@ module ShieldedTreasuryStateless {
    * self — `sendShielded` already routes it to self.) No balance or
    * received/sent accounting is tracked on the ledger.
    *
-   * @warning The returned `ShieldedSendResult` holds the sent and change coins
-   * in plaintext (`nonce`, `color`, `value`). Consuming it in-circuit is safe
-   * (passing `result.change` to `sendImmediateShielded`, for instance). Returning
-   * it from your entry point, writing it to ledger, or passing it to another
-   * contract publishes those coin details, including the amount left over from
-   * the coin that was spent. Note the compiler will NOT stop you: the
-   * `disclose` calls below clear the witness taint, so such a return compiles
-   * with no `disclose` of your own and no marker at the disclosure site. If you
-   * do not need in-circuit change handling, ignore the result. The change is
-   * recoverable off-chain from the transaction's private proving state.
+   * @warning The result holds the sent and change coins in plaintext.
+   * - Returning it from an entry point is safe: it stays with the caller.
+   * - Writing it to the ledger publishes both coins. The compiler will not
+   *   warn, because `_send` already wraps its inputs in `disclose`.
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own

package/multisig/Signer.compact

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