@openzeppelin/compact-contracts 0.3.0-alpha → 0.3.0-alpha.2

package/README.md

@@ -214,7 +214,7 @@ git clone git@github.com:OpenZeppelin/compact-contracts.git
 ```bash
 nvm install && \
 yarn && \
-yarn compact
+yarn compile
 ```
 
 ### Run tests
@@ -226,8 +226,8 @@ yarn test
 ### Check/apply Biome formatter
 
 ```bash
-yarn fmt-and-lint
-yarn fmt-and-lint:fix
+yarn lint
+yarn lint:fix
 ```
 
 ### Advanced
@@ -235,8 +235,8 @@ yarn fmt-and-lint:fix
 #### Targeted compilation
 
 ```bash
-yarn compact:access
-yarn compact:archive
+yarn compile:access
+yarn compile:archive
 ...
 ```
 
@@ -246,10 +246,10 @@ ZK key generation is slow and usually unnecessary during development.
 
 ```bash
 # Full compilation with skip-zk (use environment variable)
-SKIP_ZK=true yarn compact
+SKIP_ZK=true yarn compile
 
 # Access compilation with skip-zk (this compiles security first as a dependency)
-SKIP_ZK=true yarn compact:access
+SKIP_ZK=true yarn compile:access
 ```
 
 #### Clean environment

