@openzeppelin/compact-contracts 0.3.0-rc.1 → 0.4.0-alpha.2

package/README.md

@@ -1,4 +1,4 @@
-[![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)
+[![Generic badge](https://img.shields.io/badge/Compact%20Compiler-0.34.0-1abc9c.svg)](https://docs.midnight.network/relnotes/compact/)
 [![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.31.0
-0.31.0
+Compactc version: 0.34.0
+0.34.0
 ```
 
 ### Installation
@@ -64,7 +64,7 @@ Import the modules through `./node_modules/@openzeppelin/compact-contracts/...`.
 ```typescript
 // MyContract.compact
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.26.0;
 
 import CompactStandardLibrary;
 import "./node_modules/@openzeppelin/compact-contracts/access/Ownable"
@@ -189,6 +189,16 @@ Compiling 14 circuits:
 Overall progress [====================] 14/14
 ```
 
+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/EcdsaSignerManager`,
+or the `keccak256`-based `crypto/Eip712`.
+`multisig/presets/ShieldedMultiSigV2`, `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,
+listed under [Known issues](CHANGELOG.md#known-issues).
+
 ## Development
 
 OpenZeppelin Contracts for Compact exists thanks to its contributors.

package/access/AccessControl.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-rc.1 (access/AccessControl.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (access/AccessControl.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module AccessControl
@@ -168,7 +168,7 @@ module AccessControl {
   /**
    * @description Returns `true` if `account` has been granted `roleId`.
    *
-   * @circuitInfo k=10, rows=1019
+   * @constraints k=10, rows=1017
    *
    * @param {Bytes<32>} roleId - The role identifier.
    * @param {Either<Bytes<32>, ContractAddress>} account - The account to query.
@@ -206,7 +206,7 @@ module AccessControl {
    * In the case of an external (non-contract) caller, the caller’s identity is
    * derived from the `wit_AccessControlSK` witness as `persistentHash(secretKey)`.
    *
-   * @circuitInfo k=13, rows=2669
+   * @constraints k=13, rows=2660
    *
    * Requirements:
    *
@@ -225,7 +225,7 @@ module AccessControl {
   /**
    * @description Reverts if `account` is missing `roleId`.
    *
-   * @circuitInfo k=10, rows=987
+   * @constraints k=10, rows=997
    *
    * Requirements:
    *
@@ -248,7 +248,7 @@ module AccessControl {
    *
    * To change a role's admin use {_setRoleAdmin}.
    *
-   * @circuitInfo k=9, rows=373
+   * @constraints k=9, rows=371
    *
    * @param {Bytes<32>} roleId - The role identifier.
    * @return {Bytes<32>} roleAdmin - The admin role that controls `roleId`.
@@ -263,7 +263,7 @@ module AccessControl {
   /**
    * @description Grants `roleId` to `account`.
    *
-   * @circuitInfo k=13, rows=3536
+   * @constraints k=13, rows=3527
    *
    * Requirements:
    *
@@ -285,7 +285,7 @@ module AccessControl {
   /**
    * @description Revokes `roleId` from `account`.
    *
-   * @circuitInfo k=13, rows=3466
+   * @constraints k=13, rows=3457
    *
    * Requirements:
    *
@@ -314,7 +314,7 @@ module AccessControl {
    * `persistentHash(secretKey)`. The `callerConfirmation` parameter must match
    * the caller's computed account identifier to prevent accidental renunciation.
    *
-   * @circuitInfo k=13, rows=3322
+   * @constraints k=13, rows=3313
    *
    * Requirements:
    *
@@ -339,7 +339,7 @@ module AccessControl {
   /**
    * @description Sets `adminRole` as `roleId`'s admin role.
    *
-   * @circuitInfo k=10, rows=581
+   * @constraints k=10, rows=579
    *
    * @param {Bytes<32>} roleId - The role identifier.
    * @param {Bytes<32>} adminRole - The admin role identifier.
@@ -353,7 +353,7 @@ module AccessControl {
    * @description Attempts to grant `roleId` to `account` and returns a boolean indicating if `roleId` was granted.
    * Internal circuit without access restriction.
    *
-   * @circuitInfo k=11, rows=1143
+   * @constraints k=11, rows=1141
    *
    * Requirements:
    *
@@ -376,7 +376,7 @@ module AccessControl {
    * @description Attempts to grant `roleId` to `account` and returns a boolean indicating if `roleId` was granted.
    * Internal circuit without access restriction. It does NOT check if the role is granted to a ContractAddress.
    *
-   * @circuitInfo k=11, rows=1142
+   * @constraints k=11, rows=1140
    *
    * @notice External smart contracts cannot call the access control contract at this time, so granting a role to a ContractAddress may
    * render a circuit permanently inaccessible.
@@ -409,7 +409,7 @@ module AccessControl {
    * @description Attempts to revoke `roleId` from `account` and returns a boolean indicating if `roleId` was revoked.
    * Internal circuit without access restriction.
    *
-   * @circuitInfo k=11, rows=1073
+   * @constraints k=11, rows=1071
    *
    * @param {Bytes<32>} roleId - The role identifier.
    * @param {Either<Bytes<32>, ContractAddress>} account - A Bytes<32> or ContractAddress.
@@ -437,7 +437,7 @@ module AccessControl {
    *
    * The result is a 32-byte commitment that uniquely identifies the caller.
    *
-   * @circuitInfo k=13, rows=2294
+   * @constraints k=13, rows=2294
    *
    * @returns {Bytes<32>} accountId - The computed account identifier.
    */

package/access/Ownable.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-rc.1 (access/Ownable.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (access/Ownable.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module Ownable
@@ -94,6 +94,12 @@ module Ownable {
    */
   export ledger _isInitialized: Boolean;
 
+  /**
+   * @description The current owner, canonicalized on write. A `left` holds an
+   * account identifier, stored as supplied and never checked against the secret
+   * key it should derive from; a `right` holds a contract address. The zero
+   * value means ownership has been renounced.
+   */
   export ledger _owner: Either<Bytes<32>, ContractAddress>;
 
   /**
@@ -111,7 +117,7 @@ module Ownable {
    * @description Initializes the contract by setting the `initialOwner`.
    * This must be called in the contract's constructor.
    *
-   * @circuitInfo k=10, rows=626
+   * @constraints k=10, rows=626
    *
    * Requirements:
    *
@@ -158,7 +164,7 @@ module Ownable {
   /**
    * @description Returns the current contract owner.
    *
-   * @circuitInfo k=7, rows=76
+   * @constraints k=7, rows=74
    *
    * Requirements:
    *
@@ -178,7 +184,7 @@ module Ownable {
    * interactions are supported in Compact.
    * This restriction prevents permanently disabling access to a circuit.
    *
-   * @circuitInfo k=13, rows=2959
+   * @constraints k=13, rows=2947
    *
    * Requirements:
    *
@@ -205,7 +211,7 @@ module Ownable {
    * Ownership privileges sent to a contract address may become uncallable.
    * Once contract-to-contract calls are supported, this circuit may be deprecated.
    *
-   * @circuitInfo k=13, rows=2956
+   * @constraints k=13, rows=2944
    *
    * Requirements:
    *
@@ -228,7 +234,7 @@ module Ownable {
    * It will not be possible to call `assertOnlyOwner` circuits anymore.
    * Can only be called by the current owner.
    *
-   * @circuitInfo k=13, rows=2364
+   * @constraints k=13, rows=2353
    *
    * Requirements:
    *
@@ -256,7 +262,7 @@ module Ownable {
    * In the case of an external (non-contract) caller, the caller’s identity is
    * derived from the `wit_OwnableSK` witness as `persistentHash(secretKey)`.
    *
-   * @circuitInfo k=13, rows=2360
+   * @constraints k=13, rows=2349
    *
    * Requirements:
    *
@@ -282,7 +288,7 @@ module Ownable {
    * interactions are supported in Compact.
    * This restriction prevents circuits from being inadvertently locked in contracts.
    *
-   * @circuitInfo k=10, rows=600
+   * @constraints k=10, rows=598
    *
    * Requirements:
    *
@@ -307,7 +313,7 @@ module Ownable {
    * Ownership privileges sent to a contract address may become uncallable.
    * Once contract-to-contract calls are supported, this circuit may be deprecated.
    *
-   * @circuitInfo k=10, rows=597
+   * @constraints k=10, rows=595
    *
    * Requirements:
    *

package/access/ShieldedAccessControl.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-rc.1 (access/ShieldedAccessControl.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (access/ShieldedAccessControl.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module ShieldedAccessControl
@@ -199,6 +199,10 @@ module ShieldedAccessControl {
   /**
    * @ledger _adminRoles
    * @description Mapping from a role identifier to an admin role identifier.
+   * @type {RoleIdentifier} role - The role being administered.
+   * @type {RoleIdentifier} adminRole - The role permitted to grant and revoke it.
+   * @type {Map<role, adminRole>}
+   * @type {Map<RoleIdentifier, RoleIdentifier>} _adminRoles
    */
   export ledger _adminRoles: Map<RoleIdentifier, RoleIdentifier>;
 
@@ -311,6 +315,8 @@ module ShieldedAccessControl {
   /**
    * @description Reverts if caller cannot provide a valid proof of ownership for `role`.
    *
+   * @constraints k=15, rows=16997
+   *
    * Requirements:
    *
    * - caller must prove ownership of `role`.
@@ -337,6 +343,8 @@ module ShieldedAccessControl {
    * caller if the proving environment supplies an invalid Merkle path. This circuit will never return true for an
    * unauthorized caller.
    *
+   * @constraints k=15, rows=16997
+   *
    * Requirements:
    *
    * - caller must not provide valid Merkle tree path for a different `(role, accountId)` pairing.
@@ -392,6 +400,8 @@ module ShieldedAccessControl {
    * limited Merkle tree storage slots. 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
+   *
    * Requirements:
    *
    * - caller must prove they're an admin for `role`.
@@ -434,6 +444,8 @@ module ShieldedAccessControl {
    * but are otherwise benign. A single nullifier invalidates all duplicate commitments.
    * Implementing contracts are responsible for mitigating tree exhaustion risk.
    *
+   * @constraints k=14, rows=12250
+   *
    * Requirements:
    *
    * - The `(role, accountId)` pairing must not be already revoked.
@@ -466,6 +478,8 @@ module ShieldedAccessControl {
    * @warning Outside observers may be able to use timing and pattern analysis to weaken pseudonymity
    * guarantees if renounceRole is used in tandem with other on-chain actions.
    *
+   * @constraints k=14, rows=14440
+   *
    * Requirements:
    *
    * - The caller must provide a valid `accountId` for the role.
@@ -497,6 +511,8 @@ module ShieldedAccessControl {
    * `role`. At this time, proofs of non-membership on values in the Merkle tree LDT are not possible
    * so a `(role, accountId)` pairing that does not exist can still be revoked.
    *
+   * @constraints k=15, rows=27005
+   *
    * Requirements:
    *
    * - caller must prove they're an admin for `role`.
@@ -533,6 +549,8 @@ module ShieldedAccessControl {
    * @warning Exposing this circuit directly in an implementing contract would allow anyone to revoke
    * roles without authorization. It must be wrapped with appropriate access control.
    *
+   * @constraints k=14, rows=10260
+   *
    * Requirements:
    *
    * - The `(role, accountId)` pairing must not be already revoked.
@@ -599,6 +617,8 @@ module ShieldedAccessControl {
    *
    * To change a role's admin use {_setRoleAdmin}.
    *
+   * @constraints k=9, rows=374
+   *
    * Disclosures:
    *
    * - A role identifier.
@@ -621,6 +641,8 @@ module ShieldedAccessControl {
    * @warning Exposing this circuit directly in an implementing contract would allow anyone to assign
    * arbitrary admin roles without authorization. It must be wrapped with appropriate access control.
    *
+   * @constraints k=10, rows=581
+   *
    * Disclosures:
    *
    * - The role identifier
@@ -707,6 +729,8 @@ module ShieldedAccessControl {
    * - `commitmentDomain`: Domain separator `"ShieldedAccessControl:commitment"` (padded to 32 bytes) to prevent
    * hash collisions when extending the module or using similar commitment schemes.
    *
+   * @constraints k=13, rows=6404
+   *
    * @param {RoleIdentifier} role - The role identifier.
    * @param {AccountIdentifier} accountId - The unique identifier of the account.
    *

package/access/ZOwnablePK.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-rc.1 (access/ZOwnablePK.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (access/ZOwnablePK.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module ZOwnablePK
@@ -99,7 +99,7 @@ module ZOwnablePK {
    * @warning The `ownerId` must be calculated prior to contract deployment using the SHA256 hashing algorithm.
    * Using any other algorithm will result in a permanent loss of contract access.
    *
-   * @circuitInfo k=14, rows=14933
+   * @constraints k=14, rows=14933
    *
    * Requirements:
    *
@@ -150,7 +150,7 @@ module ZOwnablePK {
    * @description Returns the current commitment representing the contract owner.
    * The full commitment is: `SHA256(SHA256(pk, nonce), instanceSalt, counter, domain)`.
    *
-   * @circuitInfo k=10, rows=57
+   * @constraints k=6, rows=48
    *
    * Requirements:
    *
@@ -167,7 +167,7 @@ module ZOwnablePK {
    * @description Transfers ownership to `newOwnerId`.
    * `newOwnerId` must be precalculated and given to the current owner off chain.
    *
-   * @circuitInfo k=16, rows=39240
+   * @constraints k=15, rows=17023
    *
    * Requirements:
    *
@@ -191,7 +191,7 @@ module ZOwnablePK {
    * It will not be possible to call `assertOnlyOwner` circuits anymore.
    * Can only be called by the current owner.
    *
-   * @circuitInfo k=15, rows=24442
+   * @constraints k=14, rows=10579
    *
    * Requirements:
    *
@@ -212,7 +212,7 @@ module ZOwnablePK {
    * the stored owner commitment.
    * Use this to only allow the owner to call specific circuits.
    *
-   * @circuitInfo k=15, rows=24437
+   * @constraints k=14, rows=10577
    *
    * Requirements:
    *
@@ -257,7 +257,7 @@ module ZOwnablePK {
    * - `domain`: Domain separator `"ZOwnablePK:shield:"` (padded to 32 bytes) to prevent
    * hash collisions when extending the module or using similar commitment schemes.
    *
-   * @circuitInfo k=14, rows=14853
+   * @constraints k=13, rows=6544
    *
    * Requirements:
    *
@@ -320,7 +320,7 @@ module ZOwnablePK {
    * @description Transfers ownership to owner id `newOwnerId` without
    * enforcing permission checks on the caller.
    *
-   * @circuitInfo k=14, rows=14823
+   * @constraints k=13, rows=6460
    *
    * Requirements:
    *

package/crypto/EcdhMask.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-rc.1 (crypto/EcdhMask.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (crypto/EcdhMask.compact)
 
-pragma language_version >= 0.23.0;
+pragma language_version >= 0.26.0;
 
 /**
  * @module EcdhMask
@@ -142,10 +142,10 @@ module EcdhMask {
   export pure circuit encrypt(
                         recipientPk: JubjubPoint,
                         value: Uint<128>,
-                        e: Field,
+                        e: JubjubScalar,
                         domain: Bytes<32>
                         ): Ciphertext {
-    const identity = ecMulGenerator(0 as Field);
+    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`
@@ -169,7 +169,7 @@ module EcdhMask {
    * @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 {
+  export pure circuit decrypt(ciphertext: Ciphertext, ekScalar: JubjubScalar, domain: Bytes<32>): Field {
     const sShared = ecMul(ciphertext.ephemeralPk, ekScalar);
     const mask = kdf(sShared, domain);
     return ciphertext.ct - mask;

package/crypto/Ecdsa.compact

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (crypto/Ecdsa.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module Ecdsa
+ * @description The low-s rule for secp256k1 ECDSA signatures.
+ *
+ * `secp256k1EcdsaVerify` accepts both `(r, s)` and `(r, n - s)`, so every valid
+ * signature has a second valid encoding that anyone can derive without the
+ * signing key. Its own documentation leaves the low-s constraint to the caller.
+ * This module is that constraint: reject `s > n / 2` and each signature has one
+ * encoding, which is what replay sets, nullifiers, and signature-derived
+ * identifiers rely on.
+ */
+module Ecdsa {
+  import CompactStandardLibrary;
+
+  /**
+   * @description Returns whether `s` is canonical, i.e. `s <= n / 2` where `n`
+   * is the secp256k1 group order.
+   *
+   * @constraints k=13, rows=5125 (zkir-v3)
+   *
+   * @param {Secp256k1Scalar} s - The `s` component of a signature.
+   * @returns {Boolean} True if `s` is in the low half.
+   */
+  export pure circuit isLowS(s: Secp256k1Scalar): Boolean {
+    const sBytes = (s as Bytes<32>) as Vector<32, Uint<8>>;
+    return fold(compareByteLe, true, sBytes, SECP256K1_HALF_ORDER_LE());
+  }
+
+  /**
+   * @description Fold callback over one little-endian byte pair. A differing
+   * pair overrides the running result, so the accumulator ends up holding the
+   * comparison at the most significant byte where `s` and `n / 2` differ. All
+   * pairs equal leaves the seed untouched, which is what makes the comparison
+   * inclusive.
+   *
+   * @param {Boolean} isLow - Result from the less significant bytes.
+   * @param {Uint<8>} sByte - Byte of `s`.
+   * @param {Uint<8>} halfByte - Byte of `n / 2`.
+   * @returns {Boolean} Updated result.
+   */
+  pure circuit compareByteLe(
+    isLow: Boolean,
+    sByte: Uint<8>,
+    halfByte: Uint<8>
+  ): Boolean {
+    return sByte == halfByte ? isLow : sByte < halfByte;
+  }
+
+  /**
+   * @description `n / 2` as little-endian bytes, matching the byte order of
+   * `Secp256k1Scalar as Bytes<32>`.
+   *
+   * @returns {Vector<32, Uint<8>>} The bytes of `n / 2`, least significant first.
+   */
+  pure circuit SECP256K1_HALF_ORDER_LE(): Vector<32, Uint<8>> {
+    // 0x7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b20a0
+    return [
+      160, 32, 27, 104, 70, 47, 233, 223,
+      29, 80, 164, 87, 115, 110, 87, 93,
+      255, 255, 255, 255, 255, 255, 255, 255,
+      255, 255, 255, 255, 255, 255, 255, 127
+    ];
+  }
+
+  // ─── Verification ───────────────────────────────────────────────────────────
+
+  /**
+   * @description Rejects a signature in the high half.
+   *
+   * @constraints k=13, rows=5156 (zkir-v3)
+   *
+   * Requirements:
+   *
+   * - `sig.s` must satisfy `s <= n / 2`.
+   *
+   * @param {Secp256k1EcdsaSignature} sig - The signature to check.
+   * @returns {[]} Empty tuple.
+   */
+  export pure circuit assertLowS(sig: Secp256k1EcdsaSignature): [] {
+    assert(isLowS(sig.s), "Ecdsa: high-s signature");
+  }
+
+  /**
+   * @description Verifies `sig` over `msgHash` under `pk`, accepting only the
+   * low-s encoding. Reports the result instead of asserting, so a caller can
+   * fold it into a count or a threshold.
+   *
+   * @constraints k=16, rows=34056 (zkir-v3)
+   *
+   * @param {Bytes<32>} msgHash - The digest that was signed.
+   * @param {Secp256k1EcdsaSignature} sig - The signature over `msgHash`.
+   * @param {Secp256k1Point} pk - The signer's public key.
+   * @returns {Boolean} True if the signature is valid and canonical.
+   */
+  export pure circuit secp256k1EcdsaVerifyLowS(
+    msgHash: Bytes<32>,
+    sig: Secp256k1EcdsaSignature,
+    pk: Secp256k1Point
+  ): Boolean {
+    // TODO: inline into the return once a guarded stdlib verify compiles.
+    // Short-circuiting `&&` puts it behind a guard, which trips an internal
+    // error in the compiler's missing-guard-workarounds pass.
+    const verified = secp256k1EcdsaVerify(msgHash, sig, pk);
+    return isLowS(sig.s) && verified;
+  }
+}