@lfdecentralizedtrust/zeto-contracts 0.2.2 → 0.5.0

package/contracts/lib/interfaces/IZetoStorage.sol

@@ -0,0 +1,106 @@
+// Copyright © 2025 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+pragma solidity ^0.8.27;
+
+interface IZetoStorage {
+    enum UTXOStatus {
+        UNKNOWN, // default value for the empty UTXO slots
+        UNSPENT,
+        SPENT
+    }
+
+    // For the main UTXO storage
+
+    /**
+     * @dev query whether a UTXO is currently spent
+     * @param txo The UTXO to check
+     * @return bool whether the UTXO is spent
+     */
+    function spent(uint256 txo) external view returns (UTXOStatus);
+
+    /**
+     * @dev validate the inputs
+     * @param inputs The inputs to validate
+     * @param inputsLocked Whether the inputs are locked
+     */
+    function validateInputs(
+        uint256[] calldata inputs,
+        bool inputsLocked
+    ) external view;
+
+    /**
+     * @dev validate the outputs
+     * @param outputs The outputs to validate
+     */
+    function validateOutputs(uint256[] calldata outputs) external view;
+
+    /**
+     * @dev validate the root
+     * @param root The root to validate
+     * @return bool whether the root is valid
+     */
+    function validateRoot(uint256 root) external view returns (bool);
+
+    /**
+     * @dev get the root
+     * @return uint256 the root
+     */
+    function getRoot() external view returns (uint256);
+
+    /**
+     * @dev process the inputs
+     * @param inputs The inputs to process
+     * @param inputsLocked Whether the inputs are locked
+     */
+    function processInputs(
+        uint256[] calldata inputs,
+        bool inputsLocked
+    ) external;
+
+    /**
+     * @dev process the outputs
+     * @param outputs The outputs to process
+     */
+    function processOutputs(uint256[] calldata outputs) external;
+
+    /**
+     * @dev Register freshly-minted locked UTXOs in the locked-UTXO ledger.
+     *
+     *      The storage layer is intentionally a thin UTXO substrate and
+     *      does NOT track who is allowed to spend a locked UTXO; that
+     *      responsibility belongs to the Zeto contract on top (e.g. the
+     *      lock-id-keyed `_locks[lockId].spender` in
+     *      `ZetoFungible`-style lockable-capability contracts). Callers
+     *      that need delegate/spender semantics must maintain that state
+     *      themselves above this interface.
+     *
+     * @param lockedOutputs The locked UTXOs to register as UNSPENT
+     */
+    function processLockedOutputs(uint256[] calldata lockedOutputs) external;
+
+    /**
+     * @dev Query whether a UTXO is currently in the locked-unspent set.
+     *
+     *      The delegate / spender of the lock is intentionally NOT
+     *      returned here: the storage layer no longer tracks it. To
+     *      surface the spender alongside the locked-state, expose the
+     *      combined view at the Zeto layer instead.
+     *
+     * @param utxo The UTXO to check
+     * @return whether the UTXO is currently locked-unspent
+     */
+    function locked(uint256 utxo) external view returns (bool);
+}

package/contracts/lib/interfaces/{izeto_lockable.sol → IZetoVerifier.sol}

@@ -1,4 +1,4 @@
-// Copyright © 2024 Kaleido, Inc.
+// Copyright © 2025 Kaleido, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
 //
@@ -15,24 +15,11 @@
 // limitations under the License.
 pragma solidity ^0.8.27;
 
