@openzeppelin/compact-contracts 0.4.0-alpha.6 → 0.4.0

package/multisig/presets/NativeShieldedTokenIssuer.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (multisig/presets/NativeShieldedTokenIssuer.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/presets/NativeShieldedTokenIssuer.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -183,7 +183,10 @@ pragma language_version >= 0.26.0;
  * Mint and burn only. No send, transfer or execute circuit exists, so
  * contract-held coins (from `mintToSelf` or `burnFromSelf` change) leave only
  * through `burnFromSelf`, supplied by the operator as
- * `QualifiedShieldedCoinInfo`. Coins minted to users are ordinary
+ * `QualifiedShieldedCoinInfo`. Moving such a coin anywhere else needs a
+ * custody module composed by the consumer that records the coin without
+ * claiming it a second time; `ShieldedTreasury._deposit` is not that module
+ * today (compact-contracts#1112). Coins minted to users are ordinary
  * Zswap coins the contract neither tracks nor restricts; a holder redeems by
  * paying the coin into a `burn` tx. No supply accounting.
  *

package/multisig/presets/ShieldedMultiSigV2.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (multisig/presets/ShieldedMultiSigV2.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (multisig/presets/ShieldedMultiSigV2.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -25,6 +25,13 @@ pragma language_version >= 0.26.0;
  * through ZswapOutput events from the indexer, constructs QualifiedShieldedCoinInfo
  * off-chain, and provides it as a circuit parameter for spending.
  *
+ * @notice Keeping coin data off the ledger hides balances from the public,
+ * not from a depositor. Whoever knows a deposited coin can find the `execute`
+ * that spends it, recover the amount sent, test candidate recipients against
+ * the sent coin's commitment, and derive the change coin, so every later
+ * spend descending from that change and the balance it carries are traceable
+ * by that depositor. See `ShieldedTreasuryStateless` for the derivation.
+ *
  * @notice Requires ZKIR v3: `keccak256` is unavailable on the v2 backend.
  *
  * @notice Implementing contracts register the signer set from their
@@ -37,13 +44,11 @@ module ShieldedMultiSigV2<#t> {
   import "../Secp256k1EcdsaMultisig"<t> prefix Secp256k1EcdsaMultisig_;
   import "../../crypto/Eip712" prefix Eip712_;
   import "../../utils/EvmAbi" prefix EvmAbi_;
-  import "../ProposalManager" prefix Proposal_;
+  import "../RecipientTypes";
   import "../ShieldedTreasuryStateless" prefix Treasury_;
 
-  // Implementing contracts need this for the re-exported `execute` signature.
-  // Importing `ProposalManager` again instead would give them a second,
-  // unwritten copy of its state.
-  export { Proposal_Recipient };
+  // Implementing contracts need these for the re-exported `execute` signature.
+  export { Recipient, RecipientKind };
 
   /**
    * @description Monotonic operation counter. `execute` reads it as that
@@ -132,7 +137,8 @@ module ShieldedMultiSigV2<#t> {
    *
    * No access control which allows anyone to deposit. The coin is claimed at the
    * protocol level through receiveShielded. No coin data is stored on the
-   * public ledger, preserving full balance privacy.
+   * public ledger, so no balance is readable from it; a depositor can still
+   * follow the coin they deposited (see the module notice).
    *
    * The operator discovers the coin's Merkle tree index by subscribing
    * to ZswapOutput events via the indexer, filtering by contract address,
@@ -175,7 +181,7 @@ module ShieldedMultiSigV2<#t> {
    * - `to.kind` must be `ShieldedUser`.
    * - Coin value must be >= amount.
    *
-   * @param {Proposal_Recipient} to - The recipient.
+   * @param {Recipient} to - The recipient.
    * @param {Uint<128>} amount - The amount to send.
    * @param {QualifiedShieldedCoinInfo} coin - The coin to spend (from operator's pool).
    * @param {Vector<t, Secp256k1Point>} pubkeys - Public keys of approving signers.
@@ -184,7 +190,7 @@ module ShieldedMultiSigV2<#t> {
    * @returns {ShieldedSendResult} The send result including any change.
    */
   export circuit execute(
-    to: Proposal_Recipient,
+    to: Recipient,
     amount: Uint<128>,
     coin: QualifiedShieldedCoinInfo,
     pubkeys: Vector<t, Secp256k1Point>,
@@ -211,7 +217,7 @@ module ShieldedMultiSigV2<#t> {
     Secp256k1EcdsaMultisig_assertApprovals(msgHash, pubkeys, signatures);
 
     assert(
-      to.kind == Proposal_RecipientKind.ShieldedUser,
+      to.kind == RecipientKind.ShieldedUser,
       "ShieldedMultiSigV2: recipient must be a coin public key"
     );
     const recipient = left<ZswapCoinPublicKey, ContractAddress>(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openzeppelin/compact-contracts",
-  "version": "0.4.0-alpha.6",
+  "version": "0.4.0",
   "description": "OpenZeppelin Compact contract library",
   "keywords": [
     "openzeppelin",

package/security/Allowlist.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (security/Allowlist.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (security/Allowlist.compact)
 
 pragma language_version >= 0.26.0;
 

package/security/Blocklist.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (security/Blocklist.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (security/Blocklist.compact)
 
 pragma language_version >= 0.26.0;
 

package/security/Initializable.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (security/Initializable.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (security/Initializable.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -35,8 +35,6 @@ module Initializable {
   /**
    * @description Initializes the state thus ensuring the calling circuit can only be called once.
    *
-   * @constraints k=6, rows=28
-   *
    * Requirements:
    *
    * - Contract must not be initialized.

package/security/Pausable.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (security/Pausable.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (security/Pausable.compact)
 
 pragma language_version >= 0.26.0;
 

package/token/ConfidentialFungibleToken.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/ConfidentialFungibleToken.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/ConfidentialFungibleToken.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -28,6 +28,16 @@ pragma language_version >= 0.26.0;
  * (`extensions/ConfidentialFungibleTokenPublicSupply`) a composing contract pairs
  * with them if it wants a tracked supply.
  *
+ * @notice Allowances. `approve` funds the allowance at approve time: `value`
+ * moves out of the caller's spendable balance into the escrow, where it stays
+ * until spent or re-approved. Funding is required, not a choice: the spender
+ * holds no owner encryption key, so at spend time it can only prove against
+ * its own escrow copy, never that the owner's balance covers the allowance.
+ * An approve conserves the owner's holdings (spendable plus every outstanding
+ * escrow), so allowances across spenders can sum to the whole holding but
+ * never exceed it, and a re-approve replaces the prior one rather than
+ * stacking.
+ *
  * @notice Single-receiver. Auditor support, freeze, and admin-style seize are
  * deliberately left to companion modules or a future multi-receiver variant.
  * The escrow-spend primitive here (`_spendEscrow`) enables user-consenting
@@ -35,6 +45,9 @@ pragma language_version >= 0.26.0;
  * requires authority visibility into balances and is therefore out of scope
  * for the single-receiver base.
  *
+ * @dev Initialization. Every exported circuit except `initialize` asserts the
+ * contract is initialized.
+ *
  * @dev Trust model for witnesses.
  *
  * Witness implementations live in the user's wallet (TypeScript frontend) and
@@ -390,7 +403,9 @@ module ConfidentialFungibleToken {
   /**
    * @description Escrowed allowances, keyed by owner then spender. Membership is
    * checked independently of the entry, so an allowance that was never escrowed
-   * is unspendable.
+   * is unspendable. A spend also requires both owner and spender to be
+   * registered, so an entry written here for an unregistered account (for
+   * example by a composing contract) is unspendable as well.
    * @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.
@@ -618,25 +633,37 @@ module ConfidentialFungibleToken {
 
   /**
    * @description Returns the escrow entry (the encrypted allowance) that `owner`
-   * granted `spender`. When no allowance exists, returns a well-formed
-   * encrypted-zero entry (its encrypted amounts decrypt to 0, analogous to an
-   * ERC-20 zero allowance) rather than `default<EscrowEntry>`: the returned
-   * Jubjub points are on-curve, so the view is safe to prove (e.g. through a
-   * contract-to-contract call) and safe for a wallet to decrypt, whereas a zeroed
-   * default holds off-curve points. The cap is encrypted, not public.
+   * granted `spender`. When no allowance exists, returns a placeholder entry
+   * rather than `default<EscrowEntry>`: the returned Jubjub points are on-curve,
+   * so the view is safe to prove (e.g. through a contract-to-contract call),
+   * whereas a zeroed default holds off-curve points. The cap is encrypted, not
+   * public.
+   *
+   * @notice The placeholder's `spenderCt` and `ownerCt` are genuine encryptions
+   * of 0. Its `ownerMemo` is not: it is a sentinel for an absent allowance,
+   * recognised by `ephemeralPk == identity`, which `EcdhMask_encrypt` never
+   * produces and `EcdhMask_decrypt` rejects. A wallet must test for the
+   * sentinel rather than decrypt and narrow it.
+   *
+   * @notice "No allowance" and "an allowance of 0" both read as encrypted-zero in
+   * the amount fields; the memo sentinel tells them apart, since `approve` stores
+   * a real memo even for 0. This getter grants nothing, the spend path
+   * (`transferFrom`/`burnFrom`) gates on `_escrow` membership independently, so a
+   * non-existent allowance is unspendable.
+   *
+   * @constraints k=10, rows=938
    *
-   * @notice "No allowance" and "an allowance of 0" both read as encrypted-zero;
-   * a caller that must distinguish them reads `_escrow` membership off-chain. This
-   * getter grants nothing, the spend path (`transferFrom`/`burnFrom`) gates on
-   * `_escrow` membership independently, so a non-existent allowance is unspendable.
+   * Requirements:
    *
-   * @constraints k=10, rows=936
+   * - Contract is initialized.
    *
    * @param {Bytes<32>} owner - The account that granted the allowance.
    * @param {Bytes<32>} spender - The approved spender.
-   * @return {EscrowEntry} - The encrypted escrow entry (encrypted-zero if none).
+   * @return {EscrowEntry} - The encrypted escrow entry (a placeholder with the
+   * absent-allowance sentinel if none).
    */
   export circuit allowance(owner: Bytes<32>, spender: Bytes<32>): EscrowEntry {
+    assertInitialized();
     if (!_escrow.member(disclose(owner)) ||
         !_escrow.lookup(disclose(owner)).member(disclose(spender))) {
       const id = constructJubjubPoint(0 as Field, 1 as Field);
@@ -656,12 +683,17 @@ module ConfidentialFungibleToken {
   /**
    * @description Returns whether `account` has registered an encryption key.
    *
-   * @constraints k=9, rows=303
+   * @constraints k=9, rows=305
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
    *
    * @param {Bytes<32>} account - The account to query.
    * @return {Boolean} - True if `account` is registered.
    */
   export circuit isRegistered(account: Bytes<32>): Boolean {
+    assertInitialized();
     return _encryptionKeys.member(disclose(account));
   }
 
@@ -812,6 +844,12 @@ module ConfidentialFungibleToken {
    * `sum(balances) == totalSupply` invariant. Pair it with a debit (as `transfer`
    * does) or a supply increase (as a supply layer's `mint` does).
    *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   * - `value` is within `MAX_TRANSFER_VALUE()`.
+   * - `account` is non-zero and registered.
+   *
    * @param account - The recipient account id.
    * @param value - The amount to credit.
    */
@@ -928,7 +966,7 @@ module ConfidentialFungibleToken {
    * credits `to`, and pushes an encrypted memo to `to`. The amount is hidden;
    * the (sender, recipient) pair is public.
    *
-   * @constraints k=16, rows=41623
+   * @constraints k=16, rows=41621
    *
    * @notice Returns the caller's (sender's) `accountId` for caller-side gating.
    * The sender is derived from the same authentication `_debit` performs, so the
@@ -946,7 +984,6 @@ module ConfidentialFungibleToken {
    * @return {Bytes<32>} - The caller's (sender's) accountId.
    */
   export circuit transfer(to: Bytes<32>, value: Uint<128>): Bytes<32> {
-    assertInitialized();
     // Derive the sender from the same authentication `_debit` uses, so the
     // returned id is exactly the account whose funds moved.
     const senderId = _debit(value);
@@ -966,7 +1003,7 @@ module ConfidentialFungibleToken {
    * operations (`mint`/`burn`) live in a separate layer outside this conserving
    * surface, and only they may break conservation.
    *
-   * @constraints k=16, rows=41612
+   * @constraints k=16, rows=41610
    *
    * @notice Like `transfer`, the credit lands in the recipient's pending pool
    * (see the dual-balance note); the caller sweeps their own incoming value.
@@ -992,7 +1029,6 @@ module ConfidentialFungibleToken {
    * @return {Bytes<32>} - The caller's accountId (for caller-side gating).
    */
   export circuit _move(to: Bytes<32>, value: Uint<128>): Bytes<32> {
-    assertInitialized();
     const senderId = _debit(value);
     _credit(to, value);
     return senderId;
@@ -1125,7 +1161,7 @@ module ConfidentialFungibleToken {
    * caller via `approve`) and credits it to `to`, reducing both escrow copies by
    * `value`. The amount is hidden.
    *
-   * ???? @constraints k=17, rows=68920
+   * @constraints k=17, rows=68922
    *
    * @notice Returns the caller's (spender's) `accountId` for caller-side gating.
    *
@@ -1135,6 +1171,7 @@ module ConfidentialFungibleToken {
    * - `value` is within `MAX_TRANSFER_VALUE()`.
    * - `to` is registered and is not the zero account.
    * - An escrow from `fromAddress` to the caller exists with at least `value`.
+   * - `fromAddress` and the caller are registered.
    *
    * @param {Bytes<32>} fromAddress - The owner whose escrow is drawn on.
    * @param {Bytes<32>} to - The recipient account.
@@ -1146,7 +1183,6 @@ module ConfidentialFungibleToken {
                    to: Bytes<32>,
                    value: Uint<128>
                    ): Bytes<32> {
-    assertInitialized();
     _assertValueInBound(value);
     assert(to != default<Bytes<32>>,
            "ConfidentialFungibleToken: invalid receiver");
@@ -1299,6 +1335,13 @@ module ConfidentialFungibleToken {
    * not prove the post-refund balance on a later re-approve/revoke. See the
    * `EscrowEntry` field doc.
    *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   * - `value` is within `MAX_TRANSFER_VALUE()`.
+   * - An escrow from `fromAddress` to the caller exists with at least `value`.
+   * - `fromAddress` and the caller are registered.
+   *
    * @param fromAddress - The owner whose escrow the caller (spender) draws on.
    * @param value - The amount to consume from the allowance.
    */
@@ -1310,6 +1353,10 @@ module ConfidentialFungibleToken {
     assert(_escrow.member(disclose(fromAddress)) &&
            _escrow.lookup(disclose(fromAddress)).member(disclose(spenderId)),
            "ConfidentialFungibleToken: no escrow");
+    assert(_encryptionKeys.member(disclose(spenderId)),
+           "ConfidentialFungibleToken: spender not registered");
+    assert(_encryptionKeys.member(disclose(fromAddress)),
+           "ConfidentialFungibleToken: owner not registered");
 
     const entry = _escrow.lookup(disclose(fromAddress)).lookup(disclose(spenderId));
 
@@ -1374,13 +1421,14 @@ module ConfidentialFungibleToken {
    * recipient credit. The building block for a composing contract's
    * `burnFrom`; it performs no supply accounting (see `_burn`).
    *
-   * ???? @constraints k=16, rows=42201
+   * @constraints k=16, rows=42205
    *
    * Requirements:
    *
    * - Contract is initialized.
    * - `value` is within `MAX_TRANSFER_VALUE()`.
    * - An escrow from `fromAddress` to the caller exists with at least `value`.
+   * - `fromAddress` and the caller are registered.
    *
    * @param {Bytes<32>} fromAddress - The owner whose escrow is consumed.
    * @param {Uint<128>} value - The amount to burn.

package/token/FungibleToken.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/FungibleToken.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/FungibleToken.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -130,8 +130,6 @@ module FungibleToken {
    * @dev This MUST be called in the implementing contract's constructor. Failure to do so
    * can lead to an irreparable contract.
    *
-   * @constraints k=10, rows=71
-   *
    * @param {Opaque<"string">} name_ - The name of the token.
    * @param {Opaque<"string">} symbol_ - The symbol of the token.
    * @param {Uint<8>} decimals_ - The number of decimals used to get the user representation.

package/token/MultiToken.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/MultiToken.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/MultiToken.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -176,8 +176,6 @@ module MultiToken {
   /**
    * @description Initializes the contract by setting the base URI for all tokens.
    *
-   * @constraints k=6, rows=31
-   *
    * Requirements:
    *
    * - Must be called in the contract's constructor.

package/token/NativeShieldedToken.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/NativeShieldedToken.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/NativeShieldedToken.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -230,7 +230,13 @@ module NativeShieldedToken {
    *
    * @notice The consumer SHOULD persist the returned coin info in its own
    * ledger state: it is the contract's holding and is not otherwise
-   * recoverable.
+   * recoverable. The coin is already claimed as a receive by the mint, so a
+   * custody module must record it without calling `receiveShielded` on it
+   * again (see the recipient-arm note in `NativeShieldedTokenCore`).
+   * `ShieldedTreasury._deposit` claims on the way in and is not that path;
+   * a record-only circuit is tracked in compact-contracts#1112. Until a
+   * custody module is composed, the only spend of a contract-held coin is
+   * `_burnFromSelf`.
    *
    * @constraints k=14, rows=10221
    *
@@ -310,7 +316,9 @@ module NativeShieldedToken {
    *
    * @dev The consumer SHOULD persist the returned change coin info in its own
    * ledger state: the change replaces `coin` as the contract's holding, and
-   * its info is not otherwise recoverable.
+   * its info is not otherwise recoverable. Like a `_mintToSelf` coin, the
+   * change is already claimed as a receive, so a custody module must record
+   * it without a second `receiveShielded`.
    *
    * @constraints k=15, rows=23208
    *

package/token/NativeShieldedTokenCore.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/NativeShieldedTokenCore.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/NativeShieldedTokenCore.compact)
 
 pragma language_version >= 0.26.0;
 

package/token/NativeShieldedTokenFamily.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/NativeShieldedTokenFamily.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/NativeShieldedTokenFamily.compact)
 
 pragma language_version >= 0.26.0;
 

package/token/NonFungibleToken.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/NonFungibleToken.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/NonFungibleToken.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -165,8 +165,6 @@ module NonFungibleToken {
    * This MUST be called in the implementing contract's constructor.
    * Failure to do so can lead to an irreparable contract.
    *
-   * @constraints k=6, rows=52
-   *
    * Requirements:
    *
    * - Contract is not initialized.

package/token/examples/ZOwnableNativeShieldedTokenExample.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/examples/ZOwnableNativeShieldedTokenExample.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/examples/ZOwnableNativeShieldedTokenExample.compact)
 
 pragma language_version >= 0.26.0;
 

package/token/extensions/ConfidentialFungibleTokenPublicSupply.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/extensions/ConfidentialFungibleTokenPublicSupply.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/extensions/ConfidentialFungibleTokenPublicSupply.compact)
 
 pragma language_version >= 0.26.0;
 

package/token/extensions/NativeShieldedTokenDerivedNonce.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (token/extensions/NativeShieldedTokenDerivedNonce.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (token/extensions/NativeShieldedTokenDerivedNonce.compact)
 
 pragma language_version >= 0.26.0;
 

package/utils/EvmAbi.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (utils/EvmAbi.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (utils/EvmAbi.compact)
 
 pragma language_version >= 0.26.0;
 

package/utils/Utils.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.6 (utils/Utils.compact)
+// OpenZeppelin Compact Contracts v0.4.0 (utils/Utils.compact)
 
 pragma language_version >= 0.26.0;