@openzeppelin/compact-contracts 0.2.0 → 0.3.0-alpha.1

package/token/NonFungibleToken.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (token/NonFungibleToken.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (token/NonFungibleToken.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module NonFungibleToken
@@ -154,18 +154,6 @@ module NonFungibleToken {
    */
   witness wit_NonFungibleTokenSK(): Bytes<32>;
 
-  /**
-   * @description Returns a canonical zero Either value (left variant with zero Bytes<32>).
-   * Used as the zero value for mint/burn operations and cleared approvals.
-   *
-   * @return {Either<Bytes<32>, ContractAddress>} - The zero value.
-   */
-  export pure circuit ZERO(): Either<Bytes<32>, ContractAddress> {
-    return Either<Bytes<32>, ContractAddress> {
-      is_left: true, left: default<Bytes<32>>, right: default<ContractAddress>
-    };
-  }
-
   /**
    * @description Initializes the contract by setting the name and symbol.
    *
@@ -510,7 +498,7 @@ module NonFungibleToken {
                    tokenId: Uint<128>
                    ): [] {
     assertInitialized();
-    assert(!_isTargetZero(to), "NonFungibleToken: invalid receiver");
+    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());
@@ -535,7 +523,7 @@ module NonFungibleToken {
   export circuit _ownerOf(tokenId: Uint<128>): Either<Bytes<32>, ContractAddress> {
     assertInitialized();
     if (!_owners.member(disclose(tokenId))) {
-      return ZERO();
+      return Utils_zeroAccount();
     }
 
     return _owners.lookup(disclose(tokenId));
@@ -556,7 +544,7 @@ module NonFungibleToken {
   export circuit _getApproved(tokenId: Uint<128>): Either<Bytes<32>, ContractAddress> {
     assertInitialized();
     if (!_tokenApprovals.member(disclose(tokenId))) {
-      return ZERO();
+      return Utils_zeroAccount();
     }
     return _tokenApprovals.lookup(disclose(tokenId));
   }
@@ -588,7 +576,7 @@ module NonFungibleToken {
     const canonOwner = Utils_canonicalize<Bytes<32>, ContractAddress>(owner);
     const canonSpender = Utils_canonicalize<Bytes<32>, ContractAddress>(spender);
 
-    return (!_isTargetZero(disclose(canonSpender)) &&
+    return (!Utils_isTargetZero(disclose(canonSpender)) &&
             (disclose(canonOwner) == disclose(canonSpender) ||
              isApprovedForAll(canonOwner, canonSpender) ||
              _getApproved(tokenId) == disclose(canonSpender)));
@@ -619,7 +607,7 @@ module NonFungibleToken {
                    ): [] {
     assertInitialized();
     if (!_isAuthorized(owner, spender, tokenId)) {
-      assert(!_isTargetZero(owner), "NonFungibleToken: nonexistent token");
+      assert(!Utils_isTargetZero(owner), "NonFungibleToken: nonexistent token");
       assert(false, "NonFungibleToken: insufficient approval");
     }
   }
@@ -649,20 +637,20 @@ module NonFungibleToken {
     const fromAddress = _ownerOf(tokenId);
 
     // Perform (optional) operator check
-    if (!_isTargetZero(disclose(canonAuth))) {
+    if (!Utils_isTargetZero(disclose(canonAuth))) {
       _checkAuthorized(fromAddress, canonAuth, tokenId);
     }
 
     // Execute the update
-    if (!_isTargetZero(disclose(fromAddress))) {
+    if (!Utils_isTargetZero(disclose(fromAddress))) {
       // Clear approval. No need to re-authorize
-      _approve(ZERO(), tokenId, ZERO());
+      _approve(Utils_zeroAccount(), tokenId, Utils_zeroAccount());
       const canonFrom = Utils_canonicalize<Bytes<32>, ContractAddress>(fromAddress);
       const newBalance = _balances.lookup(disclose(canonFrom)) - 1 as Uint<128>;
       _balances.insert(disclose(canonFrom), disclose(newBalance));
     }
 
-    if (!_isTargetZero(disclose(canonTo))) {
+    if (!Utils_isTargetZero(disclose(canonTo))) {
       if (!_balances.member(disclose(canonTo))) {
         _balances.insert(disclose(canonTo), 0);
       }
@@ -723,11 +711,11 @@ module NonFungibleToken {
                    tokenId: Uint<128>
                    ): [] {
     assertInitialized();
-    assert(!_isTargetZero(to), "NonFungibleToken: invalid receiver");
+    assert(!Utils_isTargetZero(to), "NonFungibleToken: invalid receiver");
 
-    const previousOwner = _update(to, tokenId, ZERO());
+    const previousOwner = _update(to, tokenId, Utils_zeroAccount());
 
-    assert(_isTargetZero(previousOwner), "NonFungibleToken: invalid sender");
+    assert(Utils_isTargetZero(previousOwner), "NonFungibleToken: invalid sender");
   }
 
   /**
@@ -747,8 +735,8 @@ module NonFungibleToken {
    */
   export circuit _burn(tokenId: Uint<128>): [] {
     assertInitialized();
-    const previousOwner = _update(ZERO(), tokenId, ZERO());
-    assert(!_isTargetZero(previousOwner), "NonFungibleToken: invalid sender");
+    const previousOwner = _update(Utils_zeroAccount(), tokenId, Utils_zeroAccount());
+    assert(!Utils_isTargetZero(previousOwner), "NonFungibleToken: invalid sender");
     _tokenURIs.remove(disclose(tokenId));
   }
 
@@ -814,11 +802,11 @@ module NonFungibleToken {
                    tokenId: Uint<128>
                    ): [] {
     assertInitialized();
-    assert(!_isTargetZero(to), "NonFungibleToken: invalid receiver");
+    assert(!Utils_isTargetZero(to), "NonFungibleToken: invalid receiver");
 
-    const previousOwner = _update(to, tokenId, ZERO());
+    const previousOwner = _update(to, tokenId, Utils_zeroAccount());
 
-    assert(!_isTargetZero(previousOwner), "NonFungibleToken: nonexistent token");
+    assert(!Utils_isTargetZero(previousOwner), "NonFungibleToken: nonexistent token");
 
     const canonFrom = Utils_canonicalize<Bytes<32>, ContractAddress>(fromAddress);
     assert(previousOwner == canonFrom, "NonFungibleToken: incorrect owner");
@@ -848,12 +836,12 @@ module NonFungibleToken {
     assertInitialized();
     // Canonicalize + normalize `to`
     const canonTo = Utils_canonicalize<Bytes<32>, ContractAddress>(to);
-    const normalizedTo = _isTargetZero(canonTo) ? ZERO() : canonTo;
+    const normalizedTo = Utils_isTargetZero(canonTo) ? Utils_zeroAccount() : canonTo;
 
     // Canonicalize auth
     const canonAuth = Utils_canonicalize<Bytes<32>, ContractAddress>(auth);
 
-    if (!_isTargetZero(disclose(canonAuth))) {
+    if (!Utils_isTargetZero(disclose(canonAuth))) {
       const owner = _requireOwned(tokenId);
 
       // We do not use _isAuthorized because single-token approvals should not be able to call approve
@@ -888,10 +876,10 @@ module NonFungibleToken {
                    ): [] {
     assertInitialized();
     const canonOwner = Utils_canonicalize<Bytes<32>, ContractAddress>(owner);
-    assert(!_isTargetZero(canonOwner), "NonFungibleToken: invalid owner");
+    assert(!Utils_isTargetZero(canonOwner), "NonFungibleToken: invalid owner");
 
     const canonOp = Utils_canonicalize<Bytes<32>, ContractAddress>(operator);
-    assert(!_isTargetZero(canonOp), "NonFungibleToken: invalid operator");
+    assert(!Utils_isTargetZero(canonOp), "NonFungibleToken: invalid operator");
 
     if (!_operatorApprovals.member(disclose(canonOwner))) {
       _operatorApprovals.insert(
@@ -921,7 +909,7 @@ module NonFungibleToken {
     assertInitialized();
     const owner = _ownerOf(tokenId);
 
-    assert(!_isTargetZero(owner), "NonFungibleToken: nonexistent token");
+    assert(!Utils_isTargetZero(owner), "NonFungibleToken: nonexistent token");
     return owner;
   }
 
@@ -936,52 +924,6 @@ module NonFungibleToken {
    * @returns {Bytes<32>} accountId - The computed account identifier.
    */
   circuit _computeAccountId(): Bytes<32> {
-    return computeAccountId(wit_NonFungibleTokenSK());
-  }
-
-  /**
-   * @description Computes an account identifier without on-chain state, allowing a user to derive
-   * their identity commitment before submitting it in a token operation.
-   * This is the off-chain counterpart to {_computeAccountId} and produces an identical result
-   * given the same inputs.
-   *
-   * @warning OpSec: The `secretKey` parameter is a sensitive secret. Mishandling it can
-   * permanently compromise the security of this system:
-   *
-   * - **Never log or persist** the `secretKey` in plaintext — avoid browser devtools,
-   *   application logs, analytics pipelines, or any observable side-channel.
-   * - **Store offline or in secure enclaves** — hardware security modules (HSMs),
-   *   air-gapped devices, or encrypted vaults are strongly preferred over hot storage.
-   * - **Use cryptographically secure randomness** — generate keys with `crypto.getRandomValues()`
-   *   or equivalent; weak or predictable keys can be brute-forced to reveal your identity.
-   * - **Treat key loss as identity loss** — a lost key cannot be recovered.
-   * - **Avoid calling this circuit in untrusted environments** — executing this in an
-   *   unverified browser extension, compromised runtime, or shared machine may expose
-   *   the key to a malicious observer.
-   *
-   * ## ID Derivation
-   * `accountId = persistentHash(secretKey)`
-   *
-   * @param {Bytes<32>} secretKey - A 32-byte cryptographically secure random value.
-   *
-   * @returns {Bytes<32>} accountId - The computed account identifier.
-   */
-  export pure circuit computeAccountId(secretKey: Bytes<32>): Bytes<32> {
-    return persistentHash<Vector<1, Bytes<32>>>([secretKey]);
-  }
-
-  /**
-   * @description Returns `true` if `target`'s active branch (as indicated by `is_left`)
-   * holds the zero value.
-   *
-   * @param {Either<Bytes<32>, ContractAddress>} target - The value to check.
-   * @returns {Boolean} - `true` if the active branch is zero, `false` otherwise.
-   */
-  circuit _isTargetZero(target: Either<Bytes<32>, ContractAddress>): Boolean {
-    if (target.is_left) {
-      return target.left == default<Bytes<32>>;
-    } else {
-      return target.right == default<ContractAddress>;
-    }
+    return Utils_computeAccountId(wit_NonFungibleTokenSK());
   }
 }

package/token/extensions/ConfidentialFungibleTokenPublicSupply.compact

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (token/extensions/ConfidentialFungibleTokenPublicSupply.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module ConfidentialFungibleTokenPublicSupply
+ * @description Optional standalone extension that adds public supply
+ * accounting to a `ConfidentialFungibleToken`. It exposes the scalar
+ * `_addSupply` / `_subSupply` building blocks plus the `totalSupply` getter.
+ * It imports no token module.
+ *
+ * "Public" supply means the total, and therefore each mint/burn delta, is
+ * disclosed on chain. Balances stay confidential; only the aggregate is
+ * visible. This is the right default for issuers who must attest to a public
+ * circulating supply (stablecoins, tokenized funds). A confidential-supply
+ * extension (ElGamal supply cell + auditor viewing key) is a separate variant.
+ *
+ * @notice Pairs with `ConfidentialFungibleToken`. The consuming contract
+ * composes the pieces, calling the accounting block alongside the matching
+ * token op (the integration suite drives an assembled example,
+ * `test/integration/_mocks/ConfidentialFungibleTokenPublicSupply`):
+ *
+ *   export circuit mint(account: Bytes<32>, value: Uint<128>): [] {
+ *     Supply__addSupply(value);
+ *     Token__mint(account, value);
+ *   }
+ *
+ * The pairing is the consuming contract's responsibility: a token op called
+ * without its accounting block (or vice versa) breaks the
+ * `sum(balances) == totalSupply` invariant this extension exists to attest.
+ */
+module ConfidentialFungibleTokenPublicSupply {
+  import CompactStandardLibrary;
+
+  // The public circulating supply. 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
+   *
+   * Requirements:
+   *
+   * - `totalSupply + value` does not overflow `Uint<128>`.
+   *
+   * @param {Uint<128>} value - The amount added to the supply.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _addSupply(value: Uint<128>): [] {
+    const MAX_UINT128 = 340282366920938463463374607431768211455;
+    assert(MAX_UINT128 - _totalSupply >= value,
+           "ConfidentialFungibleTokenPublicSupply: overflow");
+    _totalSupply = disclose(_totalSupply + value as Uint<128>);
+  }
+
+  /**
+   * @description Decreases `totalSupply` by `value`. Call alongside the token
+   * module's `_burn` or `_burnFrom`. The removed amount is disclosed via the
+   * supply delta.
+   *
+   * @circuitInfo k=9, rows=256
+   *
+   * Requirements:
+   *
+   * - `totalSupply` is at least `value`.
+   *
+   * @param {Uint<128>} value - The amount removed from the supply.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _subSupply(value: Uint<128>): [] {
+    assert(_totalSupply >= value,
+           "ConfidentialFungibleTokenPublicSupply: supply underflow");
+    _totalSupply = disclose(_totalSupply - value as Uint<128>);
+  }
+
+  /**
+   * @description Returns the public total token supply.
+   *
+   * @circuitInfo k=6, rows=26
+   *
+   * @return {Uint<128>} - The total supply.
+   */
+  export circuit totalSupply(): Uint<128> {
+    return _totalSupply;
+  }
+}

package/token/extensions/NativeShieldedTokenDerivedNonce.compact

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (token/extensions/NativeShieldedTokenDerivedNonce.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module NativeShieldedTokenDerivedNonce
+ * @description Optional standalone extension providing derived coin nonces for
+ * native shielded token mints, so callers need not manage nonces themselves. It
+ * owns a monotonic `_counter` and exposes `_deriveNonce`; it imports no token
+ * module and needs no initialization.
+ *
+ * @notice Pairs with `NativeShieldedToken` and `NativeShieldedTokenFamily`. The
+ * consuming contract composes the pieces:
+ *
+ *   export circuit mint(recipient: ..., amount: Uint<64>): ShieldedCoinInfo {
+ *     return Token__mint(recipient, amount, Derived__deriveNonce());
+ *   }
+ *
+ * @dev Derivation
+ * Each call derives `evolveNonce(_counter, pad(32, "NativeShieldedToken:nonce"))`.
+ * `evolveNonce` hashes the counter into a full 32-byte nonce, so uniqueness comes
+ * from the monotonic counter, not the tag. The fixed tag is a domain separator:
+ * it keeps these derived nonces from clashing with any other `evolveNonce` call
+ * the implementing contract makes on the same counter for a different purpose.
+ * One counter serves the whole contract, so derived nonces never repeat across
+ * token types (domains) of one contract.
+ *
+ * @notice This variant is deterministic and recipient-PUBLIC by design: derived
+ * nonces are predictable from public state, so anyone can recompute the coin
+ * commitment for candidate recipient keys. For recipient privacy, call the base
+ * `_mint` with a secret, cryptographically random nonce instead. (An earlier
+ * design seeded a hash chain to make the sequence look random; that bought
+ * nothing here because the seed and chain are disclosed to public state, so it
+ * was removed.)
+ *
+ * @notice Collision-griefing. Derived nonces are predictable, so an actor with a
+ * caller-nonce mint can pre-mint a colliding commitment and make the matching
+ * derived-nonce mint fail. Mitigations:
+ * - Access-control both mint paths, and avoid exposing them at different trust
+ *   levels.
+ * - Do not rely on retrying. The nonce is a pure function of the counter, and a
+ *   reverted mint will not advance it, so an identical retry collides again.
+ *   Recovery is a mint with different inputs (recipient or amount): it advances
+ *   the counter, so the original tuple then mints against a fresh nonce.
+ */
+module NativeShieldedTokenDerivedNonce {
+  import CompactStandardLibrary;
+
+  /**
+   * @description Monotonic index feeding the derived-nonce derivation.
+   */
+  export ledger _counter: Counter;
+
+  /**
+   * @description Advances the counter and returns the next derived coin nonce,
+   * for use as the `nonce` argument of a native token mint.
+   *
+   * @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
+   *
+   * @return {Bytes<32>} - The next derived coin nonce.
+   */
+  export circuit _deriveNonce(): Bytes<32> {
+    _counter.increment(1);
+    return evolveNonce(_counter, pad(32, "NativeShieldedToken:nonce"));
+  }
+}

package/token/extensions/NativeShieldedTokenFamilySupply.compact

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.2.0 (token/extensions/NativeShieldedTokenFamilySupply.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module NativeShieldedTokenFamilySupply
+ * @description Optional standalone extension that adds per-domain on-chain
+ * supply accounting to a `NativeShieldedTokenFamily`. It exposes `_addMinted` /
+ * `_addBurned` building blocks plus the `totalMinted` / `totalBurned` /
+ * `totalSupply` getters, each keyed by domain. It imports no token module.
+ *
+ * It is a thin wrapper over `NativeShieldedTokenSupplyCore`, forwarding the
+ * caller's per-call `domain`, so the accounting logic and guarantees live in
+ * the shared core.
+ *
+ * @notice Pairs with `NativeShieldedTokenFamily`. The consuming contract
+ * composes the pieces, calling the accounting block alongside the matching
+ * token op:
+ *
+ *   export circuit mint(
+ *     domain: Bytes<32>,
+ *     recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+ *     amount: Uint<64>,
+ *     nonce: Bytes<32>
+ *   ): ShieldedCoinInfo {
+ *     const coin = Family__mint(domain, recipient, amount, nonce);
+ *     Supply__addMinted(domain, amount);
+ *     return coin;
+ *   }
+ *
+ *   export circuit burn(
+ *     domain: Bytes<32>,
+ *     coin: ShieldedCoinInfo,
+ *     amount: Uint<128>,
+ *     refundTo: Either<ZswapCoinPublicKey, ContractAddress>
+ *   ): Maybe<ShieldedCoinInfo> {
+ *     const refund = Family__burn(domain, coin, amount, refundTo);
+ *     Supply__addBurned(domain, amount);
+ *     return refund;
+ *   }
+ *
+ * @notice Privacy trade-off (read before composing): composing this extension
+ * makes contract-mediated BURN amounts PUBLIC. The bare family's `_burn` /
+ * `_burnFromSelf` are amount-private (their coin operations emit only
+ * commitments and nullifiers, never the value; the `disclose()` wrappers they
+ * require are compiler permission markers, not disclosure sinks). The
+ * `_addBurned` write here is what puts the burned amount into the public
+ * transcript. Compose this only when on-chain auditability is worth more than
+ * burn-amount privacy.
+ *
+ * @dev Mint amounts are already public via the protocol's `shieldedMints`
+ * effect, so `_addMinted` adds accounting, not disclosure. See
+ * `NativeShieldedTokenSupplyCore` for the exact / lower-bound / upper-bound
+ * guarantees, the per-domain `burned <= minted` invariant, and the mint-side
+ * drift caveat.
+ *
+ * @warning Pair every mint with `_addMinted` and every burn with `_addBurned` on
+ * every path, under the matching domain; mis-wiring is a security-critical,
+ * undetectable error (e.g. an undercounted mint makes `_addBurned` reject
+ * legitimate burns). See `NativeShieldedTokenSupplyCore`.
+ */
+module NativeShieldedTokenFamilySupply {
+  import CompactStandardLibrary;
+  import "./NativeShieldedTokenSupplyCore" prefix Core_;
+
+  // Circuits use the `Core_` prefix above. The named import/re-export below is
+  // only for the core supply ledger keys, so the implementing contract's ledger
+  // keys read as `_totalMinted` / `_totalBurned` rather than
+  // `NativeShieldedTokenSupplyCore__totalMinted`. The circuit names are
+  // intentionally NOT imported unprefixed, to avoid potential clashes.
+  import { _totalMinted, _totalBurned } from "./NativeShieldedTokenSupplyCore";
+  export { _totalMinted, _totalBurned };
+
+  /**
+   * @description Adds `amount` to the exact minted total for `domain`. Call
+   * once per successful `NativeShieldedTokenFamily._mint`.
+   *
+   * @circuitInfo k=10, rows=653
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator.
+   * @param {Uint<64>} amount - The minted amount.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _addMinted(domain: Bytes<32>, amount: Uint<64>): [] {
+    Core__addMinted(domain, amount);
+  }
+
+  /**
+   * @description Adds `amount` to the contract-mediated burned total for
+   * `domain`. Call once per successful `NativeShieldedTokenFamily._burn` /
+   * `_burnFromSelf`.
+   * @dev Enforces per-domain `burned <= minted`; an unpaired, duplicate, or
+   * wrong-domain burn reverts.
+   *
+   * @circuitInfo k=10, rows=755
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator.
+   * @param {Uint<128>} amount - The burned amount.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _addBurned(domain: Bytes<32>, amount: Uint<128>): [] {
+    Core__addBurned(domain, amount);
+  }
+
+  /**
+   * @description Returns the exact amount ever minted for `domain`.
+   *
+   * @circuitInfo k=9, rows=344
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator.
+   * @return {Uint<128>} - The total amount minted.
+   */
+  export circuit totalMinted(domain: Bytes<32>): Uint<128> {
+    return Core_totalMinted(domain);
+  }
+
+  /**
+   * @description Returns the contract-mediated amount burned for `domain`.
+   * @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
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator.
+   * @return {Uint<128>} - The total amount burned through the contract.
+   */
+  export circuit totalBurned(domain: Bytes<32>): Uint<128> {
+    return Core_totalBurned(domain);
+  }
+
+  /**
+   * @description Returns `totalMinted(domain) - totalBurned(domain)`.
+   * @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
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator.
+   * @return {Uint<128>} - The upper bound on tokens in existence.
+   */
+  export circuit totalSupply(domain: Bytes<32>): Uint<128> {
+    return Core_totalSupply(domain);
+  }
+}

package/token/extensions/NativeShieldedTokenSupply.compact

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.2.0 (token/extensions/NativeShieldedTokenSupply.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module NativeShieldedTokenSupply
+ * @description Optional standalone extension that adds on-chain supply
+ * accounting to a `NativeShieldedToken`. It exposes scalar `_addMinted` /
+ * `_addBurned` building blocks plus the `totalMinted` / `totalBurned` /
+ * `totalSupply` getters. It imports no token module.
+ *
+ * It is a thin wrapper over `NativeShieldedTokenSupplyCore`, forwarding a
+ * single fixed key (the paired contract has exactly one token type), so the
+ * accounting logic and guarantees live in the shared core.
+ *
+ * @notice Pairs with `NativeShieldedToken`. The consuming contract composes the
+ * pieces, calling the accounting block alongside the matching token op:
+ *
+ *   export circuit mint(
+ *     recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+ *     amount: Uint<64>,
+ *     nonce: Bytes<32>
+ *   ): ShieldedCoinInfo {
+ *     const coin = Token__mint(recipient, amount, nonce);
+ *     Supply__addMinted(amount);
+ *     return coin;
+ *   }
+ *
+ *   export circuit burn(
+ *     coin: ShieldedCoinInfo,
+ *     amount: Uint<128>,
+ *     refundTo: Either<ZswapCoinPublicKey, ContractAddress>
+ *   ): Maybe<ShieldedCoinInfo> {
+ *     const refund = Token__burn(coin, amount, refundTo);
+ *     Supply__addBurned(amount);
+ *     return refund;
+ *   }
+ *
+ * @notice Privacy trade-off (read before composing): composing this extension
+ * makes contract-mediated BURN amounts PUBLIC. The bare token's `_burn` /
+ * `_burnFromSelf` are amount-private (their coin operations emit only
+ * commitments and nullifiers, never the value; the `disclose()` wrappers they
+ * require are compiler permission markers, not disclosure sinks). The
+ * `_addBurned` write here is what puts the burned amount into the public
+ * transcript. Compose this only when on-chain auditability is worth more than
+ * burn-amount privacy.
+ *
+ * @dev Mint amounts are already public via the protocol's `shieldedMints`
+ * effect, so `_addMinted` adds accounting, not disclosure. See
+ * `NativeShieldedTokenSupplyCore` for the exact / lower-bound / upper-bound
+ * guarantees, the `burned <= minted` invariant, and the mint-side drift caveat.
+ *
+ * @warning Pair every mint with `_addMinted` and every burn with `_addBurned` on
+ * every path; mis-wiring is a security-critical, undetectable error (e.g. an
+ * undercounted mint makes `_addBurned` reject legitimate burns). See
+ * `NativeShieldedTokenSupplyCore`.
+ */
+module NativeShieldedTokenSupply {
+  import CompactStandardLibrary;
+  import "./NativeShieldedTokenSupplyCore" prefix Core_;
+
+  // Circuits use the `Core_` prefix above. The named import/re-export below is
+  // only for the core supply ledger keys, so the implementing contract's ledger
+  // keys read as `_totalMinted` / `_totalBurned` rather than
+  // `NativeShieldedTokenSupplyCore__totalMinted`. The circuit names are
+  // intentionally NOT imported unprefixed, to avoid potential clashes.
+  import { _totalMinted, _totalBurned } from "./NativeShieldedTokenSupplyCore";
+  export { _totalMinted, _totalBurned };
+
+  /**
+   * @description The single fixed domain key. The paired `NativeShieldedToken`
+   * has exactly one token type, so all accounting lives under one key.
+   */
+  circuit key(): Bytes<32> {
+    return default<Bytes<32>>;
+  }
+
+  /**
+   * @description Adds `amount` to the exact minted total. Call once per
+   * successful `NativeShieldedToken._mint`.
+   *
+   * @circuitInfo k=9, rows=375
+   *
+   * @param {Uint<64>} amount - The minted amount.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _addMinted(amount: Uint<64>): [] {
+    Core__addMinted(key(), amount);
+  }
+
+  /**
+   * @description Adds `amount` to the contract-mediated burned total. Call once
+   * per successful `NativeShieldedToken._burn` / `_burnFromSelf`.
+   * @dev Enforces `burned <= minted`; an unpaired or duplicate burn reverts.
+   *
+   * @circuitInfo k=9, rows=477
+   *
+   * @param {Uint<128>} amount - The burned amount.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _addBurned(amount: Uint<128>): [] {
+    Core__addBurned(key(), amount);
+  }
+
+  /**
+   * @description Returns the exact amount ever minted.
+   *
+   * @circuitInfo k=7, rows=65
+   *
+   * @return {Uint<128>} - The total amount minted.
+   */
+  export circuit totalMinted(): Uint<128> {
+    return Core_totalMinted(key());
+  }
+
+  /**
+   * @description Returns the contract-mediated amount burned.
+   * @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
+   *
+   * @return {Uint<128>} - The total amount burned through the contract.
+   */
+  export circuit totalBurned(): Uint<128> {
+    return Core_totalBurned(key());
+  }
+
+  /**
+   * @description Returns `totalMinted() - totalBurned()`.
+   * @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
+   *
+   * @return {Uint<128>} - The upper bound on tokens in existence.
+   */
+  export circuit totalSupply(): Uint<128> {
+    return Core_totalSupply(key());
+  }
+}