-import {Commonlib} from "../common.sol";
-
-interface IZetoLockable {
-    error UTXOAlreadyLocked(uint256 utxo);
-    error UTXONotLocked(uint256 utxo);
-    error NotLockDelegate(uint256 utxo, address delegate, address sender);
-    event UTXOsLocked(
-        uint256[] inputs,
-        uint256[] outputs,
-        uint256[] lockedOutputs,
-        address indexed delegate,
-        address indexed submitter,
-        bytes data
-    );
-    event LockDelegateChanged(
-        uint256[] lockedOutputs,
-        address indexed oldDelegate,
-        address indexed newDelegate,
-        bytes data
-    );
+interface IGroth16Verifier {
+    function verify(
+        uint[2] calldata _pA,
+        uint[2][2] calldata _pB,
+        uint[2] calldata _pC,
+        uint[] calldata _pubSignals
+    ) external view returns (bool);
 }

package/contracts/lib/registry.sol

@@ -15,81 +15,129 @@
 // limitations under the License.
 pragma solidity ^0.8.27;
 
-import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+import {Ownable2StepUpgradeable} from "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
 import {SmtLib} from "@iden3/contracts/contracts/lib/SmtLib.sol";
 import {PoseidonHasher} from "@iden3/contracts/contracts/lib/hash/PoseidonHasher.sol";
 import {PoseidonUnit2L, PoseidonUnit3L} from "@iden3/contracts/contracts/lib/Poseidon.sol";
-import {Commonlib} from "./common.sol";
-import {IZeto} from "./interfaces/izeto.sol";
-import {IZetoKyc} from "./interfaces/izeto_kyc.sol";
-
-uint256 constant MAX_SMT_DEPTH = 64;
+import {MAX_SMT_DEPTH} from "./interfaces/IZeto.sol";
+import {IZetoKyc} from "./interfaces/IZetoKyc.sol";
 
 /// @title A sample on-chain implementation of a KYC registry
+/// @author Kaleido, Inc.
 /// @dev The registry uses a Sparse Merkle Tree to store the
 ///   Zeto accounts (Babyjubjub keys), so that transaction
 ///   submitters can generate proofs of membership for the
 ///   accounts in a privacy-preserving manner.
-/// @author Kaleido, Inc.
-abstract contract Registry is OwnableUpgradeable, IZetoKyc {
-    SmtLib.Data internal _publicKeysTree;
+///
+///   Mixed into KYC-aware concrete tokens (e.g. {Zeto_AnonNullifierKyc})
+///   so that those tokens can expose `register`/`isRegistered` and
+///   contribute the identities tree's root as an additional public input
+///   to the transfer/deposit ZK circuits via the inheriting token's
+///   {extraInputs}/{extraInputsForDeposit} overrides.
+///
+///   Inherits {Ownable2StepUpgradeable} (rather than the simpler
+///   {OwnableUpgradeable}) so that the diamond formed when this mixin is
+///   composed with a token that already inherits {ZetoCommon}, which is
+///   itself {Ownable2StepUpgradeable}, resolves cleanly: both branches of
+///   the inheritance graph reach `transferOwnership`/`_transferOwnership`
+///   through the same {Ownable2StepUpgradeable} implementation, so no
+///   leaf-level override is required. The Ownable initialization itself
+///   is performed once by the token's `__ZetoCommon_init`; the Registry
+///   initializer only needs to set up the SMT.
+abstract contract Registry is Ownable2StepUpgradeable, IZetoKyc {
     using SmtLib for SmtLib.Data;
 
-    error AlreadyRegistered(uint256[2]);
+    /// @dev Thrown by {register} when the supplied public key is already
+    ///      a member of the identities tree.
+    error AlreadyRegistered(uint256[2] publicKey);
 
+    /// @dev Internal-only so it can only be called from a derived
+    ///      contract's own `initializer`-guarded entrypoint.
     function __Registry_init() internal onlyInitializing {
-        _publicKeysTree.initialize(MAX_SMT_DEPTH);
-        _publicKeysTree.setHasher(new PoseidonHasher());
+        RegistryStorage.Layout storage $ = RegistryStorage.layout();
+        $.publicKeysTree.initialize(MAX_SMT_DEPTH);
+        $.publicKeysTree.setHasher(new PoseidonHasher());
     }
 
+    /**
+     * @dev Register a new Zeto account.
+     * @param publicKey The public Babyjubjub key to register.
+     * @param data Opaque off-chain correlation data appended to the
+     *             {IdentityRegistered} event.
+     *
+     * Emits an {IdentityRegistered} event.
+     */
     function register(
-        uint256[2] memory publicKey,
+        uint256[2] calldata publicKey,
         bytes calldata data
     ) public onlyOwner {
         _register(publicKey, data);
     }
 
-    /// @dev returns whether the given public key is registered
-    /// @param publicKey The Babyjubjub public key to check
-    /// @return bool whether the given public key is included in the registry
+    /**
+     * @dev Returns whether the given public key is registered.
+     * @param publicKey The Babyjubjub public key to check.
+     */
     function isRegistered(
-        uint256[2] memory publicKey
+        uint256[2] calldata publicKey
     ) public view returns (bool) {
         uint256 nodeKey = _getIdentitiesLeafNodeKey(publicKey);
-        SmtLib.Node memory node = _publicKeysTree.getNode(nodeKey);
+        SmtLib.Node memory node = RegistryStorage.layout().publicKeysTree.getNode(
+            nodeKey
+        );
         return node.nodeType != SmtLib.NodeType.EMPTY;
     }
 
+    /**
+     * @dev Returns the root of the identities tree. This is contributed as
+     *      an extra public input to the transfer / deposit circuits in
+     *      KYC-aware token contracts via {extraInputs}.
+     */
     function getIdentitiesRoot() public view returns (uint256) {
-        return _publicKeysTree.getRoot();
+        return RegistryStorage.layout().publicKeysTree.getRoot();
     }
 
-    /// @dev Register a new Zeto account
-    /// @param publicKey The public Babyjubjub key to register
     function _register(
-        uint256[2] memory publicKey,
+        uint256[2] calldata publicKey,
         bytes calldata data
     ) internal {
         uint256 nodeHash = _getIdentitiesLeafNodeHash(publicKey);
-        SmtLib.Node memory node = _publicKeysTree.getNode(nodeHash);
+        RegistryStorage.Layout storage $ = RegistryStorage.layout();
+        SmtLib.Node memory node = $.publicKeysTree.getNode(nodeHash);
         if (node.nodeType != SmtLib.NodeType.EMPTY) {
             revert AlreadyRegistered(publicKey);
         }
-        _publicKeysTree.addLeaf(nodeHash, nodeHash);
+        $.publicKeysTree.addLeaf(nodeHash, nodeHash);
         emit IdentityRegistered(publicKey, data);
     }
 
     function _getIdentitiesLeafNodeHash(
-        uint256[2] memory publicKey
+        uint256[2] calldata publicKey
     ) internal pure returns (uint256) {
         return PoseidonUnit2L.poseidon(publicKey);
     }
 
     function _getIdentitiesLeafNodeKey(
-        uint256[2] memory publicKey
+        uint256[2] calldata publicKey
     ) internal pure returns (uint256) {
         uint256 nodeHash = PoseidonUnit2L.poseidon(publicKey);
         uint256[3] memory params = [nodeHash, nodeHash, uint256(1)];
         return PoseidonUnit3L.poseidon(params);
     }
 }
+
+/// @dev ERC-7201 (`erc7201:zeto.storage.Registry`).
+library RegistryStorage {
+    struct Layout {
+        SmtLib.Data publicKeysTree;
+    }
+
+    bytes32 private constant STORAGE_LOCATION =
+        0xf79d6fea6eabe5c80b325fcf2331fe08f18a473c50e27c55890676ff6746fd00;
+
+    function layout() internal pure returns (Layout storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
+}

package/contracts/lib/storage/base.sol

@@ -0,0 +1,210 @@
+// Copyright © 2025 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+pragma solidity ^0.8.27;
+
+import {IZetoConstants} from "../interfaces/IZeto.sol";
+import {IZetoLockableCapability} from "../interfaces/IZetoLockableCapability.sol";
+import {IZetoStorage} from "../interfaces/IZetoStorage.sol";
+import {Commonlib} from "../common/common.sol";
+import {Util} from "../common/util.sol";
+
+contract BaseStorage is IZetoStorage, IZetoConstants {
+    /// @dev Thrown when a state-mutating storage call is made by anyone other
+    ///      than the Zeto contract that deployed this storage instance.
+    error StorageUnauthorized(address caller);
+
+    /// @dev Thrown by view stubs that only have a meaningful implementation
+    ///      in nullifier-based storage (e.g. {validateRoot}, {getRoot}).
+    ///      Replaces the previous `revert("Not implemented")` strings so
+    ///      callers can match a typed error.
+    error NotImplemented();
+
+    /**
+     * @dev The Zeto contract that owns this storage instance. Captured at
+     *      construction time and immutable for the lifetime of the storage
+     *      contract. All state-mutating entry points are gated to this
+     *      address; view functions remain unrestricted.
+     *
+     *      This storage contract is created via `new BaseStorage()` (or a
+     *      subclass) from inside the Zeto contract's initializer, so
+     *      `msg.sender` at construction is the Zeto proxy address.
+     */
+    address internal immutable _zeto;
+
+    // tracks all the regular (unlocked) UTXOs
+    mapping(uint256 => UTXOStatus) internal _utxos;
+    // used for tracking locked UTXOs. multi-step transaction flows that require counterparties
+    // to upload proofs. To protect the party that uploads their proof first,
+    // and prevent any other party from utilizing the uploaded proof to execute
+    // a transaction, the input UTXOs or nullifiers can be locked and only usable
+    // by the same party that did the locking.
+    //
+    // The "who is allowed to spend a locked UTXO" question is intentionally
+    // NOT answered at this layer; the Zeto contract on top owns that state
+    // (e.g. `_locks[lockId].spender` in ZetoFungible-style lockable
+    // capabilities). This contract only tracks whether the UTXO is locked.
+    mapping(uint256 => UTXOStatus) internal _lockedUtxos;
+
+    /// @dev Reverts unless the caller is the Zeto contract that deployed this
+    ///      storage instance. Applied to every state-mutating function so the
+    ///      storage contract cannot be poked directly by external accounts.
+    modifier onlyZeto() {
+        if (msg.sender != _zeto) {
+            revert StorageUnauthorized(msg.sender);
+        }
+        _;
+    }
+
+    constructor() {
+        _zeto = msg.sender;
+    }
+
+    /// @notice Returns the address authorized to call state-mutating
+    ///         functions on this storage contract.
+    function zeto() external view returns (address) {
+        return _zeto;
+    }
+
+    function validateInputs(
+        uint256[] calldata inputs,
+        bool inputsLocked
+    ) public view virtual {
+        // sort the inputs to detect duplicates
+        uint256[] memory sortedInputs = Util.sortCommitments(inputs);
+        // Check the inputs are all unspent
+        for (uint256 i = 0; i < sortedInputs.length; ++i) {
+            if (sortedInputs[i] == 0) {
+                // skip the zero inputs
+                continue;
+            }
+            if (i > 0 && sortedInputs[i] == sortedInputs[i - 1]) {
+                revert UTXODuplicate(sortedInputs[i]);
+            }
+            if (
+                _lockedUtxos[sortedInputs[i]] == UTXOStatus.UNKNOWN &&
+                _utxos[sortedInputs[i]] == UTXOStatus.UNKNOWN
+            ) {
+                revert UTXONotMinted(sortedInputs[i]);
+            }
+            if (
+                _lockedUtxos[sortedInputs[i]] == UTXOStatus.SPENT ||
+                _utxos[sortedInputs[i]] == UTXOStatus.SPENT
+            ) {
+                revert UTXOAlreadySpent(sortedInputs[i]);
+            }
+            if (
+                !inputsLocked &&
+                _lockedUtxos[sortedInputs[i]] == UTXOStatus.UNSPENT
+            ) {
+                revert IZetoLockableCapability.AlreadyLocked(sortedInputs[i]);
+            }
+        }
+    }
+
+    function validateOutputs(uint256[] calldata outputs) public view virtual {
+        // sort the outputs to detect duplicates
+        uint256[] memory sortedOutputs = Util.sortCommitments(outputs);
+
+        // Check for duplicate outputs
+        for (uint256 i = 0; i < sortedOutputs.length; ++i) {
+            uint256 output = sortedOutputs[i];
+            if (output == 0) {
+                // skip the zero outputs
+                continue;
+            }
+            if (i > 0 && output == sortedOutputs[i - 1]) {
+                revert UTXODuplicate(output);
+            }
+            // check the outputs are all new - looking in the locked and unlocked UTXOs
+            if (
+                _utxos[output] == UTXOStatus.SPENT ||
+                _lockedUtxos[output] == UTXOStatus.SPENT
+            ) {
+                revert UTXOAlreadySpent(output);
+            } else if (
+                _utxos[output] == UTXOStatus.UNSPENT ||
+                _lockedUtxos[output] == UTXOStatus.UNSPENT
+            ) {
+                revert UTXOAlreadyOwned(output);
+            }
+        }
+    }
+
+    // Only needed for the nullifier based implementation
+    function validateRoot(uint256) public view virtual returns (bool) {
+        revert NotImplemented();
+    }
+
+    // Only needed for the nullifier based implementation
+    function getRoot() public view virtual returns (uint256) {
+        revert NotImplemented();
+    }
+
+    function processInputs(
+        uint256[] calldata inputs,
+        bool inputsLocked
+    ) public virtual onlyZeto {
+        mapping(uint256 => UTXOStatus) storage utxos = inputsLocked
+            ? _lockedUtxos
+            : _utxos;
+        // consume the input UTXOs
+        for (uint256 i = 0; i < inputs.length; ++i) {
+            if (inputs[i] != 0) {
+                utxos[inputs[i]] = UTXOStatus.SPENT;
+            }
+        }
+    }
+
+    function processOutputs(
+        uint256[] calldata outputs
+    ) public virtual onlyZeto {
+        for (uint256 i = 0; i < outputs.length; ++i) {
+            if (outputs[i] != 0) {
+                _utxos[outputs[i]] = UTXOStatus.UNSPENT;
+            }
+        }
+    }
+
+    function processLockedOutputs(
+        uint256[] calldata lockedOutputs
+    ) public virtual onlyZeto {
+        // register the locked UTXOs as UNSPENT in the locked-UTXO ledger.
+        for (uint256 i = 0; i < lockedOutputs.length; ++i) {
+            if (lockedOutputs[i] != 0) {
+                _lockedUtxos[lockedOutputs[i]] = UTXOStatus.UNSPENT;
+            }
+        }
+    }
+
+    function locked(uint256 utxo) public view returns (bool) {
+        return _lockedUtxos[utxo] == UTXOStatus.UNSPENT;
+    }
+
+    function spent(uint256 utxo) public view virtual returns (UTXOStatus) {
+        if (
+            _utxos[utxo] == UTXOStatus.SPENT ||
+            _lockedUtxos[utxo] == UTXOStatus.SPENT
+        ) {
+            return UTXOStatus.SPENT;
+        } else if (
+            _utxos[utxo] == UTXOStatus.UNSPENT ||
+            _lockedUtxos[utxo] == UTXOStatus.UNSPENT
+        ) {
+            return UTXOStatus.UNSPENT;
+        }
+        return UTXOStatus.UNKNOWN;
+    }
+}

package/contracts/lib/storage/nullifier.sol

@@ -0,0 +1,166 @@
+// Copyright © 2025 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+pragma solidity ^0.8.27;
+
+import {IZetoConstants, MAX_SMT_DEPTH} from "../interfaces/IZeto.sol";
+import {IZetoStorage} from "../interfaces/IZetoStorage.sol";
+import {Commonlib} from "../common/common.sol";
+import {Util} from "../common/util.sol";
+import {SmtLib} from "@iden3/contracts/contracts/lib/SmtLib.sol";
+import {IHasher} from "@iden3/contracts/contracts/interfaces/IHasher.sol";
+import {PoseidonUnit3L} from "@iden3/contracts/contracts/lib/Poseidon.sol";
+import {PoseidonHasher} from "@iden3/contracts/contracts/lib/hash/PoseidonHasher.sol";
+import {BaseStorage} from "./base.sol";
+
+contract NullifierStorage is BaseStorage {
+    // used for tracking regular (unlocked) UTXOs
+    // locked UTXOs are tracked in the base storage
+    SmtLib.Data internal _commitmentsTree;
+    using SmtLib for SmtLib.Data;
+
+    mapping(uint256 => bool) private _nullifiers;
+
+    error UTXORootNotFound(uint256 root);
+
+    constructor() {
+        _commitmentsTree.initialize(MAX_SMT_DEPTH);
+        IHasher hasher = new PoseidonHasher();
+        _commitmentsTree.setHasher(hasher);
+    }
+
+    function validateInputs(
+        uint256[] calldata inputs,
+        bool inputsLocked
+    ) public view override {
+        if (inputsLocked) {
+            // locked inputs are regular UTXOs (rather than nullifiers)
+            // and are validated in the base storage
+            super.validateInputs(inputs, inputsLocked);
+            return;
+        }
+
+        // sort the nullifiers to detect duplicates
+        uint256[] memory sortedInputs = Util.sortCommitments(inputs);
+
+        // Check the inputs are all unspent
+        for (uint256 i = 0; i < sortedInputs.length; ++i) {
+            if (sortedInputs[i] == 0) {
+                // skip the zero inputs
+                continue;
+            }
+            if (i > 0 && sortedInputs[i] == sortedInputs[i - 1]) {
+                revert UTXODuplicate(sortedInputs[i]);
+            }
+            if (_nullifiers[sortedInputs[i]] == true) {
+                revert UTXOAlreadySpent(sortedInputs[i]);
+            }
+        }
+    }
+
+    function validateOutputs(uint256[] calldata outputs) public view override {
+        // sort the outputs to detect duplicates
+        uint256[] memory sortedOutputs = Util.sortCommitments(outputs);
+
+        // Check the outputs are all new UTXOs
+        for (uint256 i = 0; i < sortedOutputs.length; ++i) {
+            if (sortedOutputs[i] == 0) {
+                // skip the zero outputs
+                continue;
+            }
+            if (i > 0 && sortedOutputs[i] == sortedOutputs[i - 1]) {
+                revert UTXODuplicate(sortedOutputs[i]);
+            }
+            // check the unlocked commitments tree
+            bool existsInTree = exists(sortedOutputs[i]);
+            if (existsInTree) {
+                revert UTXOAlreadyOwned(sortedOutputs[i]);
+            }
+        }
+    }
+
+    function validateRoot(uint256 root) public view override returns (bool) {
+        // Check if the root has existed before. It does not need to be the latest root.
+        // Our SMT is append-only, so if the root has existed before, and the merklet proof
+        // is valid, then the leaves still exist in the tree.
+        if (!_commitmentsTree.rootExists(root)) {
+            revert UTXORootNotFound(root);
+        }
+
+        return true;
+    }
+
+    function getRoot() public view override returns (uint256) {
+        return _commitmentsTree.getRoot();
+    }
+
+    function processInputs(
+        uint256[] calldata nullifiers,
+        bool inputsLocked
+    ) public override onlyZeto {
+        if (inputsLocked) {
+            // locked inputs are regular UTXOs (rather than nullifiers)
+            // and are processed in the base storage
+            super.processInputs(nullifiers, inputsLocked);
+            return;
+        }
+
+        for (uint256 i = 0; i < nullifiers.length; ++i) {
+            if (nullifiers[i] != 0) {
+                _nullifiers[nullifiers[i]] = true;
+            }
+        }
+    }
+
+    function processOutputs(
+        uint256[] calldata outputs
+    ) public override onlyZeto {
+        for (uint256 i = 0; i < outputs.length; ++i) {
+            if (outputs[i] != 0) {
+                _commitmentsTree.addLeaf(outputs[i], outputs[i]);
+            }
+        }
+    }
+
+    function spent(uint256 utxo) public view override returns (UTXOStatus) {
+        // by design, the contract does not know this
+        return UTXOStatus.UNKNOWN;
+    }
+
+    // check the existence of a UTXO in either the unlocked or locked commitments storage
+    function exists(uint256 utxo) internal view returns (bool) {
+        if (everExistedAsUnlocked(utxo)) {
+            return true;
+        }
+        return existsAsLocked(utxo);
+    }
+
+    // check the existence of a UTXO in the commitments tree. we take a shortcut
+    // by checking the list of nodes by their node hash, because the commitments
+    // tree is append-only, no updates or deletions are allowed. As a result, all
+    // nodes in the list are valid leaf nodes, aka there are no orphaned nodes.
+    function everExistedAsUnlocked(uint256 utxo) internal view returns (bool) {
+        uint256 nodeHash = Util.getLeafNodeHash(utxo, utxo);
+        SmtLib.Node memory node = _commitmentsTree.getNode(nodeHash);
+        return node.nodeType != SmtLib.NodeType.EMPTY;
+    }
+
+    function existsAsLocked(uint256 utxo) internal view returns (bool) {
+        if (super.locked(utxo)) {
+            return true;
+        }
+        return super.spent(utxo) != UTXOStatus.UNKNOWN;
+    }
+}