@openzeppelin/compact-contracts 0.2.0 → 0.3.0-alpha

package/security/Allowlist.compact

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (security/Allowlist.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module Allowlist
+ * @description A minimal, reusable permit-list keyed by an abstract `Bytes<32>`
+ * account identifier. It answers a single question: is this account a member?
+ *
+ * This module is a pure membership MECHANISM, not a policy. It holds no notion
+ * of "when" the list is enforced and no access control. The mutators (`_allow`,
+ * `_disallow`) are deliberately UNGATED composable primitives: a composing
+ * contract gates them behind its access-control module (the same way a token
+ * gates `_mint` / `_burn`), and decides when to call `assertAllowed` (for
+ * example, only while an "eligibility required" flag is set). Keeping the
+ * enforce-or-not decision in the composing layer leaves this module general
+ * enough to back KYC allowlists, permissioned mints, membership gates, and the
+ * like.
+ *
+ * @notice This is the PUBLIC (transparent) allowlist: membership status is
+ * publicly readable and the approved set is publicly enumerable. That is the
+ * right posture for transparent or public-graph assets. A graph-private asset
+ * should instead use a shielded allowlist (a public allowlist would re-expose
+ * the candidate set and bound the anonymity set).
+ */
+module Allowlist {
+  import CompactStandardLibrary;
+
+  // ---------------------------------------------------------------------------
+  // State
+  // ---------------------------------------------------------------------------
+
+  /** @description Approved accounts. Absent means not allowed. */
+  export ledger _allowed: Set<Bytes<32>>;
+
+  // ---------------------------------------------------------------------------
+  // Views
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @description Returns whether `account` is currently allowed.
+   *
+   * @circuitInfo k=9, rows=305
+   *
+   * @param {Bytes<32>} account - The account to query.
+   * @return {Boolean} - True if `account` is a member of the allowlist.
+   */
+  export circuit isAllowed(account: Bytes<32>): Boolean {
+    return _allowed.member(disclose(account));
+  }
+
+  // ---------------------------------------------------------------------------
+  // Check (the eligibility seam)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @description Asserts that `account` is allowed. The composing contract
+   * decides when this gate applies.
+   *
+   * @circuitInfo k=9, rows=305
+   *
+   * Requirements:
+   *
+   * - `account` is a member of the allowlist.
+   *
+   * @param {Bytes<32>} account - The account that must be allowed.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit assertAllowed(account: Bytes<32>): [] {
+    assert(isAllowed(account), "Allowlist: account not allowed");
+  }
+
+  // ---------------------------------------------------------------------------
+  // Mutators (UNGATED - the composing contract is responsible for gating these)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @description Adds `account` to the allowlist.
+   *
+   * @circuitInfo k=9, rows=303
+   *
+   * @param {Bytes<32>} account - The account to allow.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _allow(account: Bytes<32>): [] {
+    _allowed.insert(disclose(account));
+  }
+
+  /**
+   * @description Removes `account` from the allowlist.
+   *
+   * @circuitInfo k=9, rows=303
+   *
+   * @param {Bytes<32>} account - The account to disallow.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _disallow(account: Bytes<32>): [] {
+    _allowed.remove(disclose(account));
+  }
+}

package/security/Blocklist.compact

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (security/Blocklist.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module Blocklist
+ * @description A minimal, reusable deny-list keyed by an abstract `Bytes<32>`
+ * account identifier. It answers a single question: is this account blocked?
+ *
+ * This module is a pure membership MECHANISM, not a policy. It holds no notion
+ * of "when" the list is enforced and no access control. The mutators (`_block`,
+ * `_unblock`) are deliberately UNGATED composable primitives: a composing
+ * contract gates them behind its access-control module (the same way a token
+ * gates `_mint` / `_burn`), and decides when to call `assertNotBlocked`. Keeping
+ * the enforce-or-not decision in the composing layer leaves this module general
+ * enough to back sanctions lists, account freezes, abuse denials, and the like.
+ *
+ * @notice This is the PUBLIC (transparent) blocklist: membership status is
+ * publicly readable and the blocked set is publicly enumerable. That is the
+ * right posture for transparent or public-graph assets. A graph-private asset
+ * should instead use a shielded blocklist (a public blocklist would re-expose
+ * the candidate set and bound the anonymity set).
+ */
+module Blocklist {
+  import CompactStandardLibrary;
+
+  // ---------------------------------------------------------------------------
+  // State
+  // ---------------------------------------------------------------------------
+
+  /** @description Blocked accounts. Absent means not blocked. */
+  export ledger _blocked: Set<Bytes<32>>;
+
+  // ---------------------------------------------------------------------------
+  // Views
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @description Returns whether `account` is currently blocked.
+   *
+   * @circuitInfo k=9, rows=305
+   *
+   * @param {Bytes<32>} account - The account to query.
+   * @return {Boolean} - True if `account` is a member of the blocklist.
+   */
+  export circuit isBlocked(account: Bytes<32>): Boolean {
+    return _blocked.member(disclose(account));
+  }
+
+  // ---------------------------------------------------------------------------
+  // Check (the eligibility seam)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @description Asserts that `account` is not blocked. The composing contract
+   * decides when this gate applies.
+   *
+   * @circuitInfo k=9, rows=308
+   *
+   * Requirements:
+   *
+   * - `account` is not a member of the blocklist.
+   *
+   * @param {Bytes<32>} account - The account that must not be blocked.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit assertNotBlocked(account: Bytes<32>): [] {
+    assert(!isBlocked(account), "Blocklist: account blocked");
+  }
+
+  // ---------------------------------------------------------------------------
+  // Mutators (UNGATED - the composing contract is responsible for gating these)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @description Adds `account` to the blocklist.
+   *
+   * @circuitInfo k=9, rows=303
+   *
+   * @param {Bytes<32>} account - The account to block.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _block(account: Bytes<32>): [] {
+    _blocked.insert(disclose(account));
+  }
+
+  /**
+   * @description Removes `account` from the blocklist.
+   *
+   * @circuitInfo k=9, rows=303
+   *
+   * @param {Bytes<32>} account - The account to unblock.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _unblock(account: Bytes<32>): [] {
+    _blocked.remove(disclose(account));
+  }
+}

package/security/Initializable.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (security/Initializable.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha (security/Initializable.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module Initializable

package/security/Pausable.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (security/Pausable.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha (security/Pausable.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module Pausable

package/token/FungibleToken.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (token/FungibleToken.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha (token/FungibleToken.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module FungibleToken
@@ -111,19 +111,6 @@ module FungibleToken {
    */
   witness wit_FungibleTokenSK(): Bytes<32>;
 
-  /**
-   * @description Returns a canonical zero Either value for Bytes<32> and ContractAddress.
-   * This circuit returns the left variant (Bytes<32>) to avoid misleading contract-to-contract
-   * error messages.
-   *
-   * @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, symbol, and decimals.
    * @dev This MUST be called in the implementing contract's constructor. Failure to do so
@@ -509,8 +496,8 @@ module FungibleToken {
                    value: Uint<128>
                    ): [] {
     assertInitialized();
-    assert(!_isTargetZero(fromAddress), "FungibleToken: invalid sender");
-    assert(!_isTargetZero(to), "FungibleToken: invalid receiver");
+    assert(!Utils_isTargetZero(fromAddress), "FungibleToken: invalid sender");
+    assert(!Utils_isTargetZero(to), "FungibleToken: invalid receiver");
 
     _update(fromAddress, to, value);
   }
@@ -539,7 +526,7 @@ module FungibleToken {
     const canonFrom = Utils_canonicalize<Bytes<32>, ContractAddress>(fromAddress);
     const canonTo = Utils_canonicalize<Bytes<32>, ContractAddress>(to);
 
-    if (_isTargetZero(disclose(canonFrom))) {
+    if (Utils_isTargetZero(disclose(canonFrom))) {
       // Mint
       const MAX_UINT128 = 340282366920938463463374607431768211455;
       assert(MAX_UINT128 - _totalSupply >= value, "FungibleToken: arithmetic overflow");
@@ -551,7 +538,7 @@ module FungibleToken {
       _balances.insert(disclose(canonFrom), disclose(fromBal - value as Uint<128>));
     }
 
-    if (_isTargetZero(disclose(canonTo))) {
+    if (Utils_isTargetZero(disclose(canonTo))) {
       // Burn
       _totalSupply = disclose(_totalSupply - value as Uint<128>);
     } else {
@@ -610,8 +597,8 @@ module FungibleToken {
                    value: Uint<128>
                    ): [] {
     assertInitialized();
-    assert(!_isTargetZero(account), "FungibleToken: invalid receiver");
-    _update(ZERO(), account, value);
+    assert(!Utils_isTargetZero(account), "FungibleToken: invalid receiver");
+    _update(Utils_zeroAccount(), account, value);
   }
 
   /**
@@ -632,8 +619,8 @@ module FungibleToken {
    */
   export circuit _burn(account: Either<Bytes<32>, ContractAddress>, value: Uint<128>): [] {
     assertInitialized();
-    assert(!_isTargetZero(account), "FungibleToken: invalid sender");
-    _update(account, ZERO(), value);
+    assert(!Utils_isTargetZero(account), "FungibleToken: invalid sender");
+    _update(account, Utils_zeroAccount(), value);
   }
 
   /**
@@ -663,8 +650,8 @@ module FungibleToken {
     const canonOwner = Utils_canonicalize<Bytes<32>, ContractAddress>(owner);
     const canonSpender = Utils_canonicalize<Bytes<32>, ContractAddress>(spender);
 
-    assert(!_isTargetZero(canonOwner), "FungibleToken: invalid owner");
-    assert(!_isTargetZero(canonSpender), "FungibleToken: invalid spender");
+    assert(!Utils_isTargetZero(canonOwner), "FungibleToken: invalid owner");
+    assert(!Utils_isTargetZero(canonSpender), "FungibleToken: invalid spender");
 
     if (!_allowances.member(disclose(canonOwner))) {
       // If owner doesn't exist, create and insert a new sub-map directly
@@ -701,16 +688,17 @@ module FungibleToken {
     const canonOwner = Utils_canonicalize<Bytes<32>, ContractAddress>(owner);
     const canonSpender = Utils_canonicalize<Bytes<32>, ContractAddress>(spender);
 
-    assert((_allowances.member(disclose(canonOwner)) &&
-            _allowances.lookup(canonOwner).member(disclose(canonSpender))),
-           "FungibleToken: insufficient allowance"
-           );
-
-    const currentAllowance = _allowances.lookup(canonOwner).lookup(disclose(canonSpender));
-    const MAX_UINT128 = 340282366920938463463374607431768211455;
-    if (currentAllowance < MAX_UINT128) {
-      assert(currentAllowance >= value, "FungibleToken: insufficient allowance");
-      _approve(canonOwner, canonSpender, currentAllowance - value as Uint<128>);
+    // A missing allowance entry is treated as a zero allowance, mirroring
+    // `allowance`, and a zero-value spend is a no-op. Guarding on `value`
+    // avoids reverting (outside an assertion) on a missing entry and avoids
+    // writing a spurious zero entry for a zero-value spend.
+    if (disclose(value > 0)) {
+      const currentAllowance = allowance(canonOwner, canonSpender);
+      const MAX_UINT128 = 340282366920938463463374607431768211455;
+      if (currentAllowance < MAX_UINT128) {
+        assert(currentAllowance >= value, "FungibleToken: insufficient allowance");
+        _approve(canonOwner, canonSpender, currentAllowance - value as Uint<128>);
+      }
     }
   }
 
@@ -725,52 +713,6 @@ module FungibleToken {
    * @returns {Bytes<32>} accountId - The computed account identifier.
    */
   circuit _computeAccountId(): Bytes<32> {
-    return computeAccountId(wit_FungibleTokenSK());
-  }
-
-  /**
-   * @description Computes an account identifier without on-chain state, allowing a user to derive
-   * their identity commitment before submitting 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_FungibleTokenSK());
   }
 }

package/token/MultiToken.compact

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.2.0 (token/MultiToken.compact)
+// OpenZeppelin Compact Contracts v0.3.0-alpha (token/MultiToken.compact)
 
-pragma language_version >= 0.21.0;
+pragma language_version >= 0.23.0;
 
 /**
  * @module MultiToken
@@ -173,25 +173,6 @@ module MultiToken {
    */
   witness wit_MultiTokenSK(): Bytes<32>;
 
-  /**
-   * @description Returns a canonical zero Either value (left variant with zero Bytes<32>).
-   * Used as the zero value for mint/burn operations in `_update`, where a zero
-   * `fromAddress` signals a mint and a zero `to` signals a burn.
-   *
-   * The left variant is chosen so that `_isTargetZero` checks against `default<Bytes<32>>`,
-   * which is consistent with how `_update` dispatches on the zero check. A right variant
-   * with `default<ContractAddress>` would also pass `_isTargetZero`, but using the left
-   * variant avoids triggering contract address guards in circuits like `_mint` that check
-   * `!to.is_left` before delegating to `_unsafeMint`.
-   *
-   * @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 base URI for all tokens.
    *
@@ -441,14 +422,20 @@ module MultiToken {
     const canonFrom = Utils_canonicalize<Bytes<32>, ContractAddress>(fromAddress);
     const canonTo = Utils_canonicalize<Bytes<32>, ContractAddress>(to);
 
-    if (!_isTargetZero(disclose(canonFrom))) {
+    if (!Utils_isTargetZero(disclose(canonFrom))) {
       const fromBalance = balanceOf(canonFrom, id);
       assert(fromBalance >= value, "MultiToken: insufficient balance");
-      const newBalance = fromBalance - value;
-      _balances.lookup(id).insert(disclose(canonFrom), disclose(newBalance));
+      // Skip the write when `value` is zero. A zero-value update leaves the
+      // balance unchanged, so there is nothing to write, and guarding here
+      // avoids `_balances.lookup(id)` reverting outside an assertion when `id`
+      // has never been initialized.
+      if (disclose(value > 0)) {
+        const newBalance = fromBalance - value;
+        _balances.lookup(id).insert(disclose(canonFrom), disclose(newBalance));
+      }
     }
 
-    if (!_isTargetZero(disclose(canonTo))) {
+    if (!Utils_isTargetZero(disclose(canonTo)) && disclose(value > 0)) {
       if (!_balances.member(disclose(id))) {
         _balances.insert(
           disclose(id),
@@ -540,8 +527,8 @@ module MultiToken {
                    ): [] {
     assertInitialized();
 
-    assert(!_isTargetZero(fromAddress), "MultiToken: invalid sender");
-    assert(!_isTargetZero(to), "MultiToken: invalid receiver");
+    assert(!Utils_isTargetZero(fromAddress), "MultiToken: invalid sender");
+    assert(!Utils_isTargetZero(to), "MultiToken: invalid receiver");
     _update(fromAddress, to, id, value);
   }
 
@@ -627,8 +614,8 @@ module MultiToken {
                    value: Uint<128>
                    ): [] {
     assertInitialized();
-    assert(!_isTargetZero(to), "MultiToken: invalid receiver");
-    _update(ZERO(), to, id, value);
+    assert(!Utils_isTargetZero(to), "MultiToken: invalid receiver");
+    _update(Utils_zeroAccount(), to, id, value);
   }
 
   /**
@@ -652,8 +639,8 @@ module MultiToken {
                        value: Uint<128>
                        ): [] {
     assertInitialized();
-    assert(!_isTargetZero(fromAddress), "MultiToken: invalid sender");
-    _update(fromAddress, ZERO(), id, value);
+    assert(!Utils_isTargetZero(fromAddress), "MultiToken: invalid sender");
+    _update(fromAddress, Utils_zeroAccount(), id, value);
   }
 
   /**
@@ -684,10 +671,10 @@ module MultiToken {
                    ): [] {
     assertInitialized();
     const canonOwner = Utils_canonicalize<Bytes<32>, ContractAddress>(owner);
-    assert(!_isTargetZero(canonOwner), "MultiToken: invalid owner");
+    assert(!Utils_isTargetZero(canonOwner), "MultiToken: invalid owner");
 
     const canonOp = Utils_canonicalize<Bytes<32>, ContractAddress>(operator);
-    assert(!_isTargetZero(canonOp), "MultiToken: invalid operator");
+    assert(!Utils_isTargetZero(canonOp), "MultiToken: invalid operator");
 
     if (!_operatorApprovals.member(disclose(canonOwner))) {
       _operatorApprovals.insert(
@@ -710,52 +697,6 @@ module MultiToken {
    * @returns {Bytes<32>} accountId - The computed account identifier.
    */
   circuit _computeAccountId(): Bytes<32> {
-    return computeAccountId(wit_MultiTokenSK());
-  }
-
-  /**
-   * @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_MultiTokenSK());
   }
 }