@openzeppelin/compact-contracts 0.2.0 → 0.3.0-alpha.1

package/README.md

@@ -1,4 +1,4 @@
-[![Generic badge](https://img.shields.io/badge/Compact%20Compiler-0.29.0-1abc9c.svg)](https://docs.midnight.network/relnotes/compact/minokawa-0-18-26-0)
+[![Generic badge](https://img.shields.io/badge/Compact%20Compiler-0.31.0-1abc9c.svg)](https://docs.midnight.network/relnotes/compact/minokawa-0-18-26-0)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
 
 This project is built on the Midnight Network.
@@ -37,8 +37,8 @@ Follow Midnight's [Compact Developer Tools installation guide](https://docs.midn
 ```bash
 $ compact compile --version
 
-Compactc version: 0.29.0
-0.29.0
+Compactc version: 0.31.0
+0.31.0
 ```
 
 ### Installation
@@ -214,7 +214,7 @@ git clone git@github.com:OpenZeppelin/compact-contracts.git
 ```bash
 nvm install && \
 yarn && \
-yarn compact
+yarn compile
 ```
 
 ### Run tests
@@ -226,8 +226,8 @@ yarn test
 ### Check/apply Biome formatter
 
 ```bash
-yarn fmt-and-lint
-yarn fmt-and-lint:fix
+yarn lint
+yarn lint:fix
 ```
 
 ### Advanced
@@ -235,8 +235,8 @@ yarn fmt-and-lint:fix
 #### Targeted compilation
 
 ```bash
-yarn compact:access
-yarn compact:archive
+yarn compile:access
+yarn compile:archive
 ...
 ```
 
@@ -246,10 +246,10 @@ ZK key generation is slow and usually unnecessary during development.
 
 ```bash
 # Full compilation with skip-zk (use environment variable)
-SKIP_ZK=true yarn compact
+SKIP_ZK=true yarn compile
 
 # Access compilation with skip-zk (this compiles security first as a dependency)
-SKIP_ZK=true yarn compact:access
+SKIP_ZK=true yarn compile:access
 ```
 
 #### Clean environment

package/access/AccessControl.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (access/AccessControl.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (access/AccessControl.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module AccessControl
@@ -442,38 +442,6 @@ module AccessControl {
    * @returns {Bytes<32>} accountId - The computed account identifier.
    */
   circuit _computeAccountId(): Bytes<32> {
-    return computeAccountId(wit_AccessControlSK());
-  }
-
-  /**
-   * @description Computes an account identifier without on-chain state, allowing a user to derive
-   * their identity commitment before submitting it in a grant or revoke operation.
-   * This is the off-chain counterpart to {_computeAccountId} and produces an identical result
-   * given the same inputs.
-   *
-   * @warning OpSec: The `secretKey` parameter is a sensitive secret. Mishandling it can
-   * permanently compromise the privacy guarantees of this system:
-   *
-   * - **Never log or persist** the `secretKey` in plaintext — avoid browser devtools,
-   *   application logs, analytics pipelines, or any observable side-channel.
-   * - **Store offline or in secure enclaves** — hardware security modules (HSMs),
-   *   air-gapped devices, or encrypted vaults are strongly preferred over hot storage.
-   * - **Use cryptographically secure randomness** — generate keys with `crypto.getRandomValues()`
-   *   or equivalent; weak or predictable keys can be brute-forced to reveal your identity.
-   * - **Treat key loss as identity loss** — a lost key cannot be recovered. Back up
-   *   keys securely before using them in role commitments.
-   * - **Avoid calling this circuit in untrusted environments** — executing this in an
-   *   unverified browser extension, compromised runtime, or shared machine may expose
-   *   the key to a malicious observer.
-   *
-   * ## ID Derivation
-   * `accountId = persistentHash(secretKey)`
-   *
-   * @param {Bytes<32>} secretKey - A 32-byte cryptographically secure random value.
-   *
-   * @returns {Bytes<32>} accountId - The computed account identifier.
-   */
-  export pure circuit computeAccountId(secretKey: Bytes<32>): Bytes<32> {
-    return persistentHash<Vector<1, Bytes<32>>>([secretKey]);
+    return Utils_computeAccountId(wit_AccessControlSK());
   }
 }

package/access/Ownable.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (access/Ownable.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (access/Ownable.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module Ownable
@@ -125,7 +125,7 @@ module Ownable {
   export circuit initialize(initialOwner: Either<Bytes<32>, ContractAddress>): [] {
     assertNotInitialized();
     _isInitialized = true;
-    assert(!_isTargetZero(initialOwner), "Ownable: invalid initial owner");
+    assert(!Utils_isTargetZero(initialOwner), "Ownable: invalid initial owner");
     _transferOwnership(initialOwner);
   }
 
@@ -219,7 +219,7 @@ module Ownable {
   export circuit _unsafeTransferOwnership(newOwner: Either<Bytes<32>, ContractAddress>): [] {
     assertInitialized();
     assertOnlyOwner();
-    assert(!_isTargetZero(newOwner), "Ownable: invalid new owner");
+    assert(!Utils_isTargetZero(newOwner), "Ownable: invalid new owner");
     _unsafeUncheckedTransferOwnership(newOwner);
   }
 
@@ -335,52 +335,6 @@ module Ownable {
    * @returns {Bytes<32>} accountId - The computed account identifier.
    */
   circuit _computeAccountId(): Bytes<32> {
-    return computeAccountId(wit_OwnableSK());
-  }
-
-  /**
-   * @description Computes an account identifier without on-chain state, allowing a user to derive
-   * their identity commitment before submitting it in an ownership transfer.
-   * This is the off-chain counterpart to {_computeAccountId} and produces an identical result
-   * given the same inputs.
-   *
-   * @warning OpSec: The `secretKey` parameter is a sensitive secret. Mishandling it can
-   * permanently compromise the security of this system:
-   *
-   * - **Never log or persist** the `secretKey` in plaintext — avoid browser devtools,
-   *   application logs, analytics pipelines, or any observable side-channel.
-   * - **Store offline or in secure enclaves** — hardware security modules (HSMs),
-   *   air-gapped devices, or encrypted vaults are strongly preferred over hot storage.
-   * - **Use cryptographically secure randomness** — generate keys with `crypto.getRandomValues()`
-   *   or equivalent; weak or predictable keys can be brute-forced to reveal your identity.
-   * - **Treat key loss as identity loss** — a lost key cannot be recovered.
-   * - **Avoid calling this circuit in untrusted environments** — executing this in an
-   *   unverified browser extension, compromised runtime, or shared machine may expose
-   *   the key to a malicious observer.
-   *
-   * ## ID Derivation
-   * `accountId = persistentHash(secretKey)`
-   *
-   * @param {Bytes<32>} secretKey - A 32-byte cryptographically secure random value.
-   *
-   * @returns {Bytes<32>} accountId - The computed account identifier.
-   */
-  export pure circuit computeAccountId(secretKey: Bytes<32>): Bytes<32> {
-    return persistentHash<Vector<1, Bytes<32>>>([secretKey]);
-  }
-
-  /**
-   * @description Returns `true` if `target`'s active branch (as indicated by `is_left`)
-   * holds the zero value.
-   *
-   * @param {Either<Bytes<32>, ContractAddress>} target - The value to check.
-   * @returns {Boolean} - `true` if the active branch is zero, `false` otherwise.
-   */
-  circuit _isTargetZero(target: Either<Bytes<32>, ContractAddress>): Boolean {
-    if (target.is_left) {
-      return target.left == default<Bytes<32>>;
-    } else {
-      return target.right == default<ContractAddress>;
-    }
+    return Utils_computeAccountId(wit_OwnableSK());
   }
 }

package/access/ShieldedAccessControl.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (access/ShieldedAccessControl.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (access/ShieldedAccessControl.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module ShieldedAccessControl

package/access/ZOwnablePK.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (access/ZOwnablePK.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (access/ZOwnablePK.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module ZOwnablePK

package/crypto/EcdhMask.compact

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (crypto/EcdhMask.compact)
+
+pragma language_version >= 0.23.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.
+ *
+ * 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.
+ *
+ * @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: 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).
+ *
+ * Secrecy: `recipientPk` is public, so anyone who learns `e` recomputes
+ * `S = recipientPk^e`, hence the mask, and opens the ciphertext. 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 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 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
+ * in-circuit from a value the same circuit commits to elsewhere (a producer
+ * cannot desync the two) and is immutable once written (no in-transit attacker).
+ * A corrupted ciphertext could only fail the recipient's own later proof, never
+ * 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
+ * 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.
+ *
+ * @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-
+ * ElGamal balance ciphertexts, as the confidential token does. This joint use is
+ * 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.
+ *
+ * @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
+ * circuit for wallet/off-chain use (recovering a received value needs no proof);
+ * the on-chain path only ever calls `encrypt`.
+ */
+module EcdhMask {
+  import CompactStandardLibrary;
+
+  /**
+   * @description An ECDH one-time-pad ciphertext: the ephemeral public key and
+   * the field-masked value.
+   */
+  export struct Ciphertext {
+    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])
+    );
+  }
+
+  /**
+   * @description Encrypts `value` to `recipientPk` under ephemeral scalar `e`.
+   *
+   * @notice `e` MUST be fresh per call (see the module freshness precondition).
+   *
+   * 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 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>,
+                        e: Field,
+                        domain: Bytes<32>
+                        ): Ciphertext {
+    const identity = ecMulGenerator(0 as Field);
+    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 };
+  }
+
+  /**
+   * @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).
+   *
+   * @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`).
+   */
+  export pure circuit decrypt(ciphertext: Ciphertext, ekScalar: Field, domain: Bytes<32>): Field {
+    const sShared = ecMul(ciphertext.ephemeralPk, ekScalar);
+    const mask = kdf(sShared, domain);
+    return ciphertext.ct - mask;
+  }
+}