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

package/token/ConfidentialFungibleToken.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (token/ConfidentialFungibleToken.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (token/ConfidentialFungibleToken.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -11,7 +11,17 @@ pragma language_version >= 0.26.0;
  * follows the same pattern as `FungibleToken`: a witness-derived
  * `accountId = persistentHash(secretKey)`. Encryption uses a separate witness
  * `wit_ConfidentialTokenEK` to derive an ElGamal keypair `(ek, pk)` via
- * `ElGamal_derivePk`, where `pk = g^degradeToTransient(persistentHash(EK))`.
+ * `ElGamal_derivePk`, where
+ * `pk = g^degradeToTransient(persistentHash([ElGamal domain tag, EK]))`.
+ *
+ * @notice Sharing key material between the two witnesses is PERMITTED. The
+ * account identifier is an untagged hash of the SK and is published as a ledger
+ * map key; the encryption scalar is a DOMAIN-SEPARATED hash of the EK. Because
+ * the two derivations are tagged differently, a wallet may return the same
+ * value from `wit_ConfidentialTokenSK` and `wit_ConfidentialTokenEK`, or derive
+ * both from one master secret, without the published identifier revealing the
+ * encryption key. The domain separation is what makes that safe. Do not remove
+ * it. See `ElGamal.secretToScalar`.
  *
  * @notice Supply. The mint/burn building blocks (`_mint`/`_burn`/`_burnFrom`)
  * live here; total-supply tracking is an optional add-on
@@ -42,6 +52,8 @@ pragma language_version >= 0.26.0;
  *
  *  - `wit_ConfidentialTokenEK`: verified by `ElGamal_assertDecryptsTo`,
  *    which re-derives `pk` and asserts it equals the on-chain stored pk.
+ *    `sweep` and `clearMemos` have no plaintext to decrypt, so they assert the
+ *    same binding directly via `_assertOwnsEncryptionKey`.
  *
  *  - `wit_PlaintextBalance(ct)`: verified by `ElGamal_assertDecryptsTo`,
  *    which asserts `Dec(ct, EK) == claimedValue`. The ciphertext is passed
@@ -62,13 +74,36 @@ pragma language_version >= 0.26.0;
  * high-entropy, and secret for every invocation.
  *
  * Seed REUSE leaks plaintext differences, and the circuit does NOT prevent
- * it. The debit and escrow ciphertexts (`_debit`, `approve`, `_spendEscrow`,
- * and the re-approve refund) derive randomness from a static domain tag with
- * no per-operation nonce, so two operations under one seed share randomness
- * and their public ciphertext deltas reveal the amount difference. The credit
- * path folds the recipient's memo-list length in as a nonce (defense in
- * depth), but that counter RESETS on `clearMemos`, so it is an in-epoch
- * backstop only, never a substitute for freshness.
+ * it. The debit and re-approve-refund ciphertexts (`_debit`, `approve`) derive
+ * randomness from a static domain tag with no per-op nonce, so two
+ * operations under one seed share randomness and their public ciphertext deltas
+ * reveal the amount difference. `_spendEscrow` is the exception: every value it
+ * derives folds in the spend epoch AND both counterparties, so its randomness
+ * is unique per spend regardless of the seed. The credit path folds the
+ * recipient's `_creditEpochs` counter in as a nonce (defense in depth). A sender
+ * advances it with every credit and nothing rolls it back (neither the recipient
+ * nor any circuit) so the party whose randomness it protects is the one moving
+ * it, and a repeated seed still yields distinct randomness there. It is a
+ * backstop, not a substitute for freshness. It covers only credits, and only
+ * against reuse of one seed to one recipient.
+ *
+ * @notice WHOSE confidentiality a seed protects is not always the caller's. On
+ * most paths a wallet's seed hygiene guards its own amounts, so the incentive
+ * and the exposure sit with the same party. The escrow spend path is the
+ * exception: `_spendEscrow` expands every random value it uses from the
+ * SPENDER's seed, but all three protect the OWNER. Two re-encrypt their escrow
+ * and the third masks their remaining allowance. A spender reusing a seed leaks
+ * a counterparty's balance, not their own, and the owner cannot prevent it by
+ * rotating their own seed as the leaking call is not theirs.
+ *
+ * The accidental case is removed by binding both counterparties into the
+ * derivation alongside the epoch, which counts per (owner, spender) and so
+ * restarts for each pair. That covers the two ways one seed repeats randomness
+ * across calls: one spender drawing on two owners, and two wallets sharing a
+ * seed drawing on one owner. Nothing stops a spender who deliberately publishes
+ * their seed, since any construction must let them compute the pad. Wallet
+ * authors supplying a seed for `transferFrom` / `burnFrom` should understand
+ * they are protecting the owner they are spending on behalf of.
  *
  * Seed generation is a WALLET responsibility and OUT OF SCOPE for this
  * contract, which cannot enforce it. The witness shipped in this repo
@@ -86,13 +121,31 @@ pragma language_version >= 0.26.0;
  *  - approve does not disclose the cap (private-cap escrow design).
  *  - Counterparty graph (sender_id, recipient_id) is public on every
  *    transfer.
+ *  - Per-(owner, spender) escrow spend count is public and permanent
+ *    (`_escrowSpendEpochs`); each spend is already visible in tx
+ *    history, so this adds no fact, only a cheaper way to read it.
+ *  - Per-account lifetime credit count is public and permanent
+ *    (`_creditEpochs`); unlike the memo list, it does not reset on
+ *    `clearMemos`.
  *
  * @dev Per-transfer value bound. Value-bearing circuits check
  * `value <= MAX_TRANSFER_VALUE()`, which is now the `Uint<128>` maximum: the ECDH
  * memo delivers the amount directly (no discrete-log recovery), so the former
  * `2^48` cap that kept wallet-side BSGS tractable is gone. Amounts stay well under
  * the Jubjub scalar-field order, so the homomorphic balance sums (and the
- * `g^value` encoding) do not wrap. Balances remain Uint<128>.
+ * `g^value` encoding) do not wrap at any plausible scale. Accumulation makes
+ * that a resource bound rather than an invariant: ~2^124 maximal credits into
+ * one account reach `l`, past which the stored point encodes the sum MOD `l` and
+ * the balance verifies against a smaller number than was deposited.
+ *
+ * @dev Balance claims are `Uint<248>`, wider than the per-transfer bound. A
+ * balance grows by homomorphic addition with no running total to bound, so a
+ * long enough run of in-range credits could otherwise push the stored quantity
+ * past what any `Uint<128>` claim can state, leaving the balance unspendable.
+ * The 120-bit gap between the claim width and the transfer bound puts that at
+ * ~2^120 credits. The two widths are therefore coupled: raising
+ * `MAX_TRANSFER_VALUE` narrows the gap, and 248 is the widest `Uint` Compact
+ * offers, so the claim cannot absorb it.
  *
  * @dev Value delivery via memo channel. Every credit made through `_credit`
  * (mint / transfer / transferFrom) pushes an ECDH one-time-pad memo (see
@@ -174,15 +227,15 @@ pragma language_version >= 0.26.0;
  * into the derivations is a possible defense-in-depth hardening; under review, deferred.
  *
  * Block weight. A deploy bundles every exported entry point's on-chain IR into
- * one transaction, and the value circuits are SHA256-heavy (k=16), so a
- * full-surface deployment is byte-heavy. Whether it fits is a property of the
+ * one transaction, and the value circuits are SHA256-heavy (k=16, k=17 for
+ * `transferFrom`), so a full-surface deployment is byte-heavy. Whether it fits is a property of the
  * target network, not the contract: the per-transaction block byte budget is a
  * governance-configurable, node-side ledger parameter. On the local ledger-8 dev
  * stack the full surface exceeded it and was rejected (`1010: Transaction would
  * exhaust the block limits`), while a reduced surface (e.g. receive + transfer,
  * dropping allowances and supply accounting) fit. So confirm deployability
  * against the target network; if a deployment is over budget there, the lever is
- * exposing only the k=16 value operations it needs, not just trimming getters.
+ * exposing only the value operations it needs, not just trimming getters.
  * A deployed contract can also be upgraded by its Contract Maintenance Authority
  * (CMA), so an over-budget deployment can start with a lean surface and add
  * operations by upgrade instead of fitting the whole surface into one deploy.
@@ -223,6 +276,7 @@ module ConfidentialFungibleToken {
   import CompactStandardLibrary;
   import "../crypto/ElGamal" prefix ElGamal_;
   import "../crypto/EcdhMask" prefix EcdhMask_;
+  import "../utils/Utils" prefix Utils_;
 
   // ---------------------------------------------------------------------------
   // Types
@@ -254,26 +308,137 @@ module ConfidentialFungibleToken {
     ownerMemo: EcdhMask_Ciphertext;
   }
 
+  // Hash preimage for the per-spend randomness `_spendEscrow` derives. The epoch
+  // counts per (owner, spender) and so restarts for each pair, which is why both
+  // parties are bound in alongside it. Drop the owner and one spender's first
+  // spend against two owners repeats `rSpender`; drop the spender and two wallets
+  // sharing a seed repeat `rOwner` against one owner. Either repeat cancels on
+  // subtraction, because the colliding pair is encrypted under one key.
+  struct SpendRandomnessPreimage {
+    seed:    Bytes<32>;
+    domain:  Bytes<32>;
+    owner:   Bytes<32>;
+    spender: Bytes<32>;
+    epoch:   Field;
+  }
+
   // ---------------------------------------------------------------------------
   // Ledger state
   // ---------------------------------------------------------------------------
 
-  // Dual-balance grief fix. `_balances` is the SPENDABLE (confirmed) balance that
-  // debits draw from; `_pending` is the incoming pool that credits land in. Only
-  // the owner moves pending -> spendable, via `sweep()`. So a third party spamming
-  // dust credits cannot churn a victim's spendable ciphertext and invalidate the
-  // victim's in-flight spend proofs (a liveness grief). A wallet's total balance
-  // is `balanceOf` (spendable) + `pendingOf` (pending).
+  /**
+   * @description Spendable (confirmed) balances, encrypted under each account's
+   * ElGamal key. Debits draw from here. Paired with `_pending`: only the owner
+   * moves pending into spendable, via `sweep()`, so a third party spamming dust
+   * credits cannot churn a victim's spendable ciphertext and invalidate their
+   * in-flight spend proofs. A wallet's total is `balanceOf` + `pendingOf`.
+   * @type {Bytes<32>} accountId - The account identifier.
+   * @type {ElGamal_Ciphertext} balance - The encrypted spendable balance.
+   * @type {Map<accountId, balance>}
+   * @type {Map<Bytes<32>, ElGamal_Ciphertext>} _balances
+   */
   export ledger _balances: Map<Bytes<32>, ElGamal_Ciphertext>;
+
+  /**
+   * @description Incoming (unconfirmed) balances, encrypted under each account's
+   * ElGamal key. Credits land here rather than in `_balances`; the owner moves
+   * them across with `sweep()`.
+   * @type {Bytes<32>} accountId - The account identifier.
+   * @type {ElGamal_Ciphertext} pending - The encrypted pending balance.
+   * @type {Map<accountId, pending>}
+   * @type {Map<Bytes<32>, ElGamal_Ciphertext>} _pending
+   */
   export ledger _pending: Map<Bytes<32>, ElGamal_Ciphertext>;
+
+  /**
+   * @description Registered ElGamal encryption keys, one per account.
+   * Registration is one-shot: a second registration for the same account is
+   * rejected.
+   * @type {Bytes<32>} accountId - The account identifier.
+   * @type {JubjubPoint} encryptionKey - The account's ElGamal public key.
+   * @type {Map<accountId, encryptionKey>}
+   * @type {Map<Bytes<32>, JubjubPoint>} _encryptionKeys
+   */
   export ledger _encryptionKeys: Map<Bytes<32>, JubjubPoint>;
+
+  /**
+   * @description Per-account memo inbox. A credit pushes a masked memo the
+   * recipient decrypts off-chain; `pushFront` means newest first.
+   * @type {Bytes<32>} accountId - The recipient's identifier.
+   * @type {List<EcdhMask_Ciphertext>} memos - The recipient's memos.
+   * @type {Map<accountId, memos>}
+   * @type {Map<Bytes<32>, List<EcdhMask_Ciphertext>>} _memos
+   */
   export ledger _memos: Map<Bytes<32>, List<EcdhMask_Ciphertext>>;
+
+  /**
+   * @description Escrowed allowances, keyed by owner then spender. Membership is
+   * checked independently of the entry, so an allowance that was never escrowed
+   * is unspendable.
+   * @type {Bytes<32>} owner - The account that escrowed the allowance.
+   * @type {Bytes<32>} spender - The account allowed to spend it.
+   * @type {EscrowEntry} entry - The escrowed allowance.
+   * @type {Map<owner, Map<spender, entry>>}
+   * @type {Map<Bytes<32>, Map<Bytes<32>, EscrowEntry>>} _escrow
+   */
   export ledger _escrow: Map<Bytes<32>, Map<Bytes<32>, EscrowEntry>>;
 
+  /**
+   * @description Per-(owner, spender) escrow-spend counter, folded into the
+   * randomness `_spendEscrow` derives so repeat spends by one spender against
+   * one owner never share a one-time pad. It restarts for each pair, which is
+   * why both counterparties are bound in too; see `SpendRandomnessPreimage`.
+   *
+   * Kept out of `EscrowEntry`: `approve` replaces that entry wholesale, so a
+   * counter living there would restart on every re-approve.
+   *
+   * Note that this exposes a per-pair spend count which is already derivable
+   * from tx history.
+   * @type {Bytes<32>} owner - The account that escrowed the allowance.
+   * @type {Bytes<32>} spender - The account spending it.
+   * @type {Counter} epoch - The pair's lifetime escrow-spend count.
+   * @type {Map<owner, Map<spender, epoch>>}
+   * @type {Map<Bytes<32>, Map<Bytes<32>, Counter>>} _escrowSpendEpochs
+   */
+  export ledger _escrowSpendEpochs: Map<Bytes<32>, Map<Bytes<32>, Counter>>;
+
+  /**
+   * @description Per-account credit counter. `_credit` uses it as the nonce that
+   * keeps each credit's randomness distinct, so it MUST only ever increase. No
+   * circuit resets it. It is kept out of `_memos` for that reason: the memo list
+   * is prunable by its owner, and a nonce that could be walked back would let a
+   * reused seed repeat an earlier credit's randomness. The cost is that an
+   * account's lifetime credit count is permanently readable from state.
+   *
+   * `Counter` is chosen for no-reset monotonicity, not commutativity. Its
+   * `increment` emits no pinned read, but `_credit` reads the value back to
+   * derive the nonce, and that read pins the recipient's key. Credits to one
+   * recipient still serialize; see the Concurrency note above.
+   * @type {Bytes<32>} accountId - The account identifier.
+   * @type {Counter} epoch - The account's lifetime credit count.
+   * @type {Map<accountId, epoch>}
+   * @type {Map<Bytes<32>, Counter>} _creditEpochs
+   */
+  export ledger _creditEpochs: Map<Bytes<32>, Counter>;
+
+  /**
+   * @description Whether `initialize` has run. Guards against re-initialization
+   * and against use before initialization.
+   */
   export ledger _isInitialized: Boolean;
 
+  /**
+   * @description The token's human-readable name, set once at construction.
+   */
   export sealed ledger _name: Opaque<"string">;
+  /**
+   * @description The token's ticker symbol, set once at construction.
+   */
   export sealed ledger _symbol: Opaque<"string">;
+  /**
+   * @description The number of decimals used to display balances, set once at
+   * construction. Purely presentational; no circuit scales by it.
+   */
   export sealed ledger _decimals: Uint<8>;
 
 
@@ -290,8 +455,9 @@ module ConfidentialFungibleToken {
    * well under the Jubjub scalar-field order, so homomorphic sums do not wrap.
    *
    * @notice This equals the argument type's own maximum, so the per-op check is
-   * effectively a no-op, retained as a single explicit ceiling / documentation
-   * point. Removing the now-vestigial check entirely is a follow-up cleanup.
+   * redundant today. KEEP IT: it compares against a hard constant rather than
+   * the argument type, so it still catches a later widening of the transfer
+   * type — which is what the balance-claim width is sized against.
    */
   export pure circuit MAX_TRANSFER_VALUE(): Uint<128> {
     return 340282366920938463463374607431768211455; // 2^128 - 1
@@ -326,7 +492,7 @@ module ConfidentialFungibleToken {
    * The ciphertext is passed explicitly so the wallet can route to the right
    * cached plaintext by ciphertext identity. This avoids call-order
    * conventions (which would be brittle to circuit refactors) and lets the
-   * wallet maintain a `Map<ElGamal_Ciphertext, Uint128>` lookup.
+   * wallet maintain a `Map<ElGamal_Ciphertext, Uint248>` lookup.
    *
    * Verified in-circuit by `ElGamal_assertDecryptsTo`: a wrong plaintext
    * fails the assertion `Dec(ct, EK) == claimedValue`.
@@ -334,7 +500,7 @@ module ConfidentialFungibleToken {
    * @param ct - The ciphertext whose plaintext is being requested.
    * @returns The wallet's cached plaintext for `ct`.
    */
-  witness wit_PlaintextBalance(ct: ElGamal_Ciphertext): Uint<128>;
+  witness wit_PlaintextBalance(ct: ElGamal_Ciphertext): Uint<248>;
 
   /**
    * @witness wit_RandomnessSeed
@@ -345,10 +511,11 @@ module ConfidentialFungibleToken {
    * module header). The derivation is deterministic and public, so an observer
    * who knows the seed can strip a memo's mask and read the delivered amount, and
    * recover balance/escrow amounts from the public ciphertexts. Seed REUSE leaks
-   * plaintext differences and the circuit does NOT prevent it: only the credit
-   * path folds a per-recipient nonce (the memo-list length) in as defense in
-   * depth, and even that resets on `clearMemos`. The seed MUST be fresh,
-   * high-entropy, and secret for every invocation.
+   * plaintext differences and the circuit does NOT prevent it on most paths.
+   * `_spendEscrow` is an exception (its randomness folds the spend epoch and both
+   * counterparties); the credit path folds the recipient's `_creditEpochs`
+   * counter as defense in depth, and that covers credits alone. The seed MUST be
+   * fresh, high-entropy, and secret for every invocation.
    */
   witness wit_RandomnessSeed(): Bytes<32>;
 
@@ -390,7 +557,7 @@ module ConfidentialFungibleToken {
    * ciphertext if the account is unregistered. The amount is encrypted; only the
    * account (or an authorized viewer) can decrypt it.
    *
-   * @circuitInfo k=10, rows=989
+   * @constraints k=10, rows=984
    *
    * Requirements:
    *
@@ -416,7 +583,7 @@ module ConfidentialFungibleToken {
    * balance is `balanceOf`; a wallet's total is the sum of the two. See the
    * dual-balance note on the ledger declarations.
    *
-   * @circuitInfo k=10, rows=986
+   * @constraints k=10, rows=981
    *
    * Requirements:
    *
@@ -447,7 +614,7 @@ module ConfidentialFungibleToken {
    * getter grants nothing, the spend path (`transferFrom`/`burnFrom`) gates on
    * `_escrow` membership independently, so a non-existent allowance is unspendable.
    *
-   * @circuitInfo k=10, rows=938
+   * @constraints k=10, rows=936
    *
    * @param {Bytes<32>} owner - The account that granted the allowance.
    * @param {Bytes<32>} spender - The approved spender.
@@ -473,7 +640,7 @@ module ConfidentialFungibleToken {
   /**
    * @description Returns whether `account` has registered an encryption key.
    *
-   * @circuitInfo k=9, rows=305
+   * @constraints k=9, rows=303
    *
    * @param {Bytes<32>} account - The account to query.
    * @return {Boolean} - True if `account` is registered.
@@ -491,7 +658,7 @@ module ConfidentialFungibleToken {
    * `wit_ConfidentialTokenEK` and initializes their balance to an encryption of
    * zero. Registration is a prerequisite for sending or receiving.
    *
-   * @circuitInfo k=13, rows=6203
+   * @constraints k=13, rows=8046
    *
    * @notice Returns the caller's `accountId`. A composing contract can gate on
    * the returned value (e.g. assert it is KYC-approved) to restrict who may
@@ -555,14 +722,14 @@ module ConfidentialFungibleToken {
   // (its `mint` increments the total before crediting; its `burn` decrements it
   // after debiting).
   //
-  // Randomness: `_credit` folds a per-recipient nonce (the memo-list length)
-  // into its seed-derived randomness as defense in depth. This helps only
-  // within a memo epoch: `clearMemos` resets the counter, and it is NOT a
-  // substitute for seed freshness (see the header note); seed reuse still leaks
-  // credited-amount differences. Within an epoch the nonce keeps a single
-  // circuit's multi-party credits distinct (each recipient's count is
-  // independent). The debit side has no such nonce, so seed freshness is the
-  // only defense there.
+  // Randomness: `_credit` folds a per-recipient nonce (`_creditEpochs`) into
+  // its seed-derived randomness as defense in depth. The nonce only ever
+  // increases, so it never repeats a value, but it is NOT a substitute for seed
+  // freshness (see the header note); seed reuse still leaks credited-amount
+  // differences on every other path. It also keeps a single circuit's
+  // multi-party credits distinct, each recipient's counter being independent.
+  // The debit side has no such nonce, so seed freshness is the only defense
+  // there.
   // ---------------------------------------------------------------------------
 
   /**
@@ -618,11 +785,11 @@ module ConfidentialFungibleToken {
    * account's balance ciphertext and pushes an ECDH one-time-pad memo that
    * delivers `value` directly to the recipient (no discrete-log recovery, so no
    * `2^48` bound). All per-credit randomness is derived internally from the
-   * witness seed and a per-recipient monotonic nonce (the memo-list length),
-   * which keeps randomness distinct WITHIN a memo epoch (defense in depth for
-   * the memo's one-time pad; see `crypto/EcdhMask`). That nonce RESETS on
-   * `clearMemos`, so it is an in-epoch backstop only, never a substitute for
-   * seed freshness (see the module header and the section note above `_debit`).
+   * witness seed and a per-recipient monotonic nonce (`_creditEpochs`), which
+   * keeps randomness distinct across credits (defense in depth for the memo's
+   * one-time pad; see `crypto/EcdhMask`). That nonce only ever increases and
+   * nothing resets it, but it is never a substitute for seed freshness (see the
+   * module header and the section note above `_debit`).
    *
    * @warning Does not adjust any supply total. Called outside a supply-accounted
    * flow, `_credit` mints unbacked value (inflation) and breaks the
@@ -642,20 +809,25 @@ module ConfidentialFungibleToken {
 
     const recipientPk = _encryptionKeys.lookup(disclose(account));
 
-    // Ensure the recipient's memo list exists; its length is a per-recipient
-    // monotonic nonce that makes this credit's randomness unique even if the
-    // wallet reuses its seed. Freshness is essential for the memo OTP: a repeated
-    // ephemeral to the same recipient would reuse the pad.
+    // Ensure the recipient's memo list exists.
     if (!_memos.member(disclose(account))) {
       _memos.insert(disclose(account), default<List<EcdhMask_Ciphertext>>);
     }
-    const count = _memos.lookup(disclose(account)).length() as Field;
+
+    // Advance the recipient's credit epoch and use it as this credit's nonce.
+    // The nonce must come from a source that only increases; anything the
+    // recipient can reset would let a reused seed repeat the randomness below.
+    if (!_creditEpochs.member(disclose(account))) {
+      _creditEpochs.insert(disclose(account), default<Counter>);
+    }
+    _creditEpochs.lookup(disclose(account)).increment(1);
+    const count = _creditEpochs.lookup(disclose(account)) as Field;
     const seed = wit_RandomnessSeed();
 
     // Randomness must be a VALID Jubjub scalar. `transientHash`'s raw Field output
-    // can exceed the Jubjub scalar-field order, so each scalar is derived via
-    // `degradeToTransient(persistentHash(...))`, which truncates into the scalar
-    // field. The per-recipient count, folded into a
+    // can exceed the Jubjub scalar-field order and fault `ecMulGenerator`, so each
+    // scalar is derived via `degradeToTransient(persistentHash(...))`, which
+    // truncates into the scalar field. The per-recipient epoch, folded into a
     // Bytes<32> nonce, keeps each credit's randomness unique even if the seed
     // repeats (essential for the memo OTP). This inlines the tag + expansion into
     // a single hash per scalar. The residual persistentHash cost is poseidon-gated
@@ -693,7 +865,7 @@ module ConfidentialFungibleToken {
    * `extensions/ConfidentialFungibleTokenPublicSupply`) if the deployment tracks
    * `totalSupply`.
    *
-   * @circuitInfo k=15, rows=27142
+   * @constraints k=15, rows=26962
    *
    * Requirements:
    *
@@ -716,7 +888,7 @@ module ConfidentialFungibleToken {
    * `extensions/ConfidentialFungibleTokenPublicSupply`) if the deployment tracks
    * `totalSupply`.
    *
-   * @circuitInfo k=14, rows=14673
+   * @constraints k=14, rows=14889
    *
    * Requirements:
    *
@@ -740,7 +912,7 @@ module ConfidentialFungibleToken {
    * credits `to`, and pushes an encrypted memo to `to`. The amount is hidden;
    * the (sender, recipient) pair is public.
    *
-   * @circuitInfo k=16, rows=41617
+   * @constraints k=16, rows=41623
    *
    * @notice Returns the caller's (sender's) `accountId` for caller-side gating.
    * The sender is derived from the same authentication `_debit` performs, so the
@@ -778,7 +950,7 @@ module ConfidentialFungibleToken {
    * operations (`mint`/`burn`) live in a separate layer outside this conserving
    * surface, and only they may break conservation.
    *
-   * @circuitInfo k=16, rows=41606
+   * @constraints k=16, rows=41612
    *
    * @notice Like `transfer`, the credit lands in the recipient's pending pool
    * (see the dual-balance note); the caller sweeps their own incoming value.
@@ -814,12 +986,13 @@ module ConfidentialFungibleToken {
    * @description Sweeps the caller's incoming `pending` pool into their
    * `spendable` balance. Credits land in `pending` (see the dual-balance note);
    * this `sweep` is the ONLY path from pending into spendable, and only the owner
-   * can invoke it (the account is derived from the caller's witness secret). So a
-   * third party spamming credits cannot force a victim's spendable ciphertext to
-   * change, which is what would otherwise invalidate the victim's in-flight spend
-   * proofs (a liveness grief).
+   * can invoke it (the caller proves BOTH witness secrets: the account secret
+   * identifies the account, the encryption secret proves the caller can read it).
+   * So a third party spamming credits cannot force a victim's spendable ciphertext
+   * to change, which is what would otherwise invalidate the victim's in-flight
+   * spend proofs (a liveness grief).
    *
-   * @circuitInfo k=13, rows=2879
+   * @constraints k=13, rows=7541
    *
    * @notice Purely homomorphic: adds the two ciphertexts (same key) and resets
    * pending to Enc(0). No plaintext is needed; the wallet already learned the
@@ -829,14 +1002,14 @@ module ConfidentialFungibleToken {
    *
    * - Contract is initialized.
    * - The caller is registered.
+   * - The caller holds the encryption secret registered for their account.
    *
    * @return {Bytes<32>} - The caller's accountId.
    */
   export circuit sweep(): Bytes<32> {
     assertInitialized();
     const accountId = _computeAccountId();
-    assert(_encryptionKeys.member(disclose(accountId)),
-           "ConfidentialFungibleToken: not registered");
+    _assertOwnsEncryptionKey(accountId);
     const newSpendable = ElGamal_add(
       _balances.lookup(disclose(accountId)),
       _pending.lookup(disclose(accountId)));
@@ -852,7 +1025,7 @@ module ConfidentialFungibleToken {
    * refunds any prior escrow, so allowances replace rather than stack. The cap
    * is not public.
    *
-   * @circuitInfo k=16, rows=43067
+   * @constraints k=16, rows=42938
    *
    * @notice Returns the caller's (approver's) `accountId` for caller-side gating.
    *
@@ -936,7 +1109,7 @@ module ConfidentialFungibleToken {
    * caller via `approve`) and credits it to `to`, reducing both escrow copies by
    * `value`. The amount is hidden.
    *
-   * @circuitInfo k=16, rows=63207
+   * ???? @constraints k=17, rows=68920
    *
    * @notice Returns the caller's (spender's) `accountId` for caller-side gating.
    *
@@ -976,7 +1149,14 @@ module ConfidentialFungibleToken {
    * @description Clears the caller's memo list, letting a wallet that has folded
    * its memos into its local balance cache prune on-chain memo storage.
    *
-   * @circuitInfo k=13, rows=2316
+   * `expectedEpoch` is the caller's view of its `_creditEpochs` value at the
+   * moment it read the list. The call is rejected unless that still matches, so
+   * a credit landing between the read and this transaction is never silently
+   * discarded. The wallet retries against the memos it has now seen. A wallet
+   * therefore reads its memo list and its epoch together, folds the memos into
+   * its cache, and passes that epoch back here.
+   *
+   * @constraints k=13, rows=7019
    *
    * @warning Clearing memos is destructive and can permanently lock funds. The
    * on-chain balance ciphertext is not directly decryptable (discrete-log
@@ -984,20 +1164,35 @@ module ConfidentialFungibleToken {
    * them without a durable off-chain record of the balance loses the ability to
    * recover it; and because spending requires proving the balance plaintext, the
    * funds become unspendable, not merely undisplayable. Clear only memos already
-   * folded into a durable cache/backup (see §7 of the design doc).
+   * folded into a durable cache/backup. The epoch check only rules out a credit
+   * the caller has not seen; it does not make clearing safe for memos the caller
+   * never folded in.
+   *
+   * @param {Uint<64>} expectedEpoch - The caller's view of its credit epoch.
    *
    * Requirements:
    *
    * - Contract is initialized.
+   * - The caller is registered.
+   * - The caller holds the encryption secret registered for their account.
+   * - The caller has a memo list.
+   * - `expectedEpoch` equals the caller's current credit epoch.
    *
    * @return {[]} - Empty tuple.
    */
-  export circuit clearMemos(): [] {
+  export circuit clearMemos(expectedEpoch: Uint<64>): [] {
     assertInitialized();
     const accountId = _computeAccountId();
-    if (_memos.member(disclose(accountId))) {
-      _memos.insert(disclose(accountId), default<List<EcdhMask_Ciphertext>>);
-    }
+    _assertOwnsEncryptionKey(accountId);
+
+    // Both reads are unconditional, so both are pinned in the transcript and a
+    // concurrent credit invalidates this tx
+    assert(_memos.member(disclose(accountId)),
+           "ConfidentialFungibleToken: no memo list");
+    assert(_creditEpochs.lookup(disclose(accountId)) as Field == expectedEpoch as Field,
+           "ConfidentialFungibleToken: memo list changed");
+
+    _memos.insert(disclose(accountId), default<List<EcdhMask_Ciphertext>>);
   }
 
   // ---------------------------------------------------------------------------
@@ -1026,16 +1221,40 @@ module ConfidentialFungibleToken {
     return computeAccountId(wit_ConfidentialTokenSK());
   }
 
+  /**
+   * @description Asserts `accountId` is registered and that the caller holds the
+   * encryption secret registered for it, by re-deriving the public key and
+   * comparing it to ledger state.
+   *
+   * @notice Circuits that move or destroy value prove this implicitly, via
+   * `ElGamal_assertDecryptsTo` on a balance. `sweep` and `clearMemos` have no
+   * plaintext to decrypt, so they assert it directly: holding the account secret
+   * alone must not be enough to clear a memo list or merge pending value, since
+   * doing both leaves the holder unable to state a balance they can no longer
+   * learn.
+   */
+  circuit _assertOwnsEncryptionKey(accountId: Bytes<32>): [] {
+    assert(_encryptionKeys.member(disclose(accountId)),
+           "ConfidentialFungibleToken: not registered");
+    assert(ElGamal_derivePk(wit_ConfidentialTokenEK()) ==
+             _encryptionKeys.lookup(disclose(accountId)),
+           "ConfidentialFungibleToken: wrong encryption key");
+  }
+
   /**
    * @description Derives the public `accountId` from a secret key, as
    * `persistentHash(sk)`. Pure, so a wallet can compute its own account
    * identifier off-chain (no proof) before transacting.
    *
+   * @dev Delegates to `Utils.computeAccountId` rather than reimplementing the
+   * hash. The identifier is deliberately GLOBAL. The same key material yields
+   * the same id in every module that derives it.
+   *
    * @param {Bytes<32>} sk - The account secret key.
    * @return {Bytes<32>} - The derived accountId.
    */
   export pure circuit computeAccountId(sk: Bytes<32>): Bytes<32> {
-    return persistentHash<Vector<1, Bytes<32>>>([sk]);
+    return Utils_computeAccountId(sk);
   }
 
   /**
@@ -1080,15 +1299,35 @@ module ConfidentialFungibleToken {
 
     const ek = wit_ConfidentialTokenEK();
     const spenderPk = _encryptionKeys.lookup(disclose(spenderId));
-    const escrowPlaintext = wit_PlaintextBalance(entry.spenderCt);
-    ElGamal_assertDecryptsTo(entry.spenderCt, spenderPk, ek, escrowPlaintext);
+    // Balance claims are `Uint<248>`, but an escrow cannot legitimately exceed
+    // the transfer bound: `approve` caps it at `Uint<128>` and replaces rather
+    // than stacks, and `_spendEscrow` only reduces it. Narrowing states that
+    // invariant here instead of leaving it to inspection of those two circuits.
+    // The cast fails closed, so an out-of-range claim aborts rather than wraps.
+    const escrowPlaintext =
+      wit_PlaintextBalance(entry.spenderCt) as Uint<128>;
+    ElGamal_assertDecryptsTo(entry.spenderCt, spenderPk, ek, escrowPlaintext as Uint<248>);
     assert(escrowPlaintext >= value,
            "ConfidentialFungibleToken: insufficient allowance");
 
     const seed = wit_RandomnessSeed();
-    const rSpender = ElGamal_expandRandomness(seed, pad(32, "spend_escrow_spender"));
-    const rOwner   = ElGamal_expandRandomness(seed, pad(32, "spend_escrow_owner"));
-    const eOwnerMemo = ElGamal_expandRandomness(seed, pad(32, "spend_owner_memo"));
+
+    // The seed is the SPENDER's, but all three values protect the OWNER. The
+    // epoch below plus both counterparties in the preimage are what keep them
+    // distinct when a seed is reused. See the module header's @notice.
+    if (!_escrowSpendEpochs.member(disclose(fromAddress))) {
+      _escrowSpendEpochs.insert(disclose(fromAddress), default<Map<Bytes<32>, Counter>>);
+    }
+    if (!_escrowSpendEpochs.lookup(disclose(fromAddress)).member(disclose(spenderId))) {
+      _escrowSpendEpochs.lookup(disclose(fromAddress)).insert(disclose(spenderId), default<Counter>);
+    }
+    _escrowSpendEpochs.lookup(disclose(fromAddress)).lookup(disclose(spenderId)).increment(1);
+    const spendEpoch =
+      _escrowSpendEpochs.lookup(disclose(fromAddress)).lookup(disclose(spenderId)) as Field;
+
+    const rSpender   = _expandSpendRandomness(seed, pad(32, "spend_escrow_spender"), fromAddress, spenderId, spendEpoch);
+    const rOwner     = _expandSpendRandomness(seed, pad(32, "spend_escrow_owner"),   fromAddress, spenderId, spendEpoch);
+    const eOwnerMemo = _expandSpendRandomness(seed, pad(32, "spend_owner_memo"),     fromAddress, spenderId, spendEpoch);
 
     const ownerPk = _encryptionKeys.lookup(disclose(fromAddress));
     const newSpenderCt = ElGamal_subEncrypted(entry.spenderCt, spenderPk, value, rSpender);
@@ -1119,7 +1358,7 @@ module ConfidentialFungibleToken {
    * recipient credit. The building block for a composing contract's
    * `burnFrom`; it performs no supply accounting (see `_burn`).
    *
-   * @circuitInfo k=16, rows=36274
+   * ???? @constraints k=16, rows=42201
    *
    * Requirements:
    *
@@ -1135,6 +1374,25 @@ module ConfidentialFungibleToken {
     return _spendEscrow(fromAddress, value);
   }
 
+  /**
+   * @description Derives one per-spend random scalar for `_spendEscrow`. Does
+   * what `ElGamal_expandRandomness` does, but folds both counterparties and the
+   * escrow-spend epoch into the preimage as well as the seed and domain tag, so
+   * each spend gets distinct randomness even when a seed is reused.
+   */
+  pure circuit _expandSpendRandomness(
+      seed: Bytes<32>, domain: Bytes<32>, owner: Bytes<32>, spender: Bytes<32>,
+      epoch: Field): JubjubScalar {
+    return degradeToTransient(
+             persistentHash<SpendRandomnessPreimage>(
+               SpendRandomnessPreimage {
+                 seed: seed, domain: domain, owner: owner, spender: spender,
+                 epoch: epoch
+               }
+             )
+           ) as JubjubScalar;
+  }
+
   /**
    * @description Refunds any prior escrow for (ownerId, spender) to the owner's
    * main balance and clears the slot, so re-approving replaces rather than