package/access/AccessControl.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (access/AccessControl.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (access/AccessControl.compact)
 
 pragma language_version >= 0.23.0;
 

package/access/Ownable.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (access/Ownable.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (access/Ownable.compact)
 
 pragma language_version >= 0.23.0;
 

package/access/ShieldedAccessControl.compact

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

package/access/ZOwnablePK.compact

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

package/crypto/EcdhMask.compact

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (crypto/EcdhMask.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module EcdhMask
+ * @description Stateless ECDH hybrid encryption of a single field element to a
+ * Jubjub public key. Delivers a value to whoever holds the secret behind a
+ * Jubjub public key WITHOUT encoding it in the exponent, so recovery needs no
+ * discrete-log search and the value is unbounded within `Uint<128>`. This is the
+ * direct-decrypt counterpart to the homomorphic `crypto/ElGamal`: use ElGamal to
+ * accumulate ciphertexts, use this to hand a recipient the plaintext.
+ *
+ * Construction (recipient key `pk = g^ek`, ephemeral scalar `e` fresh per call):
+ *   E    = g^e                      (ephemeral public key)
+ *   S    = pk^e = g^{ek*e}          (ECDH shared secret point)
+ *   mask = KDF(S)                   (domain-separated Field, see `kdf`)
+ *   ct   = value + mask             (field one-time-pad)
+ * Recipient recovers: S = E^ek, mask = KDF(S), value = ct - mask.
+ *
+ * @dev Freshness and secrecy precondition (CRITICAL). `e` MUST be both unique per
+ * call to the same recipient AND secret (unpredictable to observers), even across
+ * circuit invocations that reuse a randomness seed.
+ *
+ * Uniqueness: the mask is a one-time pad, so a repeated `e` repeats `S` and
+ * `mask`, and reusing a pad is catastrophic (subtracting two ciphertexts recovers
+ * both values).
+ *
+ * Secrecy: `recipientPk` is public, so anyone who learns `e` recomputes
+ * `S = recipientPk^e`, hence the mask, and opens the ciphertext. A unique but
+ * PREDICTABLE `e` (a plain counter, a public nonce) therefore breaks
+ * confidentiality completely. `e` must be high-entropy and secret, exactly like
+ * an ElGamal encryption randomness (see `crypto/ElGamal`), not merely distinct.
+ *
+ * The caller supplies `e` and owns both properties, e.g. by expanding a secret
+ * per-invocation seed bound to a per-recipient-unique nonce (a monotonic index).
+ * This is stronger than exponential ElGamal's uniqueness requirement (there,
+ * reuse merely leaks plaintext equality); do not treat `e` as "any randomness."
+ *
+ * @dev Weak inputs. Two degenerate inputs zero the shared secret and expose the
+ * value: `recipientPk = identity` gives `S = identity` for any `e`, and `e = 0`
+ * gives `S = identity` for any key. Both yield `mask = KDF(identity, domain)`, a
+ * value any observer can recompute, so `ct = value + mask` opens trivially. The
+ * identity is a valid subgroup point, so the runtime subgroup guarantee does NOT
+ * catch it; `encrypt` therefore asserts `recipientPk != identity` and
+ * `ephemeralPk (= g^e) != identity`. Guarding the ephemeral POINT rather than the
+ * scalar subsumes `e != 0` and stays correct regardless of how the runtime treats
+ * an out-of-range scalar: `g^e = identity` captures both `e = 0` and any
+ * `e ≡ 0 (mod ℓ)`. (Guarding `e != 0` directly would instead lean on the runtime
+ * faulting `ecMul` for scalars `≥ ℓ`; the point guard removes that dependency.)
+ * These are the only weak inputs (for a subgroup key, `S = identity` iff the
+ * ephemeral point is the identity).
+ *
+ * @dev Integrity. The pad is malleable and NO authentication is added here. This
+ * is safe in the intended on-chain use, where the ciphertext is computed
+ * in-circuit from a value the same circuit commits to elsewhere (a producer
+ * cannot desync the two) and is immutable once written (no in-transit attacker).
+ * A corrupted ciphertext could only fail the recipient's own later proof, never
+ * enable theft. Consumers with a different threat model (mutable storage,
+ * in-transit tampering) MUST add their own authentication.
+ *
+ * @dev Security. This is hashed ElGamal (ECIES without a MAC) over Jubjub and
+ * inherits its guarantees: IND-CPA under the Oracle Diffie-Hellman assumption in
+ * the random-oracle model (the `persistentHash` KDF keyed by the secret point
+ * `S`). It is NOT IND-CCA: the additive pad is malleable (see Integrity), which
+ * is acceptable here only because the on-chain ciphertext is bound in-circuit to
+ * the value it commits to elsewhere. Hiding carries a large margin: `kdf` returns
+ * a `degradeToTransient` output in `[0, 2^248)` while `value < 2^128`, so even
+ * treating the KDF output as uniform the value is hidden with about `2^-120`
+ * statistical slack, leaving only the assumption that the hash of the DH secret
+ * is PRF-like. Confidentiality relies on the runtime constraining every
+ * `JubjubPoint` into the prime-order subgroup (see `crypto/ElGamal`), so `S`
+ * cannot be a low-order point that leaks `ek`. Binding the ephemeral `E` into the
+ * KDF is deliberately omitted: for a fixed `recipientPk`, `E = g^e` and
+ * `S = pk^e` are both determined by `e`, so `KDF(S)` already varies with `E` and
+ * folding it in buys nothing.
+ *
+ * @dev Shared key with `crypto/ElGamal` (in scope). A consumer MAY use the same
+ * recipient Jubjub key for both these memos (hashed ElGamal) and exponential-
+ * ElGamal balance ciphertexts, as the confidential token does. This joint use is
+ * safe: the two schemes share only the public key, this KDF is domain-separated
+ * and keyed by the secret DH point, and neither exposes a decryption oracle, so
+ * under CPA / ODH a ciphertext of one scheme does not help attack the other.
+ *
+ * @dev No ledger state, no witnesses. Every circuit is pure and takes its keys,
+ * value, and randomness as explicit arguments. `decrypt` is exposed as a pure
+ * circuit for wallet/off-chain use (recovering a received value needs no proof);
+ * the on-chain path only ever calls `encrypt`.
+ */
+module EcdhMask {
+  import CompactStandardLibrary;
+
+  /**
+   * @description An ECDH one-time-pad ciphertext: the ephemeral public key and
+   * the field-masked value.
+   */
+  export struct Ciphertext {
+    ephemeralPk: JubjubPoint;
+    ct: Field;
+  }
+
+  /**
+   * @description Derives the field mask from the ECDH shared secret point,
+   * domain-separated by a caller-supplied `domain` tag. Hashes the point to
+   * `Bytes<32>`, then re-hashes it with the domain tag and truncates into the
+   * field via `degradeToTransient`. The consumer chooses `domain` (so this
+   * module is not tied to any one protocol) and MUST use the same value on
+   * encrypt and decrypt.
+   *
+   * @dev Uses `persistentHash` deliberately: the recipient reproduces this mask
+   * to decrypt, possibly across a platform upgrade, so it must be upgrade-stable.
+   *
+   * @param sShared - The ECDH shared secret point (`pk^e` for the sender,
+   *                  `E^ek` for the recipient; equal by construction).
+   * @param domain - The consumer's domain-separation tag.
+   * @return The field mask.
+   */
+  export pure circuit kdf(sShared: JubjubPoint, domain: Bytes<32>): Field {
+    const pointHash = persistentHash<JubjubPoint>(sShared);
+    return degradeToTransient(
+      persistentHash<Vector<2, Bytes<32>>>([pointHash, domain])
+    );
+  }
+
+  /**
+   * @description Encrypts `value` to `recipientPk` under ephemeral scalar `e`.
+   *
+   * @notice `e` MUST be fresh per call (see the module freshness precondition).
+   *
+   * Requirements:
+   *
+   * - `recipientPk` is not the identity point.
+   * - `e` is non-zero, a valid Jubjub scalar (`< ℓ`), secret, and fresh per call.
+   *
+   * @param recipientPk - The recipient's Jubjub public key (`g^ek`).
+   * @param value - The value to deliver (any `Uint<128>`; no `2^48` bound).
+   * @param e - A fresh ephemeral scalar.
+   * @param domain - The consumer's domain-separation tag (must match decrypt).
+   * @return The ciphertext `{ ephemeralPk = g^e, ct = value + KDF(pk^e) }`.
+   */
+  export pure circuit encrypt(
+                        recipientPk: JubjubPoint,
+                        value: Uint<128>,
+                        e: Field,
+                        domain: Bytes<32>
+                        ): Ciphertext {
+    const identity = ecMulGenerator(0 as Field);
+    assert(recipientPk != identity, "EcdhMask: identity pk");
+    const ephemeralPk = ecMulGenerator(e);
+    // Guard the ephemeral POINT, not the scalar: `ephemeralPk == identity`
+    // captures `e == 0` and any `e` that reduces to 0 mod l, so the guard is
+    // correct regardless of how the runtime treats an out-of-range scalar. This
+    // subsumes `e != 0` (see the weak-inputs note).
+    assert(ephemeralPk != identity, "EcdhMask: zero ephemeral");
+    const sShared = ecMul(recipientPk, e);
+    const mask = kdf(sShared, domain);
+    return Ciphertext { ephemeralPk: ephemeralPk, ct: (value as Field) + mask };
+  }
+
+  /**
+   * @description Recovers the value from a ciphertext using the recipient's
+   * secret scalar. Pure and off-chain (no proof needed to read a received value).
+   *
+   * @param ciphertext - The ciphertext to decrypt.
+   * @param ekScalar - The recipient's secret scalar (`crypto/ElGamal`'s
+   *                   `secretToScalar(EK)`).
+   * @param domain - The consumer's domain-separation tag (must match encrypt).
+   * @return The recovered value as a `Field` (equal to the original `value`,
+   *         which is `< 2^128`).
+   */
+  export pure circuit decrypt(ciphertext: Ciphertext, ekScalar: Field, domain: Bytes<32>): Field {
+    const sShared = ecMul(ciphertext.ephemeralPk, ekScalar);
+    const mask = kdf(sShared, domain);
+    return ciphertext.ct - mask;
+  }
+}

package/crypto/ElGamal.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (crypto/ElGamal.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (crypto/ElGamal.compact)
 
 pragma language_version >= 0.23.0;
 

package/multisig/ForwarderPrivate.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ForwarderPrivate.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (multisig/ForwarderPrivate.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -97,8 +97,12 @@ module ForwarderPrivate {
    * @description Spends a previously-deposited shielded coin to the parent,
    * a coin public key. The caller proves knowledge of `(parent, opSecret)`
    * matching the stored commitment; the coin is sent as a plain shielded note,
-   * so the parent stays hidden on-chain. If `coin.value` exceeds `value`, the
-   * change is re-emitted back to the contract for future drains.
+   * so the parent stays hidden on-chain. If `coin.value` exceeds `value`,
+   * `sendShielded` routes the change back to this contract as a self-owned
+   * output; `_drain` returns it untouched via `result.change`. The
+   * implementing contract chooses what to do with it: leave it dwelling at
+   * the contract for a future drain, or spend it onward to a different
+   * recipient in the same transaction via `sendImmediateShielded`.
    *
    * The parent is a `ZswapCoinPublicKey`, never a `ContractAddress`: a shielded
    * send to a contract publishes that contract's address in cleartext on the
@@ -106,7 +110,7 @@ module ForwarderPrivate {
    * would defeat the private-parent guarantee. A coin public key is encrypted
    * inside the Zswap output and never appears on the public transcript.
    *
-   * @circuitInfo k=16, rows=41961
+   * @circuitInfo k=15, rows=23937
    *
    * Requirements:
    *
@@ -160,14 +164,14 @@ module ForwarderPrivate {
       disclose(value)
     );
 
-    if (disclose(result.change.is_some)) {
-      sendImmediateShielded(
-        disclose(result.change.value),
-        Utils_selfAsRecipient(),
-        disclose(result.change.value.value)
-      );
-    }
-
+    // `sendShielded` already emits any change as a fresh output owned by this
+    // contract (dwelling at the contract address for future drains). `_drain`
+    // returns it untouched: it must not re-spend the change here and then hand
+    // that same (now-nullified) coin back via `result.change` — that is the
+    // double spend a node rejects on the next drain. A caller is free to spend
+    // the returned change onward itself (e.g. route it to another recipient);
+    // the rule is only that the change must never be re-spent AND still treated
+    // as held.
     return result;
   }
 

package/multisig/ForwarderShielded.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ForwarderShielded.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (multisig/ForwarderShielded.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -103,7 +103,7 @@ module ForwarderShielded {
    * `sendImmediateShielded` to the stored parent recipient (always the
    * `left` / coin-public-key arm today).
    *
-   * @circuitInfo k=15, rows=18573
+   * @circuitInfo k=15, rows=24446
    *
    * Requirements:
    *

package/multisig/ForwarderUnshielded.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ForwarderUnshielded.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (multisig/ForwarderUnshielded.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -105,7 +105,7 @@ module ForwarderUnshielded {
    * forwards it to `_parent` via `sendUnshielded` (always the `right` /
    * user-address arm today).
    *
-   * @circuitInfo k=9, rows=436
+   * @circuitInfo k=10, rows=565
    *
    * Requirements:
    *

package/multisig/ProposalManager.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ProposalManager.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (multisig/ProposalManager.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -12,12 +12,33 @@ pragma language_version >= 0.23.0;
  * Recipient type with a RecipientKind tag. Typed helper circuits
  * provide safe construction of recipients without exposing the
  * internal Bytes<32> representation to consumers.
+ *
+ * @warning PROPOSALS ARE PUBLIC. `_proposals` is exported ledger state, so
+ * every proposal's recipient address, token color, amount, and status is
+ * readable off-chain, and `_nextProposalId` reveals how many have been created.
+ * This holds regardless of which treasury a consumer composes: pairing this
+ * module with `ShieldedTreasuryStateless` still publishes the full intent of
+ * every transfer, even though the transfer itself is shielded. The transfer is
+ * private; the plan is not.
+ *
+ * @notice `RecipientKind` is the only thing distinguishing what a recipient's
+ * 32 bytes mean, the same value is read as a Zswap coin public key, a contract
+ * address, or a user address depending on the tag. `Contract` is accepted by
+ * both `toShieldedRecipient` and `toUnshieldedRecipient`, so the tag alone does
+ * not determine the rail; a consumer composing both treasuries could route the
+ * same proposal either way.
  */
 module ProposalManager {
   import CompactStandardLibrary;
 
   // ─── Types ──────────────────────────────────────────────────────
 
+  /**
+   * @description Proposal lifecycle states. `Inactive` is the zero value and is
+   * never stored: `_createProposal` writes `Active`, and every view asserts the
+   * proposal exists before reading, so a stored proposal can never read
+   * `Inactive`.
+   */
   export enum ProposalStatus {
     Inactive,
     Active,
@@ -176,6 +197,19 @@ module ProposalManager {
   /**
    * @description Creates a new proposal.
    *
+   * @warning The recipient is NOT validated beyond being well-typed. Two
+   * consequences the consumer must handle:
+   *
+   * - A `kind` the execution rail cannot accept (an `UnshieldedUser` recipient
+   *   on a shielded treasury, say) creates a proposal that passes here and then
+   *   reverts in `toShieldedRecipient` at execution. It stays `Active` and
+   *   unexecutable on that rail until `_cancelProposal` retires it.
+   * - A zero or otherwise unspendable `address` is accepted, and funds sent to
+   *   it on execution are unrecoverable.
+   *
+   * @notice `_nextProposalId` is incremented and then read back for the map key,
+   * making this a pinned read-modify-write.
+   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy.

package/multisig/ShieldedTreasury.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ShieldedTreasury.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (multisig/ShieldedTreasury.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -18,6 +18,19 @@ pragma language_version >= 0.23.0;
  * purposes. The canonical balance query is `getTokenBalance`, which
  * reads the actual coin value from the UTXO map.
  *
+ * @warning This treasury's HOLDINGS ARE PUBLIC. `_coins` is exported ledger
+ * state, so every coin it holds is readable off-chain in plaintext (nonce,
+ * color, value, and Merkle index) as are the cumulative `_received` and
+ * `_sent` totals. "Shielded" here refers to the token rail, not to the
+ * treasury's balance: individual transfers are shielded, but what this
+ * contract holds is not. Anyone can observe the treasury's balance per color
+ * and identify the exact UTXO backing it.
+ *
+ * Storing the coin is what buys the convenience: the contract can spend later
+ * without the caller supplying the UTXO. If public holdings are unacceptable,
+ * use `ShieldedTreasuryStateless`, which stores nothing and has the operator
+ * supply the coin at spend time.
+ *
  * Underscore-prefixed circuits (_deposit, _send) have no access control
  * enforcement. The consuming contract must gate these behind its own
  * authorization policy.
@@ -42,9 +55,13 @@ module ShieldedTreasury {
    * The coin is then merged with any existing coin of the same color,
    * or inserted as a new entry if no coin of that color exists.
    *
-   * Zero-value deposits are permitted. While currently a no-op
-   * economically, they may serve as signaling mechanisms when events
-   * are supported, or as decoy transactions for privacy.
+   * Zero-value deposits are permitted and are not always a no-op. On a color the
+   * treasury does not yet hold, a zero-value coin is inserted and occupies that
+   * color's single slot until a later deposit merges into it; if a coin of that
+   * color already exists, the zero merges into it via `mergeCoinImmediate` and
+   * the stored value is unchanged. They may serve as signaling mechanisms when
+   * events are supported. They are not useful as privacy decoys, this
+   * treasury's holdings are public (see the module header).
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -85,8 +102,18 @@ module ShieldedTreasury {
    * @description Sends shielded tokens from the treasury.
    *
    * Looks up the stored coin by color, verifies sufficient value,
-   * and executes the shielded send. If the send produces change,
-   * it is sent back to the contract via `sendImmediateShielded`.
+   * and executes the shielded send. `sendShielded` already routes any
+   * change back to this contract as a self-owned output. Unlike the
+   * stateless variant, this treasury RETAINS the change: it is recorded in
+   * the UTXO map for the next spend. The returned `result.change` therefore
+   * belongs to the treasury and must not be re-spent by the caller (doing
+   * so would double-spend the recorded coin).
+   *
+   * @notice The returned `ShieldedSendResult` carries the sent and change coins
+   * in plaintext, so sinking it (returning it from an entry point, writing it
+   * to ledger, passing it cross-contract) discloses them. `_coins` publishes only
+   * the retained change coin, and nothing at all when the send leaves no change,
+   * so the sent coin's plaintext is disclosed beyond anything in public state.
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -119,14 +146,13 @@ module ShieldedTreasury {
 
     const result = sendShielded(coin, disclose(recipient), disclose(amount));
 
+    // `sendShielded` spends the stored coin (revealing its nullifier) and,
+    // when there is change, emits it as a fresh output owned by this
+    // contract. That change coin is already spendable. Do NOT re-spend it
+    // with `sendImmediateShielded`, which would reveal its nullifier in this
+    // same transaction and leave the recorded coin permanently double-spent.
     if (disclose(result.change.is_some)) {
-      const changeCoin = result.change.value;
-      sendImmediateShielded(
-        changeCoin,
-        Utils_selfAsRecipient(),
-        changeCoin.value
-      );
-      _coins.insertCoin(disclose(color), changeCoin, Utils_selfAsRecipient());
+      _coins.insertCoin(disclose(color), result.change.value, Utils_selfAsRecipient());
     } else {
       _coins.remove(disclose(color));
     }
@@ -191,6 +217,13 @@ module ShieldedTreasury {
    * and cumulative sent totals for a color. Should equal
    * `getTokenBalance` if accounting is consistent.
    *
+   * @notice The subtraction is unguarded. `_send` cannot drive the sent total
+   * past the received total. Change re-insertion never increments `_received`
+   * so the invariant holds for any consumer that goes through `_deposit` and
+   * `_send`. A consumer that writes the exported `_coins` directly can break
+   * it, and this circuit then fails as an unprovable range violation rather
+   * than a named assert.
+   *
    * @param {Bytes<32>} color - The token color.
    *
    * @returns {Uint<128>} Received minus sent.

package/multisig/ShieldedTreasuryStateless.compact

@@ -1,26 +1,41 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ShieldedTreasuryStateless.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (multisig/ShieldedTreasuryStateless.compact)
 
 pragma language_version >= 0.23.0;
 
 /**
- * @module ShieldedTreasury
- * @description Manages shielded (private) token deposits, accounting,
- * and transfers for multisig governance contracts.
+ * @module ShieldedTreasuryStateless
+ * @description Manages shielded (private) token deposits and transfers for
+ * multisig governance contracts, without any ledger state.
  *
- * Coins are stored on the contract ledger in a map keyed by token color,
- * with one UTXO per color. Deposits are merged with existing coins of
- * the same color via `mergeCoinImmediate`. This simplifies coin selection
- * at spend time — the executor doesn't need to choose between multiple
- * UTXOs of the same color.
+ * This module holds NO state: no coin map, no balances, no received/sent
+ * totals. Deposits call `receiveShielded` only, and spends take the coin as a
+ * circuit parameter. The operator discovers coin indices from `ZswapOutput`
+ * events via the indexer, constructs the `QualifiedShieldedCoinInfo` off-chain,
+ * and supplies it at spend time. Coin data therefore never reaches the public
+ * ledger, and there is no on-chain balance to query — contrast
+ * `ShieldedTreasury`, which stores one merged UTXO per color and tracks
+ * cumulative totals.
  *
- * Cumulative received and sent totals are tracked per color for audit
- * purposes. The canonical balance query is `getTokenBalance`, which
- * reads the actual coin value from the UTXO map.
+ * @notice Because nothing is tracked on-chain, this module cannot detect a
+ * double spend or a coin it does not own; the protocol rejects both at
+ * application time. Sufficiency is likewise enforced by `sendShielded` rather
+ * than by an assert here.
+ *
+ * @notice "No ledger state" is not the same as "unobservable". A coin
+ * commitment is a hash of the coin's data, so `sendShielded` can link a coin
+ * receive to its later spend; `_send` declares that disclosure on the
+ * consumer's behalf. Consumers that need to make the trade-off themselves
+ * should note it is only declared here for convenience — it could be moved to
+ * the caller. Separately, see `_send`'s warning about its return value, which
+ * carries coin plaintext.
+ *
+ * Underscore-prefixed circuits (_deposit, _send) have no access control
+ * enforcement. The consuming contract must gate these behind its own
+ * authorization policy.
  */
 module ShieldedTreasuryStateless {
   import CompactStandardLibrary;
-  import { selfAsRecipient } from "../utils/Utils" prefix Utils_;
 
   // ─── Deposit ────────────────────────────────────────────────────
 
@@ -38,10 +53,27 @@ module ShieldedTreasuryStateless {
    *
    * The coin is supplied by the caller rather than looked up from
    * on-chain state; the token color is derived from `coin.color`.
-   * Executes the shielded send and, if change is produced, returns it
-   * to the contract via `sendImmediateShielded`. No balance or
+   * Executes the shielded send and returns the result untouched.
+   * `sendShielded` already routes any change back to this contract as a
+   * self-owned output, so `result.change` is a live, spendable coin. The
+   * implementing contract chooses what to do with it: retain it off-chain and
+   * pass it back as the `coin` for a later spend, or spend it onward to a
+   * different recipient in the same transaction via `sendImmediateShielded`.
+   * (Re-spending change is only meaningful when it goes somewhere other than
+   * self — `sendShielded` already routes it to self.) No balance or
    * received/sent accounting is tracked on the ledger.
    *
+   * @warning The returned `ShieldedSendResult` holds the sent and change coins
+   * in plaintext (`nonce`, `color`, `value`). Consuming it in-circuit is safe
+   * (passing `result.change` to `sendImmediateShielded`, for instance). Returning
+   * it from your entry point, writing it to ledger, or passing it to another
+   * contract publishes those coin details, including the amount left over from
+   * the coin that was spent. Note the compiler will NOT stop you: the
+   * `disclose` calls below clear the witness taint, so such a return compiles
+   * with no `disclose` of your own and no marker at the disclosure site. If you
+   * do not need in-circuit change handling, ignore the result. The change is
+   * recoverable off-chain from the transaction's private proving state.
+   *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
    * authorization policy.
@@ -63,14 +95,15 @@ module ShieldedTreasuryStateless {
   ): ShieldedSendResult {
     const result = sendShielded(disclose(coin), disclose(recipient), disclose(amount));
 
-    if (disclose(result.change.is_some)) {
-      sendImmediateShielded(
-        disclose(result.change.value),
-        Utils_selfAsRecipient(),
-        disclose(result.change.value.value)
-      );
-    }
-
+    // `sendShielded` already emits any change as a fresh, self-owned output.
+    // `_send` returns it untouched: it must not re-spend the change here and
+    // then hand that same (now-nullified) coin back via `result.change`. That
+    // is the double spend a node rejects on the next spend. The implementing
+    // contract decides what to do with the returned change: retain it off-chain
+    // and spend it later, or route it onward itself. The rule is only that the
+    // change must never be re-spent AND still treated as held. "Retain" means
+    // off-chain. This module keeps no state, and writing the coin to ledger
+    // would publish its nonce, color, and value.
     return result;
   }
 }