@lfdecentralizedtrust/zeto-contracts 0.2.2 → 0.5.1

package/contracts/lib/zeto_lockable_storage.sol

@@ -0,0 +1,43 @@
+// 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;
+
+/// @dev ERC-7201 (`erc7201:zeto.storage.ZetoLockable`): lock lifecycle state for
+///      {ZetoLockableLib} and embedding token contracts.
+library ZetoLockableStorage {
+    struct ZetoLockInfo {
+        address owner;
+        address spender;
+        bytes32 spendCommitment;
+        bytes32 cancelCommitment;
+        uint256[] lockedInputs;
+    }
+
+    struct Layout {
+        mapping(bytes32 => ZetoLockInfo) locks;
+        mapping(address => mapping(bytes32 => bool)) txIds;
+        mapping(uint256 => address) utxoDelegates;
+    }
+
+    bytes32 private constant STORAGE_LOCATION =
+        0x6f84b5947db308f6274c3bdf3450b8e85913b258c3b2e7abbddf0986236a4900;
+
+    function layout() internal pure returns (Layout storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
+}

package/contracts/lib/zeto_non_fungible.sol

@@ -0,0 +1,228 @@
+// 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 {ZetoLockable} from "./zeto_lockable.sol";
+import {Commonlib} from "./common/common.sol";
+import {IZetoInitializable} from "./interfaces/IZetoInitializable.sol";
+import {IZetoStorage} from "./interfaces/IZetoStorage.sol";
+
+/// @title A sample base implementation of a Zeto based non-fungible
+///        token contract.
+/// @author Kaleido, Inc.
+/// @dev The proof has the following statements:
+///        - The sender owns the private key whose public key is part of the pre-image of the input UTXOs commitments
+///          (aka the sender is authorized to spend the input UTXOs)
+///        - The input UTXOs and output UTXOs are valid in terms of obeying mass conservation rules
+///
+///      Inherits {ZetoLockable} (linked {ZetoLockableLib}) so the
+///      create/update/delegate/spend/cancel lock lifecycle is shared with the fungible siblings via
+///      a single implementation. The two ZK-circuit-shaped hooks
+///      ({_doLockTransition} and {_transferLocked}) are overridden here
+///      to match the NF circuit's fixed 1-in/1-out shape — there is no
+///      input/output padding and no batch verifier path.
+abstract contract ZetoNonFungible is ZetoLockable {
+    function __ZetoNonFungible_init(
+        string calldata name_,
+        string calldata symbol_,
+        address initialOwner,
+        IZetoInitializable.VerifiersInfo calldata verifiers,
+        IZetoStorage storage_
+    ) internal onlyInitializing {
+        __ZetoCommon_init(name_, symbol_, initialOwner, verifiers, storage_);
+    }
+
+    /**
+     * @dev Single-input/single-output transfer.
+     *
+     * @param input The UTXO to be spent by the transaction.
+     * @param output The new UTXO to generate, for future transactions
+     *      to spend.
+     * @param proof A zero knowledge proof that the submitter is
+     *      authorized to spend the input, and that the output is valid
+     *      in terms of obeying mass conservation rules.
+     * @param data Opaque data appended to the {UTXOTransfer} event for
+     *      off-chain consumers.
+     *
+     * Emits a {UTXOTransfer} event.
+     */
+    function transfer(
+        uint256 input,
+        uint256 output,
+        bytes calldata proof,
+        bytes calldata data
+    ) public {
+        uint256[] memory inputs = new uint256[](1);
+        inputs[0] = input;
+        uint256[] memory outputs = new uint256[](1);
+        outputs[0] = output;
+        uint256[] memory lockedOutputs;
+
+        validateTransactionProposal(
+            inputs,
+            outputs,
+            lockedOutputs,
+            proof,
+            false
+        );
+
+        (
+            uint256[] memory publicInputs,
+            Commonlib.Proof memory proofStruct
+        ) = constructPublicInputs(inputs, outputs, proof, false);
+        verifyProof(proofStruct, publicInputs, false, false);
+        processInputsAndOutputs(inputs, outputs, false);
+        emit UTXOTransfer(inputs, outputs, msg.sender, data);
+    }
+
+    // ------------------------------------------------------------------
+    // ZetoLockable hook overrides — non-fungible flavour.
+    //
+    // The NF circuits are fixed 1-in/1-out (or 1-in/1-locked-out for
+    // create-lock, 1-locked-in/1-out for spend/cancel), so there is no
+    // padding step and the batch-verifier path is never selected.
+    //
+    // Caller-supplied `args` are validated by ZetoLockable to be
+    // {ZetoCreateLockArgs}/{ZetoSpendLockArgs}; this hook trusts that
+    // shape and additionally enforces that the array sizes match the
+    // NF circuit (single input plus a single locked or unlocked
+    // output).
+    // ------------------------------------------------------------------
+
+    /// @dev Thrown when an NF lock-lifecycle call is invoked with an
+    ///      input/output array shape that does not match the fixed
+    ///      1-in/1-out circuit. Catching this at the contract layer
+    ///      gives a typed revert before the proof verifier would fail
+    ///      with a generic {InvalidProof}.
+    error InvalidNonFungibleArity(
+        uint256 inputs,
+        uint256 outputs,
+        uint256 lockedOutputs
+    );
+
+    function _doLockTransition(
+        ZetoCreateLockArgs calldata args
+    ) internal override {
+        // NF createLock: spend exactly one unlocked input and produce
+        // exactly one locked output. There is no regular (unlocked)
+        // output for NF lock creation — a single token cannot be split.
+        if (
+            args.inputs.length != 1 ||
+            args.outputs.length != 0 ||
+            args.lockedOutputs.length != 1
+        ) {
+            revert InvalidNonFungibleArity(
+                args.inputs.length,
+                args.outputs.length,
+                args.lockedOutputs.length
+            );
+        }
+
+        validateTransactionProposal(
+            args.inputs,
+            args.outputs,
+            args.lockedOutputs,
+            args.proof,
+            false
+        );
+
+        // The circuit treats the locked output as the "output"; combine
+        // for the public-inputs construction.
+        uint256[] memory allOutputs = new uint256[](1);
+        allOutputs[0] = args.lockedOutputs[0];
+
+        (
+            uint256[] memory publicInputs,
+            Commonlib.Proof memory proofStruct
+        ) = constructPublicInputs(args.inputs, allOutputs, args.proof, false);
+        verifyProof(proofStruct, publicInputs, false, false);
+
+        processInputsAndOutputs(args.inputs, args.outputs, false);
+        processLockedOutputs(args.lockedOutputs);
+    }
+
+    function _transferLocked(
+        bytes32 /* lockId */,
+        uint256[] calldata lockedInputs,
+        uint256[] calldata lockedOutputs,
+        uint256[] calldata outputs,
+        bytes calldata proof,
+        bytes calldata /* data */
+    ) internal override {
+        // NF spend/cancel: consume exactly one locked input and produce
+        // exactly one output. The output may be either a regular
+        // unlocked UTXO (the typical spend case) or a fresh locked UTXO
+        // (e.g. re-lock under a new spender via cancel-then-create).
+        if (
+            lockedInputs.length != 1 ||
+            lockedOutputs.length + outputs.length != 1
+        ) {
+            revert InvalidNonFungibleArity(
+                lockedInputs.length,
+                outputs.length,
+                lockedOutputs.length
+            );
+        }
+
+        validateTransactionProposal(
+            lockedInputs,
+            outputs,
+            lockedOutputs,
+            proof,
+            true
+        );
+
+        // The circuit treats locked and unlocked outputs identically, so
+        // both feed `constructPublicInputs` via the same single-element
+        // `allOutputs` array.
+        uint256[] memory allOutputs = new uint256[](1);
+        allOutputs[0] = lockedOutputs.length == 1
+            ? lockedOutputs[0]
+            : outputs[0];
+
+        (
+            uint256[] memory publicInputs,
+            Commonlib.Proof memory proofStruct
+        ) = constructPublicInputs(lockedInputs, allOutputs, proof, true);
+        verifyProof(proofStruct, publicInputs, false, true);
+
+        // Storage-side bookkeeping keeps the two ledgers strictly
+        // disjoint: the unlocked output (if any) goes through
+        // `processOutputs`, the locked output (if any) goes through
+        // `processLockedOutputs`. Mirroring `_doLockTransition` here
+        // avoids the locked-output being recorded as both unlocked and
+        // locked, which would let it be spent twice (once via the
+        // unlocked path, once via the lockable path).
+        processInputsAndOutputs(lockedInputs, outputs, true);
+        processLockedOutputs(lockedOutputs);
+    }
+}
+
+/// @dev ERC-7201 (`erc7201:zeto.storage.ZetoNonFungible`).
+library ZetoNonFungibleStorage {
+    struct Layout {
+        uint256 __reserved;
+    }
+
+    bytes32 private constant STORAGE_LOCATION =
+        0x70f918cef12f78aa293f0474363ccfa2a5e8bbdc86def1d4dd7d861fb8e6f600;
+
+    function layout() internal pure returns (Layout storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
+}

package/contracts/lib/zeto_non_fungible_base.sol

@@ -0,0 +1,61 @@
+// 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 {IZetoInitializable} from "./interfaces/IZetoInitializable.sol";
+import {ZetoNonFungible} from "./zeto_non_fungible.sol";
+import {IZetoStorage} from "./interfaces/IZetoStorage.sol";
+import {BaseStorage} from "./storage/base.sol";
+
+/// @title A sample base implementation of a Zeto based non-fungible token contract
+///        without using nullifiers. Each UTXO's spending status is explicitly tracked.
+/// @author Kaleido, Inc.
+/// @dev Wires {BaseStorage} into {ZetoNonFungible} for non-nullifier
+///      flavours of Zeto NF tokens. See {ZetoNonFungible} for the
+///      rationale behind the omitted lock lifecycle.
+abstract contract ZetoNonFungibleBase is ZetoNonFungible {
+    function __ZetoNonFungibleBase_init(
+        string calldata name_,
+        string calldata symbol_,
+        address initialOwner,
+        IZetoInitializable.VerifiersInfo calldata verifiers
+    ) internal onlyInitializing {
+        IZetoStorage storage_ = new BaseStorage();
+        __ZetoNonFungible_init(
+            name_,
+            symbol_,
+            initialOwner,
+            verifiers,
+            storage_
+        );
+    }
+}
+
+/// @dev ERC-7201 (`erc7201:zeto.storage.ZetoNonFungibleBase`).
+library ZetoNonFungibleBaseStorage {
+    struct Layout {
+        uint256 __reserved;
+    }
+
+    bytes32 private constant STORAGE_LOCATION =
+        0x3b5aad0db95258b4583c7272ce26730b4879c3622cde60d71e7f2a14bdd3ae00;
+
+    function layout() internal pure returns (Layout storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
+}

package/contracts/lib/zeto_non_fungible_nullifier.sol

@@ -0,0 +1,61 @@
+// 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 {IZetoInitializable} from "./interfaces/IZetoInitializable.sol";
+import {ZetoNonFungible} from "./zeto_non_fungible.sol";
+import {IZetoStorage} from "./interfaces/IZetoStorage.sol";
+import {NullifierStorage} from "./storage/nullifier.sol";
+
+/// @title A sample base implementation of a Zeto based non-fungible token
+///        contract with nullifier-based history masking.
+/// @author Kaleido, Inc.
+/// @dev Wires {NullifierStorage} into {ZetoNonFungible} for the nullifier
+///      flavours of Zeto NF tokens. See {ZetoNonFungible} for the
+///      rationale behind the omitted lock lifecycle.
+abstract contract ZetoNonFungibleNullifier is ZetoNonFungible {
+    function __ZetoNonFungibleNullifier_init(
+        string calldata name_,
+        string calldata symbol_,
+        address initialOwner,
+        IZetoInitializable.VerifiersInfo calldata verifiers
+    ) internal onlyInitializing {
+        IZetoStorage storage_ = new NullifierStorage();
+        __ZetoNonFungible_init(
+            name_,
+            symbol_,
+            initialOwner,
+            verifiers,
+            storage_
+        );
+    }
+}
+
+/// @dev ERC-7201 (`erc7201:zeto.storage.ZetoNonFungibleNullifier`).
+library ZetoNonFungibleNullifierStorage {
+    struct Layout {
+        uint256 __reserved;
+    }
+
+    bytes32 private constant STORAGE_LOCATION =
+        0x02976bb09873e8949dece591ee756708ea74c24901fa2000868b92802a9a5200;
+
+    function layout() internal pure returns (Layout storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
+}

package/contracts/test/escrow1.sol

@@ -15,16 +15,50 @@
 // limitations under the License.
 pragma solidity ^0.8.27;
 
-import {Commonlib} from "../lib/common.sol";
+import {Commonlib} from "../lib/common/common.sol";
 import {Zeto_Anon} from "../zeto_anon.sol";
-// import {console} from "hardhat/console.sol";
+import {ILockableCapability} from "../lib/interfaces/ILockableCapability.sol";
+import {IZetoLockableCapability} from "../lib/interfaces/IZetoLockableCapability.sol";
 
-/// @title A sample on-chain implementation of an escrow contract using Zeto tokens
+/// @title zkEscrow1
 /// @author Kaleido, Inc.
-/// @dev Implements escrow based payment flows with Zeto_Anon tokens
+/// @notice Sample on-chain escrow built on top of {Zeto_Anon} that brokers a
+///         payment between a payer and a payee using the new
+///         {ILockableCapability} lifecycle.
+///
+///         Lifecycle of a single escrowed payment:
+///           1. The payer calls {Zeto_Anon.createLock} to lock one or more
+///              UTXOs they own. The payer is initially both the lock owner
+///              and spender.
+///           2. The payer calls {Zeto_Anon.delegateLock} naming this escrow
+///              as the new spender. From this point on, only this escrow
+///              can spend or cancel the lock.
+///           3. The payer (or anyone) calls {initiatePayment} on this
+///              escrow with the lockId and the proposed unlocked output
+///              UTXOs. The escrow asserts it is the current spender of the
+///              lock before recording the payment.
+///           4. An authorised approver calls {approvePayment} with a ZK
+///              proof attesting that `(lockedInputs, outputs)` is a valid
+///              transition under {Zeto_Anon}'s circuit. The escrow stores
+///              the proof but does not yet consume the lock.
+///           5. Anyone (typically the payee) calls {completePayment}. The
+///              escrow forwards the stored proof to {Zeto_Anon.spendLock},
+///              which consumes the locked inputs and mints the unlocked
+///              outputs to their recipients in a single atomic step.
+///
+///         Notes on the new lock model:
+///           * The escrow does NOT choose the locked inputs at approval
+///             or completion time. They are pinned by `_locks[lockId]`
+///             inside {Zeto_Anon} at create-time, so "spending lock A
+///             always consumes lock A's UTXOs" is a hard contract
+///             invariant rather than a soft hash check on user-supplied
+///             arrays.
+///           * The escrow likewise does not choose `lockedOutputs` (it
+///             always sends them empty); the spend completes by minting
+///             plain unlocked UTXOs to the recipients.
 contract zkEscrow1 {
     enum PaymentStatus {
-        UNKNOWN, // this is the default value for the empty payment slots
+        UNKNOWN, // default value for empty payment slots
         INITIATED,
         APPROVED,
         COMPLETED,
@@ -32,10 +66,10 @@ contract zkEscrow1 {
     }
 
     struct Payment {
-        uint256[] lockedInputs;
+        bytes32 lockId;
         uint256[] outputs;
         PaymentStatus status;
-        Commonlib.Proof proof;
+        bytes proof;
     }
 
     mapping(uint256 => Payment) public payments;
@@ -45,7 +79,7 @@ contract zkEscrow1 {
 
     event PaymentInitiated(
         uint256 paymentId,
-        uint256[] lockedInputs,
+        bytes32 lockId,
         uint256[] outputs,
         bytes data
     );
@@ -56,35 +90,41 @@ contract zkEscrow1 {
         zeto = Zeto_Anon(zetoAddress);
     }
 
+    /// @notice Record a new escrowed payment against an existing lock.
+    /// @dev    The escrow MUST already be the current spender of the lock
+    ///         (the payer must have called {Zeto_Anon.delegateLock} naming
+    ///         this contract as the new spender before calling here).
+    ///         The locked inputs themselves are not stored on the
+    ///         payment; they are read fresh from {Zeto_Anon.getLockedInputs}
+    ///         at approval and completion time so the escrow always
+    ///         operates on the lock's storage-pinned content.
     function initiatePayment(
-        uint256[] memory lockedInputs,
+        bytes32 lockId,
         uint256[] memory outputs,
         bytes calldata data
     ) public {
-        for (uint256 i = 0; i < lockedInputs.length; i++) {
-            bool locked;
-            address delegate;
-            (locked, delegate) = zeto.locked(lockedInputs[i]);
-            require(locked, "Input not locked");
-            require(
-                delegate == address(this),
-                "Input not locked to this contract"
-            );
-        }
+        ILockableCapability.LockInfo memory info = zeto.getLock(lockId);
+        require(info.spender == address(this), "Escrow is not the spender");
         inflightCount++;
-        Commonlib.Proof memory emptyProof;
+        bytes memory emptyProof;
         payments[inflightCount] = Payment(
-            lockedInputs,
+            lockId,
             outputs,
             PaymentStatus.INITIATED,
             emptyProof
         );
-        emit PaymentInitiated(inflightCount, lockedInputs, outputs, data);
+        emit PaymentInitiated(inflightCount, lockId, outputs, data);
     }
 
+    /// @notice Verify the spend ZK proof for an initiated payment and
+    ///         move the payment into the APPROVED state.
+    /// @dev    The verification mirrors what {Zeto_Anon._transferLocked}
+    ///         would do later (same {checkAndPadCommitments} + locked-input
+    ///         verifier path), so a successful approval here guarantees
+    ///         that {completePayment} will not revert on proof grounds.
     function approvePayment(
         uint256 paymentId,
-        Commonlib.Proof memory proof,
+        bytes memory proof,
         bytes calldata data
     ) public {
         Payment storage payment = payments[paymentId];
@@ -92,12 +132,18 @@ contract zkEscrow1 {
             payment.status == PaymentStatus.INITIATED,
             "Payment not initiated"
         );
-        payment.lockedInputs = zeto.checkAndPadCommitments(
-            payment.lockedInputs
-        );
-        payment.outputs = zeto.checkAndPadCommitments(payment.outputs);
+        uint256[] memory lockedInputs = zeto.getLockedInputs(payment.lockId);
+        (
+            uint256[] memory paddedInputs,
+            uint256[] memory paddedOutputs
+        ) = zeto.checkAndPadCommitments(lockedInputs, payment.outputs);
         require(
-            zeto.verifyProof(payment.lockedInputs, payment.outputs, proof),
+            zeto.constructPublicSignalsAndVerifyProof(
+                paddedInputs,
+                paddedOutputs,
+                proof,
+                true
+            ),
             "Invalid proof"
         );
         payment.proof = proof;
@@ -105,18 +151,28 @@ contract zkEscrow1 {
         emit PaymentApproved(paymentId, data);
     }
 
+    /// @notice Forward the approved spend proof to {Zeto_Anon.spendLock}.
+    /// @dev    Encodes the {IZetoLockableCapability.ZetoSpendLockArgs}
+    ///         payload from `payment` and invokes `spendLock(lockId, ...)`
+    ///         as the lock's current spender. After this call returns the
+    ///         lock is consumed, the locked UTXOs are marked spent on the
+    ///         underlying Zeto storage, and the unlocked outputs are
+    ///         emitted to their recipients.
     function completePayment(uint256 paymentId, bytes calldata data) public {
         Payment storage payment = payments[paymentId];
         require(
             payment.status == PaymentStatus.APPROVED,
             "Payment not approved"
         );
-        zeto.transferLocked(
-            payment.lockedInputs,
-            payment.outputs,
-            payment.proof,
-            "0x"
-        );
+        IZetoLockableCapability.ZetoSpendLockArgs
+            memory spendArgs = IZetoLockableCapability.ZetoSpendLockArgs({
+                txId: bytes32(paymentId),
+                lockedOutputs: new uint256[](0),
+                outputs: payment.outputs,
+                proof: payment.proof,
+                data: ""
+            });
+        zeto.spendLock(payment.lockId, abi.encode(spendArgs), "");
         payment.status = PaymentStatus.COMPLETED;
         emit PaymentCompleted(paymentId, data);
     }