@lfdecentralizedtrust/zeto-contracts 0.2.1 → 0.5.0

package/contracts/lib/zeto_fungible_burn.sol

@@ -15,72 +15,102 @@
 // limitations under the License.
 pragma solidity ^0.8.27;
 
-import {Groth16Verifier_Burn} from "../verifiers/verifier_burn.sol";
-import {Groth16Verifier_BurnBatch} from "../verifiers/verifier_burn_batch.sol";
-import {ZetoBase} from "./zeto_base.sol";
-import {Commonlib} from "./common.sol";
-
-uint256 constant BURN_INPUT_SIZE = 3;
-uint256 constant BATCH_BURN_INPUT_SIZE = 11;
+import {IGroth16Verifier} from "./interfaces/IZetoVerifier.sol";
+import {ZetoFungibleBase} from "./zeto_fungible_base.sol";
+import {Commonlib} from "./common/common.sol";
 
 /// @title A feature implementation of a Zeto fungible token burn contract
 /// @author Kaleido, Inc.
-/// @dev Can be added to a Zeto fungible token contract to allow for burning of tokens.
-abstract contract ZetoFungibleBurnable is ZetoBase {
-    Groth16Verifier_Burn internal _burnVerifier;
-    Groth16Verifier_BurnBatch internal _batchBurnVerifier;
-
+/// @dev Mixed-in alongside {ZetoFungibleBase} (the non-nullifier sibling of
+///      {ZetoFungibleNullifier}) to add a {burn} entry point that destroys a
+///      set of input UTXOs and produces a single output UTXO holding the
+///      remainder. The burn proof attests that the inputs sum to
+///      `output + burn_amount` while preserving owner-side range and
+///      ownership invariants.
+///
+///      The locking lifecycle is unaffected by burning: locked UTXOs cannot
+///      be supplied as inputs because {validateInputs} (called from {_burn})
+///      rejects locked entries via the underlying {BaseStorage} ledger.
+abstract contract ZetoFungibleBurnable is ZetoFungibleBase {
+    /// @dev Internal-only so it can only be called from a derived
+    ///      contract's own `initializer`-guarded entrypoint.
     function __ZetoFungibleBurnable_init(
-        Groth16Verifier_Burn burnVerifier,
-        Groth16Verifier_BurnBatch batchBurnVerifier
-    ) public onlyInitializing {
-        _burnVerifier = burnVerifier;
-        _batchBurnVerifier = batchBurnVerifier;
+        IGroth16Verifier burnVerifier,
+        IGroth16Verifier batchBurnVerifier
+    ) internal onlyInitializing {
+        ZetoFungibleBurnableStorage.Layout storage $ = ZetoFungibleBurnableStorage
+            .layout();
+        $.burnVerifier = burnVerifier;
+        $.batchBurnVerifier = batchBurnVerifier;
     }
 
+    /**
+     * @dev Burn a set of inputs, leaving a single output UTXO that holds the
+     *      remainder.
+     * @param inputs The input UTXOs to burn.
+     * @param output The single output UTXO holding the remainder.
+     * @param proof The Groth16 proof attesting to value conservation and
+     *              owner-side range/ownership invariants.
+     * @param data Opaque data appended to the {UTXOBurn} event for off-chain
+     *             consumers (e.g. correlation ids).
+     *
+     * Emits a {UTXOBurn} event.
+     */
     function burn(
-        uint256[] memory inputs,
+        uint256[] calldata inputs,
         uint256 output,
         Commonlib.Proof calldata proof,
         bytes calldata data
     ) public virtual {
-        // Check the proof
-        if (inputs.length > 2) {
-            // construct the public inputs for verifier
-            uint256[BATCH_BURN_INPUT_SIZE] memory fixedSizeInputs;
-            for (uint256 i = 0; i < inputs.length; i++) {
-                fixedSizeInputs[i] = inputs[i];
-            }
-            fixedSizeInputs[BATCH_BURN_INPUT_SIZE - 1] = output;
-            // Check the proof
-            require(
-                _batchBurnVerifier.verifyProof(
-                    proof.pA,
-                    proof.pB,
-                    proof.pC,
-                    fixedSizeInputs
-                ),
-                "Invalid proof"
-            );
-        } else {
-            // construct the public inputs for verifier
-            uint256[BURN_INPUT_SIZE] memory fixedSizeInputs;
-            for (uint256 i = 0; i < inputs.length; i++) {
-                fixedSizeInputs[i] = inputs[i];
-            }
-            fixedSizeInputs[BURN_INPUT_SIZE - 1] = output;
-            // Check the proof
-            require(
-                _burnVerifier.verifyProof(
-                    proof.pA,
-                    proof.pB,
-                    proof.pC,
-                    fixedSizeInputs
-                ),
-                "Invalid proof"
-            );
+        uint256[] memory publicInputs = new uint256[](inputs.length + 1);
+        for (uint256 i = 0; i < inputs.length; i++) {
+            publicInputs[i] = inputs[i];
+        }
+        publicInputs[inputs.length] = output;
+
+        ZetoFungibleBurnableStorage.Layout storage $ = ZetoFungibleBurnableStorage
+            .layout();
+        IGroth16Verifier verifier = (inputs.length > 2)
+            ? $.batchBurnVerifier
+            : $.burnVerifier;
+        if (!verifier.verify(proof.pA, proof.pB, proof.pC, publicInputs)) {
+            revert InvalidProof();
         }
 
         _burn(inputs, output, data);
     }
+
+    /// @dev Validate inputs/outputs, then transition state and emit the
+    ///      {UTXOBurn} event. Marked virtual so concrete tokens can wrap
+    ///      with additional bookkeeping if needed.
+    function _burn(
+        uint256[] memory inputs,
+        uint256 output,
+        bytes calldata data
+    ) internal virtual {
+        validateInputs(inputs, false);
+        uint256[] memory outputStates = new uint256[](1);
+        outputStates[0] = output;
+        validateOutputs(outputStates);
+        processInputs(inputs, false);
+        processOutputs(outputStates);
+        emit UTXOBurn(inputs, output, msg.sender, data);
+    }
+}
+
+/// @dev ERC-7201 (`erc7201:zeto.storage.ZetoFungibleBurnable`).
+library ZetoFungibleBurnableStorage {
+    struct Layout {
+        IGroth16Verifier burnVerifier;
+        IGroth16Verifier batchBurnVerifier;
+    }
+
+    bytes32 private constant STORAGE_LOCATION =
+        0x99d1a11894f655177598fbad145350332923053ddb779beb1721e5203b8acf00;
+
+    function layout() internal pure returns (Layout storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
 }

package/contracts/lib/zeto_fungible_burn_nullifier.sol

@@ -15,30 +15,49 @@
 // limitations under the License.
 pragma solidity ^0.8.27;
 
-import {Groth16Verifier_BurnNullifier} from "../verifiers/verifier_burn_nullifier.sol";
-import {Groth16Verifier_BurnNullifierBatch} from "../verifiers/verifier_burn_nullifier_batch.sol";
-import {ZetoNullifier} from "./zeto_nullifier.sol";
-import {Commonlib} from "./common.sol";
+import {IGroth16Verifier} from "./interfaces/IZetoVerifier.sol";
+import {ZetoFungibleNullifier} from "./zeto_fungible_nullifier.sol";
+import {Commonlib} from "./common/common.sol";
 
-uint256 constant BURN_INPUT_SIZE = 6;
-uint256 constant BATCH_BURN_INPUT_SIZE = 22;
-
-/// @title A feature implementation of a Zeto fungible token burn contract
+/// @title A feature implementation of a Zeto fungible token burn contract for nullifier-based variants
 /// @author Kaleido, Inc.
-/// @dev Can be added to a Zeto fungible token contract to allow for burning of tokens.
-abstract contract ZetoFungibleBurnableWithNullifiers is ZetoNullifier {
-    Groth16Verifier_BurnNullifier internal _burnVerifier;
-    Groth16Verifier_BurnNullifierBatch internal _batchBurnVerifier;
-
-    function __ZetoFungibleBurnableWithNullifiers_init(
-        Groth16Verifier_BurnNullifier burnVerifier,
-        Groth16Verifier_BurnNullifierBatch batchBurnVerifier
-    ) public onlyInitializing {
-        _burnVerifier = burnVerifier;
-        _batchBurnVerifier = batchBurnVerifier;
+/// @dev Mixed-in alongside {ZetoFungibleNullifier} to add a {burn} entry
+///      point that destroys a set of input nullifiers and produces a single
+///      output UTXO holding the remainder. The burn proof attests that the
+///      pre-image UTXOs sum to `output + burn_amount` while preserving
+///      owner-side range and ownership invariants and proving membership
+///      against the historical SMT `root`.
+///
+///      This is the nullifier-flow companion to {ZetoFungibleBurnable}.
+///      Unlike that contract:
+///        - inputs are nullifiers, not UTXOs;
+///        - the SMT `root` is a separate `burn` argument (not encoded in the
+///          proof bytes), so `burn` validates it explicitly;
+///        - the locking lifecycle is unaffected by burning because
+///          {NullifierStorage.validateInputs} (called from {_burn}) only
+///          accepts unspent nullifiers, and locked UTXOs live in a disjoint
+///          part of the ledger.
+abstract contract ZetoFungibleBurnableNullifier is ZetoFungibleNullifier {
+    /// @dev Internal-only so it can only be called from a derived
+    ///      contract's own `initializer`-guarded entrypoint.
+    function __ZetoFungibleBurnableNullifier_init(
+        IGroth16Verifier burnVerifier,
+        IGroth16Verifier batchBurnVerifier
+    ) internal onlyInitializing {
+        ZetoFungibleBurnableNullifierStorage.Layout
+            storage $ = ZetoFungibleBurnableNullifierStorage.layout();
+        $.burnVerifier = burnVerifier;
+        $.batchBurnVerifier = batchBurnVerifier;
     }
 
-    function constructPublicInputs(
+    /**
+     * @dev Construct the burn-circuit public-inputs vector. Layout:
+     *        [nullifiers..., root, enabled-flags..., output]
+     *      where `enabled-flags[i]` is 1 if `nullifiers[i] != 0` else 0,
+     *      mirroring the convention used in
+     *      {Zeto_AnonNullifier.constructPublicInputs}.
+     */
+    function constructBurnPublicInputs(
         uint256[] memory nullifiers,
         uint256 output,
         uint256 root
@@ -46,78 +65,102 @@ abstract contract ZetoFungibleBurnableWithNullifiers is ZetoNullifier {
         publicInputs = new uint256[](nullifiers.length * 2 + 2);
         uint256 piIndex = 0;
 
-        // copy input commitments
         for (uint256 i = 0; i < nullifiers.length; i++) {
             publicInputs[piIndex++] = nullifiers[i];
         }
-
-        // copy root
         publicInputs[piIndex++] = root;
-
-        // populate enables
         for (uint256 i = 0; i < nullifiers.length; i++) {
             publicInputs[piIndex++] = (nullifiers[i] == 0) ? 0 : 1;
         }
-
         publicInputs[piIndex] = output;
 
         return publicInputs;
     }
 
+    /**
+     * @dev Burn a set of nullifier-pre-image UTXOs, leaving a single output
+     *      UTXO that holds the remainder.
+     * @param nullifiers The nullifiers of the input UTXOs being burned.
+     * @param output The single output UTXO holding the remainder.
+     * @param root The historical SMT root the proof is committed against.
+     *             Validated against the on-chain root history before state
+     *             transitions are applied.
+     * @param proof The Groth16 proof attesting to value conservation,
+     *              owner-side range/ownership invariants, and membership of
+     *              the input UTXOs in the SMT identified by `root`.
+     * @param data Opaque data appended to the {UTXOBurn} event for off-chain
+     *             consumers (e.g. correlation ids).
+     *
+     * Emits a {UTXOBurn} event.
+     */
     function burn(
-        uint256[] memory nullifiers,
+        uint256[] calldata nullifiers,
         uint256 output,
         uint256 root,
         Commonlib.Proof calldata proof,
         bytes calldata data
     ) public virtual {
-        // Check the proof
-        if (nullifiers.length > 2) {
-            // construct the public inputs for verifier
-            uint256[] memory publicInputs = constructPublicInputs(
-                nullifiers,
-                output,
-                root
-            );
-            // construct the public inputs for verifier
-            uint256[BATCH_BURN_INPUT_SIZE] memory fixedSizeInputs;
-            for (uint256 i = 0; i < fixedSizeInputs.length; i++) {
-                fixedSizeInputs[i] = publicInputs[i];
-            }
-            // Check the proof
-            require(
-                _batchBurnVerifier.verifyProof(
-                    proof.pA,
-                    proof.pB,
-                    proof.pC,
-                    fixedSizeInputs
-                ),
-                "Invalid proof"
-            );
-        } else {
-            // construct the public inputs for verifier
-            uint256[] memory publicInputs = constructPublicInputs(
-                nullifiers,
-                output,
-                root
-            );
-            // construct the public inputs for verifier
-            uint256[BURN_INPUT_SIZE] memory fixedSizeInputs;
-            for (uint256 i = 0; i < fixedSizeInputs.length; i++) {
-                fixedSizeInputs[i] = publicInputs[i];
-            }
-            // Check the proof
-            require(
-                _burnVerifier.verifyProof(
-                    proof.pA,
-                    proof.pB,
-                    proof.pC,
-                    fixedSizeInputs
-                ),
-                "Invalid proof"
-            );
+        uint256[] memory publicInputs = constructBurnPublicInputs(
+            nullifiers,
+            output,
+            root
+        );
+
+        ZetoFungibleBurnableNullifierStorage.Layout
+            storage $ = ZetoFungibleBurnableNullifierStorage.layout();
+        IGroth16Verifier verifier = (nullifiers.length > 2)
+            ? $.batchBurnVerifier
+            : $.burnVerifier;
+        if (!verifier.verify(proof.pA, proof.pB, proof.pC, publicInputs)) {
+            revert InvalidProof();
         }
 
         _burn(nullifiers, output, root, data);
     }
+
+    /**
+     * @dev Validate inputs/outputs/root, then transition state and emit the
+     *      {UTXOBurn} event. Marked virtual so concrete tokens can wrap
+     *      with additional bookkeeping if needed.
+     *
+     *      Unlike the historical implementation on `main`, this consumes
+     *      the nullifiers via {processInputs} and inserts the output UTXO
+     *      into the SMT via {processOutputs}; without those calls the
+     *      burned UTXOs would remain spendable and the remainder UTXO
+     *      would not be a member of the tree.
+     */
+    function _burn(
+        uint256[] memory nullifiers,
+        uint256 output,
+        uint256 root,
+        bytes calldata data
+    ) internal virtual {
+        validateInputs(nullifiers, false);
+        uint256[] memory outputStates = new uint256[](1);
+        outputStates[0] = output;
+        validateOutputs(outputStates);
+        validateRoot(root);
+
+        processInputs(nullifiers, false);
+        processOutputs(outputStates);
+
+        emit UTXOBurn(nullifiers, output, msg.sender, data);
+    }
+}
+
+/// @dev ERC-7201 (`erc7201:zeto.storage.ZetoFungibleBurnableNullifier`).
+library ZetoFungibleBurnableNullifierStorage {
+    struct Layout {
+        IGroth16Verifier burnVerifier;
+        IGroth16Verifier batchBurnVerifier;
+    }
+
+    bytes32 private constant STORAGE_LOCATION =
+        0x3ec1ff2ff5e1c50bcb38c7183cc1e67f5f6626ff8f32ea7dbc84147e4b393500;
+
+    function layout() internal pure returns (Layout storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
 }

package/contracts/lib/zeto_fungible_nullifier.sol

@@ -0,0 +1,167 @@
+// Copyright © 2024 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 {Commonlib} from "./common/common.sol";
+import {IZeto, MAX_SMT_DEPTH} from "./interfaces/IZeto.sol";
+import {IZetoInitializable} from "./interfaces/IZetoInitializable.sol";
+import {ZetoFungible} from "./zeto_fungible.sol";
+import {IZetoStorage} from "./interfaces/IZetoStorage.sol";
+import {NullifierStorage} from "./storage/nullifier.sol";
+
+/// @title A sample base implementation of a Zeto based token contract with nullifiers
+/// @author Kaleido, Inc.
+/// @dev Implements common functionalities of Zeto based tokens using nullifiers
+abstract contract ZetoFungibleNullifier is ZetoFungible {
+    function __ZetoFungibleNullifier_init(
+        string calldata name_,
+        string calldata symbol_,
+        address initialOwner,
+        IZetoInitializable.VerifiersInfo calldata verifiers
+    ) internal onlyInitializing {
+        IZetoStorage storage_ = new NullifierStorage();
+        __ZetoFungible_init(name_, symbol_, initialOwner, verifiers, storage_);
+    }
+
+    function constructPublicInputsForWithdraw(
+        uint256 amount,
+        uint256[] memory nullifiers,
+        uint256 output,
+        bytes memory proof
+    ) internal override returns (uint256[] memory, Commonlib.Proof memory) {
+        // Decode the proof to extract root and proof structure. Root
+        // validation is performed here (rather than in a separate
+        // pre-decode hop in {validateTransactionProposal}, see L-4) so the
+        // proof bytes are decoded exactly once per withdraw call.
+        (uint256 root, Commonlib.Proof memory proofStruct) = abi.decode(
+            proof,
+            (uint256, Commonlib.Proof)
+        );
+        validateRoot(root);
+
+        // Calculate the total size needed for public inputs
+        uint256 size = _calculateWithdrawPublicInputsSize(nullifiers);
+
+        // Create and populate the public inputs array
+        uint256[] memory publicInputs = new uint256[](size);
+        _fillWithdrawPublicInputs(
+            publicInputs,
+            amount,
+            nullifiers,
+            root,
+            output
+        );
+
+        return (publicInputs, proofStruct);
+    }
+
+    function _calculateWithdrawPublicInputsSize(
+        uint256[] memory nullifiers
+    ) internal pure returns (uint256 size) {
+        size = (nullifiers.length * 2) + 3; // nullifiers, enabled flags, amount, root, output
+    }
+
+    function _fillWithdrawPublicInputs(
+        uint256[] memory publicInputs,
+        uint256 amount,
+        uint256[] memory nullifiers,
+        uint256 root,
+        uint256 output
+    ) internal pure {
+        uint256 piIndex = 0;
+
+        // Copy withdrawal amount
+        piIndex = _fillWithdrawAmount(publicInputs, amount, piIndex);
+
+        // Copy nullifiers
+        piIndex = _fillWithdrawNullifiers(publicInputs, nullifiers, piIndex);
+
+        // Copy root
+        piIndex = _fillWithdrawRoot(publicInputs, root, piIndex);
+
+        // Populate enabled flags
+        piIndex = _fillWithdrawEnabledFlags(publicInputs, nullifiers, piIndex);
+
+        // Copy output commitment
+        _fillWithdrawOutput(publicInputs, output, piIndex);
+    }
+
+    function _fillWithdrawAmount(
+        uint256[] memory publicInputs,
+        uint256 amount,
+        uint256 startIndex
+    ) internal pure returns (uint256 nextIndex) {
+        publicInputs[startIndex] = amount;
+        return startIndex + 1;
+    }
+
+    function _fillWithdrawNullifiers(
+        uint256[] memory publicInputs,
+        uint256[] memory nullifiers,
+        uint256 startIndex
+    ) internal pure returns (uint256 nextIndex) {
+        uint256 piIndex = startIndex;
+        for (uint256 i = 0; i < nullifiers.length; i++) {
+            publicInputs[piIndex++] = nullifiers[i];
+        }
+        return piIndex;
+    }
+
+    function _fillWithdrawRoot(
+        uint256[] memory publicInputs,
+        uint256 root,
+        uint256 startIndex
+    ) internal pure returns (uint256 nextIndex) {
+        publicInputs[startIndex] = root;
+        return startIndex + 1;
+    }
+
+    function _fillWithdrawEnabledFlags(
+        uint256[] memory publicInputs,
+        uint256[] memory nullifiers,
+        uint256 startIndex
+    ) internal pure returns (uint256 nextIndex) {
+        uint256 piIndex = startIndex;
+        for (uint256 i = 0; i < nullifiers.length; i++) {
+            publicInputs[piIndex++] = (nullifiers[i] == 0) ? 0 : 1;
+        }
+        return piIndex;
+    }
+
+    function _fillWithdrawOutput(
+        uint256[] memory publicInputs,
+        uint256 output,
+        uint256 startIndex
+    ) internal pure {
+        publicInputs[startIndex] = output;
+    }
+}
+
+/// @dev ERC-7201 (`erc7201:zeto.storage.ZetoFungibleNullifier`).
+library ZetoFungibleNullifierStorage {
+    struct Layout {
+        uint256 __reserved;
+    }
+
+    bytes32 private constant STORAGE_LOCATION =
+        0xa9ddb64cb7b603a6a83651e5155a95c052516a16afcb7569681d49e92a59ab00;
+
+    function layout() internal pure returns (Layout storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
+}