@openzeppelin/compact-contracts 0.4.0-alpha.1 → 0.4.0-alpha.3

package/README.md

@@ -189,11 +189,15 @@ 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 imports the secp256k1-based modules
-(`crypto/Ecdsa`, `multisig/EcdsaSignerManager`, `ShieldedMultiSigV2`,
-`ShieldedMultiSigV3`). Compiling the other modules under v3 currently hits
-upstream blockers, listed under [Known issues](CHANGELOG.md#known-issues).
+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
 

package/access/AccessControl.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (access/AccessControl.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (access/AccessControl.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -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,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (access/Ownable.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (access/Ownable.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -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,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (access/ShieldedAccessControl.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (access/ShieldedAccessControl.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -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,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (access/ZOwnablePK.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (access/ZOwnablePK.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -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,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (crypto/EcdhMask.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (crypto/EcdhMask.compact)
 
 pragma language_version >= 0.26.0;
 

package/crypto/Ecdsa.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (crypto/Ecdsa.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (crypto/Ecdsa.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -21,7 +21,7 @@ module Ecdsa {
    * @description Returns whether `s` is canonical, i.e. `s <= n / 2` where `n`
    * is the secp256k1 group order.
    *
-   * @circuitInfo k=13, rows=5125
+   * @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.
@@ -72,7 +72,7 @@ module Ecdsa {
   /**
    * @description Rejects a signature in the high half.
    *
-   * @circuitInfo k=13, rows=5156
+   * @constraints k=13, rows=5156 (zkir-v3)
    *
    * Requirements:
    *
@@ -90,7 +90,7 @@ module Ecdsa {
    * low-s encoding. Reports the result instead of asserting, so a caller can
    * fold it into a count or a threshold.
    *
-   * @circuitInfo k=16, rows=34056
+   * @constraints k=16, rows=34056 (zkir-v3)
    *
    * @param {Bytes<32>} msgHash - The digest that was signed.
    * @param {Secp256k1EcdsaSignature} sig - The signature over `msgHash`.

package/crypto/Eip712.compact

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (crypto/Eip712.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module Eip712
+ * @description The EIP-712 typed-data envelope, for verifying signatures
+ * produced by Ethereum signing infrastructure.
+ *
+ * A typed-data signature covers `keccak256(0x1901 || domainSeparator ||
+ * structHash)`. The domain separator binds the signature to one application,
+ * so a signature obtained for any other domain cannot be replayed here — the
+ * property `personal_sign` does not provide, since it signs an opaque hash
+ * with no application binding.
+ *
+ * Build `structHash` from EVM ABI words (see `utils/EvmAbi`), with the
+ * operation's type hash as the first word.
+ *
+ * @notice The domain is `(name, version, salt)`. `chainId` and
+ * `verifyingContract` are omitted, which EIP-712 permits — every domain field
+ * is optional. They are omitted because neither is expressible: a Midnight
+ * contract address is 32 bytes and does not fit `verifyingContract`'s
+ * `address` type, and no network identifier is available in-circuit.
+ *
+ * On an EVM chain `verifyingContract` is what makes a domain identify one
+ * deployment rather than one application. Without it, a consumer has to get
+ * that binding elsewhere. There are two places to put it, and they are not
+ * equivalent:
+ *
+ * - As a field of the operation struct, holding the contract's own address.
+ *   This is the stronger option and the one to reach for by default: a
+ *   Midnight address is randomised at deployment and cannot be predicted, so
+ *   no two instances share one, and a signature for one deployment cannot
+ *   authorise another.
+ * - As `salt`, a per-deployment value in the domain. This is weaker, because
+ *   it separates domains rather than messages. It is worth adding when the
+ *   signer gates on domains but cannot read struct fields, since that is the
+ *   only level at which it is visible.
+ *
+ * A consumer doing neither has one domain shared by every deployment of the
+ * contract, and nothing distinguishing them.
+ *
+ * @notice Requires ZKIR v3: `keccak256` is unavailable on the v2 backend.
+ */
+module Eip712 {
+  import CompactStandardLibrary;
+
+  /**
+   * @description The 66-byte typed-data preimage: the two-byte prefix, the
+   * domain separator, then the struct hash. `Bytes<n>` is emitted at exactly
+   * `n` bytes, so this hashes as the concatenation an EVM signer produces.
+   */
+  struct TypedDataPreimage {
+    prefixBytes: Bytes<2>,
+    domainSeparator: Bytes<32>,
+    structHash: Bytes<32>
+  }
+
+  /**
+   * @description The four words of the domain separator's preimage.
+   */
+  struct DomainFields {
+    typeHash: Bytes<32>,
+    hashedName: Bytes<32>,
+    hashedVersion: Bytes<32>,
+    salt: Bytes<32>
+  }
+
+  /**
+   * @description `0x1901`, the EIP-191 version byte `0x01` behind the `0x19`
+   * marker, which is how EIP-712 identifies itself.
+   *
+   * @dev Written as byte values because the bytes are not printable. The
+   * version byte is what keeps a typed-data digest from colliding with a
+   * `personal_sign` one (version `0x45`) or an intended-validator one (`0x00`).
+   *
+   * @returns {Bytes<2>} The typed-data prefix.
+   */
+  pure circuit TYPED_DATA_PREFIX(): Bytes<2> {
+    const raw: Vector<2, Uint<8>> = [25, 1];
+
+    return raw as Bytes<2>;
+  }
+
+  /**
+   * @description `keccak256("EIP712Domain(string name,string version,bytes32 salt)")`.
+   *
+   * @dev Written as a literal word. `compactc` emits a full keccak
+   * permutation even for a constant argument, so hashing the type string
+   * in-circuit would roughly double `domainSeparator`. The spec checks this
+   * word against the type string above.
+   *
+   * The string must match the domain's field set exactly: a difference of one
+   * character yields a different separator and every signature fails.
+   *
+   * @returns {Bytes<32>} The domain type hash.
+   */
+  pure circuit DOMAIN_TYPEHASH(): Bytes<32> {
+    // keccak256("EIP712Domain(string name,string version,bytes32 salt)")
+    // = 0x599a80fcaa47b95e2323ab4d34d34e0cc9feda4b843edafcc30c7bdf60ea15bf
+    const typeHash: Vector<32, Uint<8>> = [
+      0x59, 0x9a, 0x80, 0xfc, 0xaa, 0x47, 0xb9, 0x5e,
+      0x23, 0x23, 0xab, 0x4d, 0x34, 0xd3, 0x4e, 0x0c,
+      0xc9, 0xfe, 0xda, 0x4b, 0x84, 0x3e, 0xda, 0xfc,
+      0xc3, 0x0c, 0x7b, 0xdf, 0x60, 0xea, 0x15, 0xbf
+    ];
+
+    return typeHash as Bytes<32>;
+  }
+
+  /**
+   * @description Computes the domain separator for `(name, version, salt)`.
+   *
+   * EIP-712 encodes a `string` field as the keccak hash of its UTF-8 bytes,
+   * so the name and version arrive already hashed. Compact has no dynamic
+   * types, so a consumer hashes its own fixed-length literals.
+   *
+   * @constraints k=14, rows=4561 (zkir-v3)
+   *
+   * @param {Bytes<32>} hashedName - `keccak256(bytes(name))`.
+   * @param {Bytes<32>} hashedVersion - `keccak256(bytes(version))`.
+   * @param {Bytes<32>} salt - Per-deployment, per-network random value.
+   * @returns {Bytes<32>} The domain separator.
+   */
+  export pure circuit domainSeparator(
+    hashedName: Bytes<32>,
+    hashedVersion: Bytes<32>,
+    salt: Bytes<32>
+  ): Bytes<32> {
+    return keccak256<DomainFields>(DomainFields {
+      typeHash: DOMAIN_TYPEHASH(),
+      hashedName: hashedName,
+      hashedVersion: hashedVersion,
+      salt: salt
+    });
+  }
+
+  /**
+   * @description Wraps a struct hash in the typed-data envelope, yielding the
+   * digest an EVM signer actually signs.
+   *
+   * @constraints k=14, rows=4463 (zkir-v3)
+   *
+   * Requirements:
+   *
+   * - `separator` must be non-zero, which an initialized domain always is.
+   *
+   * @param {Bytes<32>} separator - The domain separator, fixed at deployment.
+   * @param {Bytes<32>} structHash - `keccak256(typeHash || the operation's ABI words)`.
+   * @returns {Bytes<32>} The digest to verify signatures against.
+   */
+  export pure circuit hashTypedData(
+    separator: Bytes<32>,
+    structHash: Bytes<32>
+  ): Bytes<32> {
+    // A zero separator is what an uninitialized ledger cell reads as, and a
+    // digest built from one still verifies signatures. Fail closed rather than
+    // authorize an operation under an unset domain.
+    assert(separator != pad(32, ""), "Eip712: domain separator not set");
+
+    return keccak256<TypedDataPreimage>(TypedDataPreimage {
+      prefixBytes: TYPED_DATA_PREFIX(),
+      domainSeparator: separator,
+      structHash: structHash
+    });
+  }
+}

package/crypto/ElGamal.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (crypto/ElGamal.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (crypto/ElGamal.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -38,6 +38,13 @@ pragma language_version >= 0.26.0;
  * cast reduces modulo the subgroup order, so casting at a call site would
  * silently accept an out-of-range scalar the typed parameter rejects.
  *
+ * @dev Domain separation. `persistentHash<Vector<N, Bytes<32>>>` is NOT
+ * domain-separating on its own. Two circuits hashing the same arity and
+ * element type share one hash domain, and the hash cannot tell which slot was
+ * "meant" as a tag. `secretToScalar` therefore prefixes a fixed constant, and
+ * that constant is placed FIRST so no call to `expandRandomness` (whose two
+ * slots are both caller-supplied) can reproduce the tuple by ordinary use.
+ *
  * @dev TRUST ASSUMPTION — subgroup membership. This is the module's most
  * load-bearing assumption. Every `JubjubPoint` reaching a curve operation is
  * assumed to be in the Jubjub prime-order subgroup, including points supplied by
@@ -105,11 +112,34 @@ module ElGamal {
    * @description Maps a 32-byte secret to a valid Jubjub scalar. See the
    * module-level hash-to-scalar note for why `degradeToTransient` is required.
    *
+   * @dev Domain separation here is load-bearing, not cosmetic. This output is
+   * the private key protecting every ciphertext held under an account. Public
+   * account identifiers derived from `Utils.computeAccountId`, for example,
+   * are computed as `persistentHash([secretKey])`, and that identifier
+   * is stored in the clear as a ledger map key. Untagged, this circuit
+   * would compute that same hash, so a secret used in both roles would
+   * have its encryption key recoverable from a published identifier by applying
+   * `degradeToTransient`. The tag makes the two derivations unrelated, so a
+   * wallet MAY safely derive its account secret and its encryption secret from
+   * common key material.
+   *
+   * @dev The tag is FIRST, deliberately. `expandRandomness` hashes
+   * `[seed, tag]` with both slots caller-supplied, so tagging this circuit as
+   * `[secret, tag]` would make `secretToScalar(x)` identical to
+   * `expandRandomness(x, <this tag>)` reachable by passing this domain string
+   * to the parameter that exists to receive domain strings. Leading with the
+   * tag means reproducing this output through `expandRandomness` would require
+   * passing the domain constant as the *seed*. Do not normalise the orderings.
+   *
    * @param secret - The 32-byte secret to map.
    * @return A valid Jubjub scalar.
    */
   export pure circuit secretToScalar(secret: Bytes<32>): JubjubScalar {
-    return degradeToTransient(persistentHash<Vector<1, Bytes<32>>>([secret])) as JubjubScalar;
+    return degradeToTransient(
+             persistentHash<Vector<2, Bytes<32>>>(
+               [pad(32, "ElGamal:secretToScalar"), secret]
+             )
+           ) as JubjubScalar;
   }
 
   /**
@@ -419,6 +449,17 @@ module ElGamal {
    * wrong plaintext fails the decryption check. Lifted special case of
    * `assertDecryptsToPoint` with the message point `g^claimedValue`.
    *
+   * @notice `claimedValue` is the widest `Uint` Compact offers, so this parameter
+   * never bounds a caller. A narrower value costs proportionally fewer rows: the
+   * range constraint belongs to where the value is declared, not to this
+   * signature.
+   *
+   * @warning The claim domain must stay below the Jubjub subgroup order `l`:
+   * verification compares `g^claimedValue`, so two claims congruent mod `l` are
+   * indistinguishable. `Uint<248>` clears `l` (~2^251.86) by under 4 bits, and
+   * that width is set by Compact's cap rather than by this bound. 251 is the
+   * widest sound `Uint` if the cap ever rises.
+   *
    * Requirements:
    *
    * - `ek` is the secret for `pk`.
@@ -433,7 +474,7 @@ module ElGamal {
                    ct: Ciphertext,
                    pk: JubjubPoint,
                    ek: Bytes<32>,
-                   claimedValue: Uint<128>
+                   claimedValue: Uint<248>
                    ): [] {
     assertDecryptsToPoint(ct, pk, ek, ecMulGenerator(claimedValue as JubjubScalar));
   }