@openzeppelin/compact-contracts 0.4.0 → 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.4.0 (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.4.0 (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
@@ -117,6 +116,8 @@ module Ownable {
    * @description Initializes the contract by setting the `initialOwner`.
    * This must be called in the contract's constructor.
    *
+   * @constraints k=10, rows=626
+   *
    * Requirements:
    *
    * - Contract is not already initialized.
@@ -178,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
@@ -204,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
    *
@@ -246,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>
     };
@@ -282,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
@@ -306,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.4.0 (access/ShieldedAccessControl.compact)
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (access/ShieldedAccessControl.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -140,8 +140,14 @@ pragma language_version >= 0.26.0;
  *   between roles should use separate keys per role and accept the additional key management overhead.
  *   In the event of key compromise, the user should coordinate with admins to revoke all roles
  *   under the compromised `accountId` and re-grant under a new identity.
- * - A `(role, accountId)` pairing can only be revoked after it was granted, so the nullifier
- *   set holds at most one entry per granted pairing.
+ * - Admins can revoke `(role, accountId)` pairings that were never granted, since on-chain
+ *   non-membership proofs are not available for the Merkle tree. This permanently burns the
+ *   nullifier for that pairing, blocking any future grant. Admin trust is a fundamental
+ *   assumption of this system. Off-chain validation should confirm that a pairing was actually
+ *   granted before submitting a revocation transaction.
+ * - `renounceRole` allows burning nullifiers for roles the caller does not currently hold,
+ *   provided they possess the correct `secretKey`. This requires knowledge of the secret key,
+ *   at which point the `accountId` should be considered fully compromised regardless.
  * - The Merkle tree capacity of 2^20 leaf slots is a permanent, irrecoverable resource.
  *   There is no mechanism to reclaim slots after revocation, no upgrade path, and no emergency
  *   recovery. Once exhausted, the contract is permanently unable to grant new roles. Deployers
@@ -206,8 +212,7 @@ module ShieldedAccessControl {
 
   /**
    * @description Nullifiers of every pairing ever granted. Makes a repeated grant a no-op so
-   * one pairing can never consume more than one `_operatorRoles` slot, and gates revocation
-   * so a nullifier can only exist for a granted pairing.
+   * one pairing can never consume more than one `_operatorRoles` slot.
    * @type {Set<RoleNullifier>} _grantedRoleNullifiers
    */
   export ledger _grantedRoleNullifiers: Set<RoleNullifier>;
@@ -469,17 +474,15 @@ module ShieldedAccessControl {
    * @notice Roles are often managed via {grantRole} and {revokeRole}: this circuit's
    * purpose is to provide a mechanism for accounts to lose their privileges
    * if they are compromised (such as when a trusted device is misplaced).
-   * Consumers with no need for self-revocation should not export this circuit.
    *
    * @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=14442
+   * @constraints k=14, rows=14440
    *
    * Requirements:
    *
    * - The caller must provide a valid `accountId` for the role.
-   * - The `(role, accountId)` pairing must have been granted.
    * - The `(role, accountId)` pairing must not be already revoked.
    * - Contract is initialized.
    *
@@ -505,15 +508,15 @@ module ShieldedAccessControl {
   /**
    * @description Permanently revokes `role` from `accountId` by inserting a role nullifier into the
    * `_roleCommitmentNullifiers` set. Once revoked, a new `accountId` must be generated to be re-authorized for
-   * `role`.
+   * `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=27007
+   * @constraints k=15, rows=27005
    *
    * Requirements:
    *
    * - caller must prove they're an admin for `role`.
    * - caller must not provide valid Merkle tree path for a different `(role, accountId)` pairing.
-   * - The `(role, accountId)` pairing must have been granted.
    * - The `(role, accountId)` pairing must not be already revoked.
    * - Contract is initialized.
    *
@@ -538,18 +541,18 @@ module ShieldedAccessControl {
   /**
    * @description Permanently revokes `role` from `accountId` by inserting a role nullifier into the
    * `_roleCommitmentNullifiers` set. Once revoked, a new `accountId` must be generated to be re-authorized for
-   * `role`.
+   * `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.
    *
    * Internal circuit without access restriction.
    *
    * @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=10262
+   * @constraints k=14, rows=10260
    *
    * Requirements:
    *
-   * - The `(role, accountId)` pairing must have been granted.
    * - The `(role, accountId)` pairing must not be already revoked.
    * - Contract is initialized.
    *
@@ -571,8 +574,8 @@ module ShieldedAccessControl {
    * @description Core business logic for the grant/revoke role circuits. Asserts that the
    * `(role, accountId)` pairing has not already been revoked. On success, dispatches on
    * `updateType`: a `Grant` inserts the role commitment into `_operatorRoles` unless the
-   * nullifier is already in `_grantedRoleNullifiers`, and a `Revoke` asserts the nullifier
-   * is in `_grantedRoleNullifiers` before inserting it into `_roleCommitmentNullifiers`.
+   * nullifier is already in `_grantedRoleNullifiers`, and a `Revoke` inserts the nullifier
+   * into `_roleCommitmentNullifiers`.
    *
    * Disclosures:
    *
@@ -600,14 +603,12 @@ module ShieldedAccessControl {
     const isRevoked = _roleCommitmentNullifiers.member(disclose(roleNullifier));
     assert(!isRevoked, "ShieldedAccessControl: role is already revoked");
 
-    const isGranted = _grantedRoleNullifiers.member(disclose(roleNullifier));
     if (updateType == UpdateType.Grant) {
-      if (!isGranted) {
+      if (!_grantedRoleNullifiers.member(disclose(roleNullifier))) {
         _grantedRoleNullifiers.insert(disclose(roleNullifier));
         _operatorRoles.insert(disclose(roleCommitment));
       }
     } else {
-      assert(isGranted, "ShieldedAccessControl: role was never granted");
       _roleCommitmentNullifiers.insert(disclose(roleNullifier));
     }
   }

package/access/ZOwnablePK.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0 (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:
@@ -106,6 +106,8 @@ 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.
    *
+   * @constraints k=13, rows=6765
+   *
    * Requirements:
    *
    * - Contract is not initialized.

package/crypto/Ecdh.compact

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.5.0-alpha.2 (crypto/Ecdh.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @module Ecdh
+ * @description Stateless Diffie-Hellman key agreement over Jubjub. Splits into
+ * the two halves of one exchange: `deriveShared` runs the sender side and
+ * returns the ephemeral public key to publish alongside the shared secret, and
+ * `recoverShared` runs the recipient side from that published point. The module
+ * agrees on a point and nothing more: deriving keys, masks or nonces from it
+ * belongs to the consumer (`crypto/EcdhMask` for hybrid encryption).
+ *
+ * @see https://www.secg.org/sec1-v2.pdf#page=33 SEC 1 v2.0 §3.3.1, Elliptic Curve Diffie-Hellman Primitive
+ * @see https://www.secg.org/sec1-v2.pdf#page=30 SEC 1 v2.0 §3.2.2.1, Elliptic Curve Public Key Validation Primitive
+ * @see https://www.secg.org/sec1-v2.pdf#page=29 SEC 1 v2.0 §3.2.1, Elliptic Curve Key Pair Generation Primitive
+ *
+ * @dev Construction and notation. SEC 1's symbol follows in brackets.
+ * - `g`: the Jubjub prime-order subgroup generator, of order `ℓ` [`G`, `n`].
+ * - `ek`: the recipient's secret scalar in `[1, ℓ-1]` [`d`, §3.2.1].
+ * - `e`: the sender's ephemeral scalar in `[1, ℓ-1]`, fresh per call [`d`, §3.2.1].
+ * - `pk = g^ek`: the recipient's public key [`Q`, §3.2.1].
+ * - `E = g^e`: the ephemeral public key, published [`Q`, §3.2.1].
+ * - `S = pk^e = g^{ek*e} = E^ek`: the shared secret point, never published
+ *   [`P = d * Q`, §3.3.1]. §3.3.1 outputs `z = x_P`; this module returns `P`
+ *   itself and leaves the KDF to the consumer.
+ * - `identity`: the point at infinity, `ecMulGenerator(0)` [`O`]. §3.2.2.1
+ *   action 1 rejects it as a key; §3.3.1 action 2 rejects it as `P`.
+ *   `deriveShared` does the first; the second cannot fire in a prime-order
+ *   group once the first holds and `e ≢ 0 (mod ℓ)`.
+ * - Jubjub only. A second curve gets its own module with the same circuit names.
+ *
+ * @dev Future APIs.
+ * - `deriveEphemeral(seed: Bytes<32>, nonce: Field): JubjubScalar` — a canonical
+ *   `e` for consumers, making the uniqueness half of the freshness rule true by
+ *   construction rather than a precondition.
+ * - `assertValidPk(pk)` / `isIdentity(pk): Boolean` — reject an identity key
+ *   where it is registered. The `deriveShared` guard fires on the sender's
+ *   transaction, so a bad key costs the sender, not the registrant.
+ * - Jubjub key-pair derivation lives in `crypto/ElGamal` (`derivePk`,
+ *   `secretToScalar`); a shared key module is its natural home.
+ *
+ * @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: a repeated `e` to one recipient repeats `S`, so every key, mask or
+ * nonce a consumer derives from `S` repeats too. Where that derivation is a
+ * one-time pad (`crypto/EcdhMask`) the reuse is catastrophic: subtracting two
+ * ciphertexts reveals the plaintext difference, and either plaintext once the
+ * other is known or constrained.
+ *
+ * Secrecy: `recipientPk` is public, so anyone who learns `e` recomputes
+ * `S = recipientPk^e` and everything derived from it. 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 collapse `S` to the identity point,
+ * which every observer can compute: `recipientPk = identity` gives `S = identity`
+ * for any `e`, and `e = 0` gives `S = identity` for any key. Anything a consumer
+ * derives from such an `S` is public. The identity is a valid subgroup point, so
+ * the runtime subgroup guarantee does NOT catch it; `deriveShared` therefore
+ * asserts `recipientPk != identity` and `ephemeralPk (= g^e) != identity`, and
+ * every sender path reaches both through it. 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 Subgroup membership. Secrecy of `S` relies on the runtime constraining
+ * every `JubjubPoint` into the prime-order subgroup (argued in `crypto/ElGamal`),
+ * so a caller cannot hand in a low-order point that leaks `ekScalar`.
+ *
+ * @dev No ledger state, no witnesses. Both circuits are pure and take their keys
+ * and randomness as explicit arguments. `recoverShared` is exposed for
+ * wallet/off-chain use (recovering a received value needs no proof); the on-chain
+ * path only ever calls `deriveShared`.
+ */
+module Ecdh {
+  import CompactStandardLibrary;
+
+  /**
+   * @description One sender-side ECDH step: the ephemeral public key to publish
+   * and the shared secret point to derive from.
+   *
+   * @notice `sShared` is secret. Keep it a circuit local; disclosing it opens
+   * everything derived from it.
+   */
+  export struct SharedSecret {
+    /** `E = g^e`, public. The recipient recovers `S = E^ek` from it. */
+    ephemeralPk: JubjubPoint;
+
+    /** `S = pk^e`, secret. Never disclose; derive from it in-circuit. */
+    sShared: JubjubPoint;
+  }
+
+  /**
+   * @description Runs the sender's ECDH step: the ephemeral public key `g^e` to
+   * publish and the shared secret `pk^e` to derive from. The single site of the
+   * weak-input guards.
+   *
+   * @notice `e` MUST be fresh per call and secret (see the module freshness
+   * precondition).
+   *
+   * @constraints k=11, rows=1385
+   *
+   * 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 e - A fresh ephemeral scalar.
+   * @return `{ ephemeralPk = g^e, sShared = recipientPk^e }`.
+   */
+  export pure circuit deriveShared(recipientPk: JubjubPoint, e: JubjubScalar): SharedSecret {
+    const identity = ecMulGenerator(0 as JubjubScalar);
+    // An identity key gives S = identity for every `e`.
+    assert(recipientPk != identity, "Ecdh: identity pk");
+    const ephemeralPk = ecMulGenerator(e);
+    // Guarding the POINT subsumes `e == 0` and any `e ≡ 0 (mod ℓ)` (see the
+    // weak-inputs note).
+    assert(ephemeralPk != identity, "Ecdh: zero ephemeral");
+    return SharedSecret { ephemeralPk: ephemeralPk, sShared: ecMul(recipientPk, e) };
+  }
+
+  /**
+   * @description The recipient's half of `deriveShared`: recomputes `S = E^ek`
+   * from a published ephemeral public key.
+   *
+   * @dev Never asserts. A wrong `ekScalar` yields an unrelated point, so a wallet
+   * scanning exchanges not addressed to it learns nothing from this circuit and
+   * the module exposes no key-correctness oracle.
+   *
+   * @constraints k=9, rows=440
+   *
+   * @param ephemeralPk - The sender's published `g^e`.
+   * @param ekScalar - The recipient's secret scalar.
+   * @return The ECDH shared secret point.
+   */
+  export pure circuit recoverShared(ephemeralPk: JubjubPoint, ekScalar: JubjubScalar): JubjubPoint {
+    return ecMul(ephemeralPk, ekScalar);
+  }
+}