@openzeppelin/compact-contracts 0.2.0 → 0.3.0-alpha

package/token/NativeShieldedTokenFamily.compact

@@ -0,0 +1,287 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (token/NativeShieldedTokenFamily.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module NativeShieldedTokenFamily
+ * @description A module for issuing a FAMILY of native shielded (Zswap)
+ * token types from one contract, discriminated by a per-call domain.
+ *
+ * This flavor exists because of Midnight's composition model: there is no
+ * contract-to-contract interaction and no way for a contract to deploy
+ * another, so the Ethereum pattern of one token contract per asset (stamped
+ * out by a factory) is unavailable. A protocol that issues many related
+ * tokens — e.g. a DEX minting one liquidity-share token per pair — must do
+ * so from a single contract, which the protocol's color derivation
+ * (`tokenType(domain, contractAddress)`) natively supports. For a
+ * single-token issuer, use `NativeShieldedToken` instead.
+ *
+ * This module is a thin wrapper over `NativeShieldedTokenCore`: it forwards the
+ * caller's per-call `domain` to every core op, so the mint/burn logic and
+ * metadata live in the shared core, not here.
+ *
+ * @notice A contract MUST NOT import both `NativeShieldedTokenFamily` and
+ * `NativeShieldedToken`. Both wrap `NativeShieldedTokenCore`, so they share one
+ * set of core state (a single init flag and one name/symbol/decimals).
+ * Pick one flavor per contract.
+ *
+ * @notice This module exposes composable building blocks for minting and
+ * burning native shielded coins. It does NOT include access control: consuming
+ * contracts compose that via the module/contract pattern (Ownable,
+ * AccessControl, etc.) and SHOULD gate the mint and burn circuits, which are
+ * unrestricted at the module level.
+ *
+ * @dev The `domain` parameter is passed explicitly per-call; the coin's `color`
+ * is `tokenType(domain, kernel.self())`, so the domain discriminates the token
+ * types within this contract (e.g. one LP share token per pair) and only this
+ * contract can mint coins of its colors. Metadata is contract-wide FAMILY
+ * metadata, following the Uniswap-V2 LP precedent: every token type shares one
+ * brand, and per-type identity belongs in the consumer's own state (e.g. a pair
+ * registry mapping domain -> underlying tokens), which is strictly more
+ * informative than a stored string. `decimals` applies family-wide; issuers
+ * with heterogeneous decimals should add their own per-domain handling. Mint
+ * amounts are `Uint<64>`, burn amounts `Uint<128>` — an asymmetry imposed by
+ * the protocol primitives, not a module choice. The mint/burn mechanics and the
+ * `_burn` vs `_burnFromSelf` spend paths live in `NativeShieldedTokenCore`.
+ *
+ * @notice With a secret, cryptographically random `_mint` nonce the mint is
+ * recipient-private; the caller is responsible for nonce uniqueness (a reused
+ * nonce for the same (domain, value, recipient) produces a duplicate
+ * commitment, which the ledger rejects). For mints that need no caller-managed
+ * nonce, compose `NativeShieldedTokenDerivedNonce` and pass its `_deriveNonce()`
+ * 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
+ * need an on-chain `totalSupply(domain)`; see it for the privacy trade-off it
+ * introduces (it makes contract-mediated burn amounts public).
+ *
+ * @notice Out of scope (phase two, pending contract-to-contract support):
+ * `balanceOf`, `allowance`, transfer mediation, batch operations, and operator
+ * approvals are not representable for native shielded UTXOs — once a user holds
+ * a coin, the contract cannot observe or restrict its movement.
+ */
+module NativeShieldedTokenFamily {
+  import CompactStandardLibrary;
+  import "./NativeShieldedTokenCore" prefix Core_;
+
+  // Circuits use the `Core_` prefix above. The named import/re-export below is
+  // only for the core state variables, so the implementing contract's ledger
+  // keys read as `_name` etc. rather than `NativeShieldedTokenCore__name`. The
+  // circuit names are intentionally NOT imported unprefixed, to avoid potential clashes.
+  import { _name, _symbol, _decimals, _isInitialized } from "./NativeShieldedTokenCore";
+  export { _name, _symbol, _decimals, _isInitialized };
+
+  /**
+   * @description Initializes the module's family metadata.
+   * @dev This MUST be called in the implementing contract's constructor, and it
+   * MUST be the only token operation performed there. Failure to call it can
+   * lead to an irreparable contract; perform mint, burn, and `tokenColor` only
+   * in post-deployment circuits, never in the constructor.
+   *
+   * @param {Opaque<"string">} name_ - The family name shared by all token types.
+   * @param {Opaque<"string">} symbol_ - The family symbol shared by all token types.
+   * @param {Uint<8>} decimals_ - The family-wide number of decimals used to
+   * get the user representation.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit initialize(
+                   name_: Opaque<"string">,
+                   symbol_: Opaque<"string">,
+                   decimals_: Uint<8>
+                   ): [] {
+    Core_initialize(name_, symbol_, decimals_);
+  }
+
+  /**
+   * @description Returns whether the contract has been initialized.
+   *
+   * @circuitInfo k=6, rows=26
+   *
+   * @return {Boolean} - True once `initialize` has run.
+   */
+  export circuit isInitialized(): Boolean {
+    return Core_isInitialized();
+  }
+
+  /**
+   * @description Returns the family name shared by all token types of this
+   * contract. Per-type identity belongs in the consumer's own state; see the
+   * module notes.
+   *
+   * @circuitInfo k=6, rows=28
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   *
+   * @return {Opaque<"string">} - The family name.
+   */
+  export circuit name(): Opaque<"string"> {
+    return Core_name();
+  }
+
+  /**
+   * @description Returns the family symbol shared by all token types of this
+   * contract.
+   *
+   * @circuitInfo k=6, rows=28
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   *
+   * @return {Opaque<"string">} - The family symbol.
+   */
+  export circuit symbol(): Opaque<"string"> {
+    return Core_symbol();
+  }
+
+  /**
+   * @description Returns the family-wide number of decimals used to get the
+   * user representation.
+   *
+   * @circuitInfo k=6, rows=28
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   *
+   * @return {Uint<8>} - The decimals value.
+   */
+  export circuit decimals(): Uint<8> {
+    return Core_decimals();
+  }
+
+  /**
+   * @description Returns the coin color (token type) for `domain` under this
+   * contract's address, so integrators do not have to re-derive it by hand.
+   *
+   * @circuitInfo k=13, rows=4248
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator.
+   * @return {Bytes<32>} - The coin color: `tokenType(domain, kernel.self())`.
+   */
+  export circuit tokenColor(domain: Bytes<32>): Bytes<32> {
+    return Core_tokenColor(domain);
+  }
+
+  /**
+   * @description Mints `amount` of the token identified by `domain` to
+   * `recipient`, using a caller-supplied nonce.
+   *
+   * @dev The caller is fully responsible for nonce uniqueness. Reusing a
+   * nonce for the same (domain, value, recipient) produces a duplicate
+   * commitment, which the protocol rejects. With a secret random nonce this
+   * is the recipient-private mint. For mints that require no caller-managed
+   * nonce, compose the `NativeShieldedTokenDerivedNonce` extension and pass
+   * its `_deriveNonce()` output.
+   *
+   * @notice The returned coin info is the only copy available to the
+   * recipient; callers SHOULD deliver it out of band. Wallets cannot detect
+   * contract-minted coins by scanning the chain.
+   *
+   * @circuitInfo k=14, rows=11119
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   * - `recipient` is not zero.
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator. Same domain + same
+   * contract address produces the same coin color (i.e. same token type).
+   * @param {Either<ZswapCoinPublicKey, ContractAddress>} recipient - The coin recipient.
+   * @param {Uint<64>} amount - Quantity to mint. Capped at `Uint<64>` by the protocol.
+   * @param {Bytes<32>} nonce - Caller-supplied nonce. Must be unique per (domain, contract).
+   * @return {ShieldedCoinInfo} - The newly created coin's info (nonce, color, value).
+   */
+  export circuit _mint(
+                   domain: Bytes<32>,
+                   recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+                   amount: Uint<64>,
+                   nonce: Bytes<32>
+                   ): ShieldedCoinInfo {
+    return Core__mint(domain, recipient, amount, nonce);
+  }
+
+  /**
+   * @description Burns `amount` from `coin`, a coin provided within the
+   * current transaction (e.g. paid in by the caller's wallet), and routes the
+   * remaining change to `refundTo`.
+   *
+   * To destroy `coin` in full, pass `coin.value` as `amount`; the change
+   * branch will not fire and `none` is returned. The `refundTo` value is
+   * inert in that case but must still be supplied and non-zero.
+   *
+   * @dev The coin is received by the contract and spent in the same
+   * transaction, so the spend goes through `sendImmediateShielded` (the
+   * transient path). For coins the contract already holds, use
+   * `_burnFromSelf` instead.
+   *
+   * @notice The returned refund coin info is the only copy available to
+   * `refundTo`; callers SHOULD deliver it out of band. Wallets cannot detect
+   * contract-sent coins by scanning the chain.
+   *
+   * @circuitInfo k=16, rows=47932
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   * - `coin.color` is this contract's token type for `domain`.
+   * - `amount` is less than or equal to `coin.value`.
+   * - `refundTo` is not zero (the zero key is the burn address; a zero
+   *   `refundTo` would silently burn the change as well).
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator.
+   * @param {ShieldedCoinInfo} coin - The coin to burn from.
+   * @param {Uint<128>} amount - Value to destroy. Must be <= `coin.value`.
+   * @param {Either<ZswapCoinPublicKey, ContractAddress>} refundTo - Where to
+   * route the unspent portion (`coin.value - amount`).
+   * @return {Maybe<ShieldedCoinInfo>} - The refund coin created for `refundTo`,
+   * or `none` if the coin was burned in full.
+   */
+  export circuit _burn(
+                   domain: Bytes<32>,
+                   coin: ShieldedCoinInfo,
+                   amount: Uint<128>,
+                   refundTo: Either<ZswapCoinPublicKey, ContractAddress>
+                   ): Maybe<ShieldedCoinInfo> {
+    return Core__burn(domain, coin, amount, refundTo);
+  }
+
+  /**
+   * @description Burns `amount` from `coin`, a coin this contract already
+   * holds (a Merkle-tree entry with a valid `mt_index`). Any change is
+   * auto-received by the contract and returned.
+   *
+   * @dev The consumer SHOULD persist the returned change coin info in its own
+   * ledger state: the change replaces `coin` as the contract's holding, and
+   * its info is not otherwise recoverable.
+   *
+   * @circuitInfo k=15, rows=23583
+   *
+   * Requirements:
+   *
+   * - Contract is initialized.
+   * - `coin.color` is this contract's token type for `domain`.
+   * - `amount` is less than or equal to `coin.value`.
+   *
+   * @param {Bytes<32>} domain - 32-byte token discriminator.
+   * @param {QualifiedShieldedCoinInfo} coin - The contract-held coin to burn from.
+   * @param {Uint<128>} amount - Value to destroy. Must be <= `coin.value`.
+   * @return {Maybe<ShieldedCoinInfo>} - The change coin retained by the
+   * contract, or `none` if the coin was burned in full.
+   */
+  export circuit _burnFromSelf(
+                   domain: Bytes<32>,
+                   coin: QualifiedShieldedCoinInfo,
+                   amount: Uint<128>
+                   ): Maybe<ShieldedCoinInfo> {
+    return Core__burnFromSelf(domain, coin, amount);
+  }
+}

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 (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/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 (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;
+  }
 }