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

package/token/NonFungibleToken.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (token/NonFungibleToken.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (token/NonFungibleToken.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -58,7 +58,7 @@ pragma language_version >= 0.26.0;
  * or in ledger writes. Canonicalization zeroes out the inactive branch of the Either,
  * ensuring that two values with the same active branch always resolve to the same map key
  * regardless of what data the inactive branch carries. Write paths are canonicalized in
- * `_update` (for `_owners` and `_balances`), `_approve` (for `_tokenApprovals`), and
+ * `_update` (for `_owners` and `_balances`), `_unsafeApprove` (for `_tokenApprovals`), and
  * `_setApprovalForAll` (for `_operatorApprovals`). Read paths are canonicalized in
  * `balanceOf`, `isApprovedForAll`, and `_isAuthorized`.
  *
@@ -85,8 +85,13 @@ module NonFungibleToken {
   import CompactStandardLibrary;
   import "../utils/Utils" prefix Utils_;
 
-  /// Public state
+  /**
+   * @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">;
 
   /**
@@ -160,7 +165,7 @@ module NonFungibleToken {
    * This MUST be called in the implementing contract's constructor.
    * Failure to do so can lead to an irreparable contract.
    *
-   * @circuitInfo k=6, rows=52
+   * @constraints k=6, rows=52
    *
    * Requirements:
    *
@@ -206,7 +211,7 @@ module NonFungibleToken {
   /**
    * @description Returns the number of tokens in `owner`'s account.
    *
-   * @circuitInfo k=10, rows=673
+   * @constraints k=10, rows=671
    *
    * Requirements:
    *
@@ -229,7 +234,7 @@ module NonFungibleToken {
   /**
    * @description Returns the owner of the `tokenId` token.
    *
-   * @circuitInfo k=9, rows=333
+   * @constraints k=9, rows=331
    *
    * Requirements:
    *
@@ -247,7 +252,7 @@ module NonFungibleToken {
   /**
    * @description Returns the token name.
    *
-   * @circuitInfo k=6, rows=28
+   * @constraints k=6, rows=26
    *
    * Requirements:
    *
@@ -263,7 +268,7 @@ module NonFungibleToken {
   /**
    * @description Returns the symbol of the token.
    *
-   * @circuitInfo k=6, rows=28
+   * @constraints k=6, rows=26
    *
    * Requirements:
    *
@@ -280,7 +285,7 @@ module NonFungibleToken {
    * @description Returns the token URI for the given `tokenId`. Returns the empty
    * string if a tokenURI does not exist.
    *
-   * @circuitInfo k=9, rows=326
+   * @constraints k=9, rows=324
    *
    * Requirements:
    *
@@ -309,7 +314,7 @@ module NonFungibleToken {
   /**
    * @description Sets the URI as `tokenURI` for the given `tokenId`.
    *
-   * @circuitInfo k=9, rows=289
+   * @constraints k=9, rows=287
    *
    * Requirements:
    *
@@ -338,7 +343,7 @@ module NonFungibleToken {
    * In the case of an external (non-contract) caller, the caller's identity is derived from the `wit_NonFungibleTokenSK`
    * witness as `persistentHash(secretKey)`.
    *
-   * @circuitInfo k=13, rows=3468
+   * @constraints k=13, rows=3406
    *
    * Requirements:
    *
@@ -359,7 +364,7 @@ module NonFungibleToken {
   /**
    * @description Returns the account approved for `tokenId` token.
    *
-   * @circuitInfo k=9, rows=422
+   * @constraints k=9, rows=420
    *
    * Requirements:
    *
@@ -383,7 +388,7 @@ module NonFungibleToken {
    * In the case of an external (non-contract) caller, the caller's identity is derived from the `wit_NonFungibleTokenSK`
    * witness as `persistentHash(secretKey)`.
    *
-   * @circuitInfo k=13, rows=2936
+   * @constraints k=13, rows=2938
    *
    * Requirements:
    *
@@ -406,7 +411,7 @@ module NonFungibleToken {
   /**
    * @description Returns if the `operator` is allowed to manage all of the assets of `owner`.
    *
-   * @circuitInfo k=11, rows=1343
+   * @constraints k=11, rows=1341
    *
    * Requirements:
    *
@@ -439,7 +444,7 @@ module NonFungibleToken {
    * In the case of an external (non-contract) caller, the caller's identity is derived from the `wit_NonFungibleTokenSK`
    * witness as `persistentHash(secretKey)`.
    *
-   * @circuitInfo k=13, rows=4800
+   * @constraints k=13, rows=4702
    *
    * Requirements:
    *
@@ -477,7 +482,7 @@ module NonFungibleToken {
    * are not currently supported. Tokens sent to a contract address may become irretrievable.
    * Once contract-to-contract calls are supported, this circuit may be deprecated.
    *
-   * @circuitInfo k=13, rows=4797
+   * @constraints k=13, rows=4699
    *
    * Requirements:
    *
@@ -499,11 +504,14 @@ module NonFungibleToken {
                    ): [] {
     assertInitialized();
     assert(!Utils_isTargetZero(to), "NonFungibleToken: invalid receiver");
-    // Setting an "auth" argument enables the `_isAuthorized` check which verifies that the token exists
-    // (fromAddress != 0). Therefore, it is not needed to verify that the return value is not 0 here.
     const auth = left<Bytes<32>, ContractAddress>(_computeAccountId());
     const previousOwner = _update(to, tokenId, auth);
 
+    // The `_isAuthorized` check inside `_update` already implies the token exists, but that
+    // holds only while approvals are never recorded for unminted tokens. Assert it directly
+    // so a misused `_unsafeApprove` cannot turn this circuit into an unauthorized mint.
+    assert(!Utils_isTargetZero(previousOwner), "NonFungibleToken: nonexistent token");
+
     const canonFrom = Utils_canonicalize<Bytes<32>, ContractAddress>(fromAddress);
     assert(previousOwner == canonFrom, "NonFungibleToken: incorrect owner");
   }
@@ -511,7 +519,7 @@ module NonFungibleToken {
   /**
    * @description Returns the owner of the `tokenId`. Does NOT revert if token doesn't exist.
    *
-   * @circuitInfo k=9, rows=308
+   * @constraints k=9, rows=306
    *
    * Requirements:
    *
@@ -532,7 +540,7 @@ module NonFungibleToken {
   /**
    * @description Returns the approved address for `tokenId`. Returns the zero value if `tokenId` is not minted.
    *
-   * @circuitInfo k=9, rows=308
+   * @constraints k=9, rows=306
    *
    * Requirements:
    *
@@ -553,7 +561,7 @@ module NonFungibleToken {
    * @description Returns whether `spender` is allowed to manage `owner`'s tokens, or `tokenId` in
    * particular (ignoring whether it is owned by `owner`).
    *
-   * @circuitInfo k=11, rows=1798
+   * @constraints k=11, rows=1796
    *
    * Requirements:
    *
@@ -585,7 +593,7 @@ module NonFungibleToken {
   /**
    * @description Checks if `spender` can operate on `tokenId`, assuming the provided `owner` is the actual owner.
    *
-   * @circuitInfo k=11, rows=1804
+   * @constraints k=11, rows=1802
    *
    * Requirements:
    *
@@ -643,8 +651,8 @@ module NonFungibleToken {
 
     // Execute the update
     if (!Utils_isTargetZero(disclose(fromAddress))) {
-      // Clear approval. No need to re-authorize
-      _approve(Utils_zeroAccount(), tokenId, Utils_zeroAccount());
+      // Clear approval. No need to re-authorize or re-read the owner
+      _unsafeApprove(Utils_zeroAccount(), tokenId, Utils_zeroAccount(), false);
       const canonFrom = Utils_canonicalize<Bytes<32>, ContractAddress>(fromAddress);
       const newBalance = _balances.lookup(disclose(canonFrom)) - 1 as Uint<128>;
       _balances.insert(disclose(canonFrom), disclose(newBalance));
@@ -666,7 +674,7 @@ module NonFungibleToken {
   /**
    * @description Mints `tokenId` and transfers it to `to`.
    *
-   * @circuitInfo k=11, rows=1473
+   * @constraints k=11, rows=1388
    *
    * Requirements:
    *
@@ -690,7 +698,7 @@ module NonFungibleToken {
   /**
    * @description Mints `tokenId` and transfers it to `to`. It does NOT check if the recipient is a ContractAddress.
    *
-   * @circuitInfo k=11, rows=1470
+   * @constraints k=11, rows=1385
    *
    * Requirements:
    *
@@ -723,7 +731,7 @@ module NonFungibleToken {
    * The approval is cleared when the token is burned.
    * This circuit does not check if the sender is authorized to operate on the token.
    *
-   * @circuitInfo k=10, rows=509
+   * @constraints k=10, rows=507
    *
    * Requirements:
    *
@@ -748,7 +756,7 @@ module NonFungibleToken {
    * interactions are supported in Compact. This restriction prevents assets from being inadvertently
    * locked in contracts that cannot currently handle token receipt.
    *
-   * @circuitInfo k=12, rows=2067
+   * @constraints k=11, rows=1982
    *
    * Requirements:
    *
@@ -779,7 +787,7 @@ module NonFungibleToken {
    * As opposed to {_unsafeTransferFrom}, this imposes no restrictions on the caller's identity.
    * It does NOT check if the recipient is a ContractAddress.
    *
-   * @circuitInfo k=12, rows=2064
+   * @constraints k=11, rows=1979
    *
    * Requirements:
    *
@@ -815,11 +823,12 @@ module NonFungibleToken {
   /**
    * @description Approve `to` to operate on `tokenId`.
    *
-   * @circuitInfo k=11, rows=1810
+   * @constraints k=11, rows=1755
    *
    * Requirements:
    *
    * - The contract is initialized.
+   * - `tokenId` must exist.
    * - If `auth` is non 0, then this function will check that `auth` is either the owner of the token,
    * or approved to operate on the token (by the owner).
    *
@@ -833,6 +842,43 @@ module NonFungibleToken {
                    tokenId: Uint<128>,
                    auth: Either<Bytes<32>, ContractAddress>
                    ): [] {
+    _unsafeApprove(to, tokenId, auth, true);
+  }
+
+  /**
+   * @description Approve `to` to operate on `tokenId`, requiring the token to exist
+   * only when `isExistenceRequired` is true.
+   *
+   * @constraints k=11, rows=1868
+   *
+   * @warning Passing false skips the check that `tokenId` was minted. Both
+   * `_unsafeTransferFrom` and `_update` read that invariant back, so a planted approval
+   * can mint a token nobody authorized or outlive a later mint. Pass false only where
+   * the owner has already been read, as `_update` does.
+   *
+   * @dev Counterpart to Solidity's `_approve(to, tokenId, auth, bool emitEvent)`, where
+   * the flag also suppresses the `Approval` event. Compact has no events, so it carries
+   * the existence check alone.
+   *
+   * Requirements:
+   *
+   * - The contract is initialized.
+   * - `tokenId` must exist, unless `isExistenceRequired` is false and `auth` is zero.
+   * - If `auth` is non 0, then this function will check that `auth` is either the owner of the token,
+   * or approved to operate on the token (by the owner).
+   *
+   * @param {Either<Bytes<32>, ContractAddress>} to - The target account to approve
+   * @param {Uint<128>} tokenId - The token to approve
+   * @param {Either<Bytes<32>, ContractAddress>} auth - An account authorized to operate on all tokens held by the owner of the token
+   * @param {Boolean} isExistenceRequired - Whether `tokenId` must exist
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _unsafeApprove(
+                   to: Either<Bytes<32>, ContractAddress>,
+                   tokenId: Uint<128>,
+                   auth: Either<Bytes<32>, ContractAddress>,
+                   isExistenceRequired: Boolean
+                   ): [] {
     assertInitialized();
     // Canonicalize + normalize `to`
     const canonTo = Utils_canonicalize<Bytes<32>, ContractAddress>(to);
@@ -841,11 +887,14 @@ module NonFungibleToken {
     // Canonicalize auth
     const canonAuth = Utils_canonicalize<Bytes<32>, ContractAddress>(auth);
 
-    if (!Utils_isTargetZero(disclose(canonAuth))) {
+    // Avoid reading the owner unless necessary
+    if (disclose(isExistenceRequired) || !Utils_isTargetZero(disclose(canonAuth))) {
       const owner = _requireOwned(tokenId);
 
       // We do not use _isAuthorized because single-token approvals should not be able to call approve
-      assert((owner == disclose(canonAuth) || isApprovedForAll(owner, canonAuth)),
+      assert((Utils_isTargetZero(disclose(canonAuth)) ||
+              owner == disclose(canonAuth) ||
+              isApprovedForAll(owner, canonAuth)),
              "NonFungibleToken: invalid approver"
              );
     }
@@ -856,7 +905,7 @@ module NonFungibleToken {
   /**
    * @description Approve `operator` to operate on all of `owner` tokens.
    *
-   * @circuitInfo k=11, rows=1261
+   * @constraints k=11, rows=1280
    *
    * Requirements:
    *
@@ -895,7 +944,7 @@ module NonFungibleToken {
    * @description Reverts if the `tokenId` doesn't have a current owner (it hasn't been minted, or it has been burned).
    * Returns the owner.
    *
-   * @circuitInfo k=9, rows=331
+   * @constraints k=9, rows=329
    *
    * Requirements:
    *

package/token/extensions/ConfidentialFungibleTokenPublicSupply.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (token/extensions/ConfidentialFungibleTokenPublicSupply.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (token/extensions/ConfidentialFungibleTokenPublicSupply.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -33,15 +33,20 @@ pragma language_version >= 0.26.0;
 module ConfidentialFungibleTokenPublicSupply {
   import CompactStandardLibrary;
 
-  // The public circulating supply. Mint and burn disclose their amounts
-  // through the delta on this value.
+  /**
+   * @description Total tokens in circulation, tracked in the clear even though
+   * balances are encrypted. Raised by `_addSupply` and lowered by `_subSupply`,
+   * each rejecting over/underflow.
+   *
+   * @warning Mint and burn disclose their amounts through the delta on this value
+   */
   export ledger _totalSupply: Uint<128>;
 
   /**
    * @description Increases `totalSupply` by `value`. Call alongside the token
    * module's `_mint`. The added amount is disclosed via the supply delta.
    *
-   * @circuitInfo k=9, rows=401
+   * @constraints k=9, rows=399
    *
    * Requirements:
    *
@@ -62,7 +67,7 @@ module ConfidentialFungibleTokenPublicSupply {
    * module's `_burn` or `_burnFrom`. The removed amount is disclosed via the
    * supply delta.
    *
-   * @circuitInfo k=9, rows=256
+   * @constraints k=9, rows=254
    *
    * Requirements:
    *
@@ -80,7 +85,7 @@ module ConfidentialFungibleTokenPublicSupply {
   /**
    * @description Returns the public total token supply.
    *
-   * @circuitInfo k=6, rows=26
+   * @constraints k=6, rows=24
    *
    * @return {Uint<128>} - The total supply.
    */

package/token/extensions/NativeShieldedTokenDerivedNonce.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (token/extensions/NativeShieldedTokenDerivedNonce.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (token/extensions/NativeShieldedTokenDerivedNonce.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -59,7 +59,7 @@ module NativeShieldedTokenDerivedNonce {
    * @notice The derivation input is public ledger state, so mints using this
    * nonce are recipient-public; see the module notes.
    *
-   * @circuitInfo k=9, rows=451
+   * @constraints k=9, rows=447
    *
    * @return {Bytes<32>} - The next derived coin nonce.
    */

package/token/extensions/NativeShieldedTokenFamilyPublicSupply.compact

@@ -20,7 +20,7 @@ pragma language_version >= 0.26.0;
  *
  *   export circuit mint(
  *     domain: Bytes<32>,
- *     recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+ *     recipient: ZswapCoinPublicKey,
  *     amount: Uint<64>,
  *     nonce: Bytes<32>
  *   ): ShieldedCoinInfo {
@@ -33,7 +33,7 @@ pragma language_version >= 0.26.0;
  *     domain: Bytes<32>,
  *     coin: ShieldedCoinInfo,
  *     amount: Uint<128>,
- *     refundTo: Either<ZswapCoinPublicKey, ContractAddress>
+ *     refundTo: ZswapCoinPublicKey
  *   ): Maybe<ShieldedCoinInfo> {
  *     const refund = Family__burn(domain, coin, amount, refundTo);
  *     Supply__addBurned(domain, amount);
@@ -76,7 +76,7 @@ module NativeShieldedTokenFamilyPublicSupply {
    * @description Adds `amount` to the exact minted total for `domain`. Call
    * once per successful `NativeShieldedTokenFamily._mint`.
    *
-   * @circuitInfo k=10, rows=653
+   * @constraints k=10, rows=645
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @param {Uint<64>} amount - The minted amount.
@@ -93,7 +93,7 @@ module NativeShieldedTokenFamilyPublicSupply {
    * @dev Enforces per-domain `burned <= minted`; an unpaired, duplicate, or
    * wrong-domain burn reverts.
    *
-   * @circuitInfo k=10, rows=755
+   * @constraints k=10, rows=747
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @param {Uint<128>} amount - The burned amount.
@@ -106,7 +106,7 @@ module NativeShieldedTokenFamilyPublicSupply {
   /**
    * @description Returns the exact amount ever minted for `domain`.
    *
-   * @circuitInfo k=9, rows=344
+   * @constraints k=9, rows=342
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @return {Uint<128>} - The total amount minted.
@@ -120,7 +120,7 @@ module NativeShieldedTokenFamilyPublicSupply {
    * @notice This is a lower bound: coins sent directly to the burn address
    * without going through the contract are not counted.
    *
-   * @circuitInfo k=9, rows=341
+   * @constraints k=9, rows=339
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @return {Uint<128>} - The total amount burned through the contract.
@@ -134,7 +134,7 @@ module NativeShieldedTokenFamilyPublicSupply {
    * @notice This is an UPPER BOUND on circulating supply, not an exact value:
    * burns that bypass the contract are invisible. See the module notes.
    *
-   * @circuitInfo k=9, rows=439
+   * @constraints k=9, rows=437
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @return {Uint<128>} - The upper bound on tokens in existence.

package/token/extensions/NativeShieldedTokenPublicSupply.compact

@@ -18,7 +18,7 @@ pragma language_version >= 0.26.0;
  * pieces, calling the accounting block alongside the matching token op:
  *
  *   export circuit mint(
- *     recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+ *     recipient: ZswapCoinPublicKey,
  *     amount: Uint<64>,
  *     nonce: Bytes<32>
  *   ): ShieldedCoinInfo {
@@ -30,7 +30,7 @@ pragma language_version >= 0.26.0;
  *   export circuit burn(
  *     coin: ShieldedCoinInfo,
  *     amount: Uint<128>,
- *     refundTo: Either<ZswapCoinPublicKey, ContractAddress>
+ *     refundTo: ZswapCoinPublicKey
  *   ): Maybe<ShieldedCoinInfo> {
  *     const refund = Token__burn(coin, amount, refundTo);
  *     Supply__addBurned(amount);
@@ -80,7 +80,7 @@ module NativeShieldedTokenPublicSupply {
    * @description Adds `amount` to the exact minted total. Call once per
    * successful `NativeShieldedToken._mint`.
    *
-   * @circuitInfo k=9, rows=375
+   * @constraints k=9, rows=373
    *
    * @param {Uint<64>} amount - The minted amount.
    * @return {[]} - Empty tuple.
@@ -94,7 +94,7 @@ module NativeShieldedTokenPublicSupply {
    * per successful `NativeShieldedToken._burn` / `_burnFromSelf`.
    * @dev Enforces `burned <= minted`; an unpaired or duplicate burn reverts.
    *
-   * @circuitInfo k=9, rows=477
+   * @constraints k=9, rows=475
    *
    * @param {Uint<128>} amount - The burned amount.
    * @return {[]} - Empty tuple.
@@ -106,7 +106,7 @@ module NativeShieldedTokenPublicSupply {
   /**
    * @description Returns the exact amount ever minted.
    *
-   * @circuitInfo k=7, rows=65
+   * @constraints k=7, rows=63
    *
    * @return {Uint<128>} - The total amount minted.
    */
@@ -119,7 +119,7 @@ module NativeShieldedTokenPublicSupply {
    * @notice This is a lower bound: coins sent directly to the burn address
    * without going through the contract are not counted.
    *
-   * @circuitInfo k=7, rows=62
+   * @constraints k=7, rows=60
    *
    * @return {Uint<128>} - The total amount burned through the contract.
    */
@@ -132,7 +132,7 @@ module NativeShieldedTokenPublicSupply {
    * @notice This is an UPPER BOUND on circulating supply, not an exact value:
    * burns that bypass the contract are invisible. See the module notes.
    *
-   * @circuitInfo k=9, rows=160
+   * @constraints k=9, rows=158
    *
    * @return {Uint<128>} - The upper bound on tokens in existence.
    */

package/token/extensions/NativeShieldedTokenPublicSupplyCore.compact

@@ -71,7 +71,7 @@ module NativeShieldedTokenPublicSupplyCore {
    * once per successful token `_mint`.
    * @dev Checks for overflow in order to output a readable error message.
    *
-   * @circuitInfo k=10, rows=653
+   * @constraints k=10, rows=645
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @param {Uint<64>} amount - The minted amount.
@@ -91,7 +91,7 @@ module NativeShieldedTokenPublicSupplyCore {
    * The guard also keeps the add and the `totalSupply` subtraction within
    * bounds, so no separate overflow/underflow check is needed.
    *
-   * @circuitInfo k=10, rows=755
+   * @constraints k=10, rows=747
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @param {Uint<128>} amount - The burned amount.
@@ -111,7 +111,7 @@ module NativeShieldedTokenPublicSupplyCore {
   /**
    * @description Returns the exact amount ever minted for `domain`.
    *
-   * @circuitInfo k=9, rows=344
+   * @constraints k=9, rows=342
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @return {Uint<128>} - The total amount minted.
@@ -128,7 +128,7 @@ module NativeShieldedTokenPublicSupplyCore {
    * @notice This is a lower bound: coins sent directly to the burn address
    * without going through the contract are not counted.
    *
-   * @circuitInfo k=9, rows=341
+   * @constraints k=9, rows=339
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @return {Uint<128>} - The total amount burned through the contract.
@@ -150,7 +150,7 @@ module NativeShieldedTokenPublicSupplyCore {
    * fires in normal operation. It is kept so the getter is a total function that
    * reads cleanly (returning 0) rather than reverting on an out-of-bound state.
    *
-   * @circuitInfo k=9, rows=439
+   * @constraints k=9, rows=437
    *
    * @param {Bytes<32>} domain - 32-byte token discriminator.
    * @return {Uint<128>} - The upper bound on tokens in existence.