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

package/token/extensions/NativeShieldedTokenSupplyCore.compact

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.2.0 (token/extensions/NativeShieldedTokenSupplyCore.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module NativeShieldedTokenSupplyCore
+ * @description Shared, domain-keyed core of the optional supply-accounting
+ * extension. It owns the per-domain minted/burned maps and exposes the
+ * `_addMinted` / `_addBurned` building blocks plus the `totalMinted` /
+ * `totalBurned` / `totalSupply` getters, each keyed by domain.
+ *
+ * This module is NOT meant to be composed directly. It is the de-duplicated
+ * base behind the two user-facing flavors:
+ *
+ * - `NativeShieldedTokenSupply` — pairs with `NativeShieldedToken`; forwards a
+ *   single fixed key (the contract has one token type).
+ * - `NativeShieldedTokenFamilySupply` — pairs with `NativeShieldedTokenFamily`;
+ *   forwards the caller's per-call `domain`.
+ *
+ * @dev Assertion messages use the generic `NativeShieldedTokenSupply:` prefix
+ * so they read sensibly from either flavor. There is no initialization: an
+ * absent domain key reads as 0, and the getters do not gate on the paired token
+ * module's init flag (a counter reading 0 before init is correct), so init
+ * enforcement stays with the token module's mint/burn circuits.
+ *
+ * @notice Accounting guarantees (when wired correctly by the consumer):
+ * `totalMinted(domain)` is EXACT, `totalBurned(domain)` a LOWER BOUND (burns
+ * that bypass the contract are invisible), and `totalSupply(domain)` =
+ * minted - burned an UPPER BOUND on circulating supply. These hold only if the
+ * consumer pairs every `_mint` with `_addMinted` and every burn with
+ * `_addBurned` under the same domain; the extension cannot enforce the pairing
+ * itself.
+ *
+ * @notice `_addBurned` enforces `burned <= minted` per domain, so a
+ * wrong-domain, duplicate, or unpaired BURN reverts rather than pushing
+ * `totalSupply(domain)` negative (this also keeps the `_addBurned` add and the
+ * `totalSupply` subtraction within bounds). It does NOT catch mint-side drift:
+ * a duplicated `_addMinted`, or one keyed to the wrong domain, silently inflates
+ * `totalMinted` (and the `burned <= minted` headroom). Correct mint pairing
+ * remains the consumer's responsibility.
+ *
+ * @warning The mint/burn <-> accounting pairing is a security-critical invariant
+ * of the CONSUMING contract; this extension cannot enforce or detect a breach:
+ * - A mint whose `_addMinted` is missing or wrong-domain leaves `totalMinted`
+ *   too low, so `_addBurned` REJECTS burns that are actually legitimate —
+ *   holders cannot burn coins that genuinely exist.
+ * - A duplicate or wrong-domain `_addMinted` inflates `totalMinted`, letting
+ *   `_addBurned` accept burns beyond what was minted.
+ * - A missing `_addBurned` leaves `totalBurned` too low, so `totalSupply`
+ *   overstates circulating supply.
+ * Call the matching accounting block on every mint and burn path, same domain.
+ */
+module NativeShieldedTokenSupplyCore {
+  import CompactStandardLibrary;
+  import "../../utils/Utils" prefix Utils_;
+
+  /**
+   * @description Exact amount minted per domain. See "Accounting guarantees".
+   * @type {Map<Bytes<32>, Uint<128>>} _totalMinted
+   */
+  export ledger _totalMinted: Map<Bytes<32>, Uint<128>>;
+  /**
+   * @description Contract-mediated amount burned per domain (lower bound).
+   * @type {Map<Bytes<32>, Uint<128>>} _totalBurned
+   */
+  export ledger _totalBurned: Map<Bytes<32>, Uint<128>>;
+
+  /**
+   * @description Adds `amount` to the exact minted total for `domain`. Call
+   * once per successful token `_mint`.
+   * @dev Checks for overflow in order to output a readable error message.
+   *
+   * @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>): [] {
+    const current = totalMinted(domain);
+    assert(Utils_UINT128_MAX() - current >= amount, "NativeShieldedTokenSupply: arithmetic overflow");
+    _totalMinted.insert(disclose(domain), disclose((current + amount) as Uint<128>));
+  }
+
+  /**
+   * @description Adds `amount` to the contract-mediated burned total for
+   * `domain`. Call once per successful token `_burn` / `_burnFromSelf`.
+   * @dev Enforces the per-domain `burned <= minted` invariant: a wrong-domain,
+   * duplicate, or unpaired burn reverts rather than corrupting `totalSupply`.
+   * 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
+   *
+   * @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>): [] {
+    const minted = totalMinted(domain);
+    const current = totalBurned(domain);
+    // First guards the subtraction below from underflowing on an already-corrupt
+    // state (stored burned past minted); the second is the reachable per-call
+    // check that this burn does not push the domain past its minted total.
+    assert(minted >= current, "NativeShieldedTokenSupply: burned total exceeds minted");
+    assert(minted - current >= amount, "NativeShieldedTokenSupply: burn exceeds available supply");
+    _totalBurned.insert(disclose(domain), disclose((current + amount) as Uint<128>));
+  }
+
+  /**
+   * @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> {
+    if (!_totalMinted.member(disclose(domain))) {
+      return 0;
+    }
+    return _totalMinted.lookup(disclose(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> {
+    if (!_totalBurned.member(disclose(domain))) {
+      return 0;
+    }
+    return _totalBurned.lookup(disclose(domain));
+  }
+
+  /**
+   * @description Returns `totalMinted(domain) - totalBurned(domain)`, or 0 if
+   * `totalBurned` somehow exceeds `totalMinted`.
+   * @notice This is an UPPER BOUND on circulating supply, not an exact value:
+   * burns that bypass the contract are invisible. See the module notes.
+   * @dev The `burned <= minted` invariant enforced by `_addBurned` already makes
+   * `burned > minted` unreachable through the accounting API, so the clamp never
+   * 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
+   *
+   * @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> {
+    const minted = totalMinted(domain);
+    const burned = totalBurned(domain);
+    return (minted >= burned ? (minted - burned) : 0) as Uint<128>;
+  }
+}

package/utils/Utils.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (utils/Utils.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (utils/Utils.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module Utils.
@@ -95,4 +95,88 @@ module Utils {
       ? Either<T1, T2>{ is_left: true, left: value.left, right: default<T2> }
       : Either<T1, T2>{ is_left: false, left: default<T1>, right: value.right };
   }
+
+  /**
+   * @description Returns the canonical zero `Either<Bytes<32>, ContractAddress>` value: the
+   * left variant (`Bytes<32>`) set to zero. Used as the sentinel for mint/burn operations
+   * (a zero `from` signals a mint, a zero `to` signals a burn) and for cleared approvals.
+   *
+   * The left variant is chosen so that `isTargetZero` checks against `default<Bytes<32>>`,
+   * and to avoid triggering contract-address guards (e.g. circuits that check `!to.is_left`
+   * before delegating to an `_unsafe` variant). A right variant with `default<ContractAddress>`
+   * would also pass `isTargetZero`, but the left variant keeps guards and error messages consistent.
+   *
+   * @return {Either<Bytes<32>, ContractAddress>} - The canonical zero value.
+   */
+  export pure circuit zeroAccount(): Either<Bytes<32>, ContractAddress> {
+    return Either<Bytes<32>, ContractAddress> {
+      is_left: true, left: default<Bytes<32>>, right: default<ContractAddress>
+    };
+  }
+
+  /**
+   * @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.
+   * @return {Boolean} - `true` if the active branch is zero, `false` otherwise.
+   */
+  export pure circuit isTargetZero(target: Either<Bytes<32>, ContractAddress>): Boolean {
+    if (target.is_left) {
+      return target.left == default<Bytes<32>>;
+    } else {
+      return target.right == default<ContractAddress>;
+    }
+  }
+
+  /**
+   * @description Computes an account identifier without on-chain state, allowing a user to derive
+   * their identity commitment before submitting an operation.
+   *
+   * @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 the current contract's address as an
+   * `Either<ZswapCoinPublicKey, ContractAddress>` for use as a
+   * recipient in shielded send operations (deposits and receiving change).
+   *
+   * @returns {Either<ZswapCoinPublicKey, ContractAddress>} The contract's address as a recipient.
+   */
+  export circuit selfAsRecipient(): Either<ZswapCoinPublicKey, ContractAddress> {
+    return right<ZswapCoinPublicKey, ContractAddress>(kernel.self());
+  }
+
+  /**
+   * @description The maximum value representable by a `Uint<128>`.
+   *
+   * @notice TODO: Remove once a math module providing this constant is available.
+   *
+   * @returns {Uint<128>} `2^128 - 1`.
+   */
+  export pure circuit UINT128_MAX(): Uint<128> {
+    return 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF;
+  }
 }