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

package/token/FungibleToken.compact

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

package/token/MultiToken.compact

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

package/token/NativeShieldedToken.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (token/NativeShieldedToken.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (token/NativeShieldedToken.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -45,7 +45,7 @@ pragma language_version >= 0.23.0;
  * recipient-public.
  *
  * @notice Supply accounting is opt-in: this module tracks NO supply totals.
- * Compose the optional `NativeShieldedTokenSupply` extension only if you need an
+ * Compose the optional `NativeShieldedTokenPublicSupply` extension only if you need an
  * on-chain `totalSupply()`; see it for the privacy trade-off it introduces (it
  * makes contract-mediated burn amounts public).
  *

package/token/NativeShieldedTokenCore.compact

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

package/token/NativeShieldedTokenFamily.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.3.0-alpha (token/NativeShieldedTokenFamily.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (token/NativeShieldedTokenFamily.compact)
 
 pragma language_version >= 0.23.0;
 
@@ -53,7 +53,7 @@ pragma language_version >= 0.23.0;
  * output, at the cost of making those mints recipient-public.
  *
  * @notice Supply accounting is opt-in: this module tracks NO supply totals.
- * Compose the optional `NativeShieldedTokenFamilySupply` extension only if you
+ * Compose the optional `NativeShieldedTokenFamilyPublicSupply` extension only if you
  * need an on-chain `totalSupply(domain)`; see it for the privacy trade-off it
  * introduces (it makes contract-mediated burn amounts public).
  *

package/token/NonFungibleToken.compact

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

package/token/extensions/ConfidentialFungibleTokenPublicSupply.compact

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha.2 (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.2 (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/NativeShieldedTokenFamilyPublicSupply.compact

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.2.0 (token/extensions/NativeShieldedTokenFamilyPublicSupply.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module NativeShieldedTokenFamilyPublicSupply
+ * @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 `NativeShieldedTokenPublicSupplyCore`, 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
+ * `NativeShieldedTokenPublicSupplyCore` 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 `NativeShieldedTokenPublicSupplyCore`.
+ */
+module NativeShieldedTokenFamilyPublicSupply {
+  import CompactStandardLibrary;
+  import "./NativeShieldedTokenPublicSupplyCore" 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
+  // `NativeShieldedTokenPublicSupplyCore__totalMinted`. The circuit names are
+  // intentionally NOT imported unprefixed, to avoid potential clashes.
+  import { _totalMinted, _totalBurned } from "./NativeShieldedTokenPublicSupplyCore";
+  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/NativeShieldedTokenPublicSupply.compact

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.2.0 (token/extensions/NativeShieldedTokenPublicSupply.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module NativeShieldedTokenPublicSupply
+ * @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 `NativeShieldedTokenPublicSupplyCore`, 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
+ * `NativeShieldedTokenPublicSupplyCore` 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
+ * `NativeShieldedTokenPublicSupplyCore`.
+ */
+module NativeShieldedTokenPublicSupply {
+  import CompactStandardLibrary;
+  import "./NativeShieldedTokenPublicSupplyCore" 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
+  // `NativeShieldedTokenPublicSupplyCore__totalMinted`. The circuit names are
+  // intentionally NOT imported unprefixed, to avoid potential clashes.
+  import { _totalMinted, _totalBurned } from "./NativeShieldedTokenPublicSupplyCore";
+  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());
+  }
+}

package/token/extensions/NativeShieldedTokenPublicSupplyCore.compact

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.2.0 (token/extensions/NativeShieldedTokenPublicSupplyCore.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module NativeShieldedTokenPublicSupplyCore
+ * @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:
+ *
+ * - `NativeShieldedTokenPublicSupply` — pairs with `NativeShieldedToken`; forwards a
+ *   single fixed key (the contract has one token type).
+ * - `NativeShieldedTokenFamilyPublicSupply` — pairs with `NativeShieldedTokenFamily`;
+ *   forwards the caller's per-call `domain`.
+ *
+ * @dev Assertion messages use the generic `NativeShieldedTokenPublicSupply:` 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 NativeShieldedTokenPublicSupplyCore {
+  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, "NativeShieldedTokenPublicSupply: 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, "NativeShieldedTokenPublicSupply: burned total exceeds minted");
+    assert(minted - current >= amount, "NativeShieldedTokenPublicSupply: 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>;
+  }
+}