@lfdecentralizedtrust/zeto-contracts 0.5.0 → 0.5.1

package/contracts/lib/zeto_lockable.sol

@@ -16,128 +16,37 @@
 pragma solidity ^0.8.27;
 
 import {IZetoLockableCapability} from "./interfaces/IZetoLockableCapability.sol";
-import {Commonlib} from "./common/common.sol";
-import {ZetoCommon, ZetoCommonStorage} from "./zeto_common.sol";
+import {IZetoLockHooks} from "./interfaces/IZetoLockHooks.sol";
+import {ILockableCapability} from "./interfaces/ILockableCapability.sol";
+import {ZetoCommon} from "./zeto_common.sol";
+import {ZetoLockableLib} from "./zeto_lockable_lib.sol";
 
 /// @title ZetoLockable
 /// @author Kaleido, Inc.
-/// @dev Reusable mixin that wires the {IZetoLockableCapability} lock
-///      lifecycle on top of {ZetoCommon}, agnostic of whether the
-///      embedding token is fungible or non-fungible.
-///
-///      The mixin owns:
-///        * The lock-state mappings ({_locks}, {_txIds},
-///          {_utxoDelegates}).
-///        * The full create / update / delegate / spend / cancel
-///          lifecycle entry points.
-///        * The hash-domain separated unlock-commitment helpers.
-///        * The {locked(uint256)} override that joins the storage
-///          layer's "is locked" bit with the per-UTXO spender
-///          projection.
-///
-///      Descendants are responsible for the two ZK-circuit-specific
-///      hooks {_doLockTransition} and {_transferLocked}, which
-///      serialize a Zeto state transition into the public-inputs
-///      shape expected by their concrete circuit family. Fungible
-///      tokens pad inputs/outputs to the next supported batch size
-///      via {ZetoCommon.checkAndPadCommitments}; non-fungible tokens
-///      operate on fixed 1-in/1-out arrays. Keeping the hooks
-///      virtual in this mixin lets both flavours share every other
-///      moving piece of the lock lifecycle.
-abstract contract ZetoLockable is ZetoCommon, IZetoLockableCapability {
-    /// @dev Lock state and replay protection live in {ZetoLockableStorage}
-    ///      (ERC-7201 namespace `zeto.storage.ZetoLockable`).
-
-    modifier lockActive(bytes32 lockId) {
-        if (ZetoLockableStorage.layout().locks[lockId].owner == address(0)) {
-            revert LockNotActive(lockId);
-        }
-        _;
-    }
-
-    modifier onlyLockOwner(bytes32 lockId) {
-        address owner = ZetoLockableStorage.layout().locks[lockId].owner;
-        if (owner != msg.sender) {
-            revert LockUnauthorized(lockId, owner, msg.sender);
+/// @dev Thin embedding layer for {IZetoLockableCapability}. Shared lock
+///      lifecycle logic lives in the linked external {ZetoLockableLib};
+///      this contract forwards interface entry points to the library and
+///      exposes {IZetoLockHooks} callbacks for circuit-specific work in
+///      descendants ({ZetoFungible}, {ZetoNonFungible}).
+abstract contract ZetoLockable is
+    ZetoCommon,
+    IZetoLockableCapability,
+    IZetoLockHooks
+{
+    modifier onlySelf() {
+        if (msg.sender != address(this)) {
+            revert NotSelf(msg.sender);
         }
         _;
     }
 
-    modifier onlyLockSpender(bytes32 lockId) {
-        address spender = ZetoLockableStorage.layout().locks[lockId].spender;
-        if (spender != msg.sender) {
-            revert LockUnauthorized(lockId, spender, msg.sender);
-        }
-        _;
-    }
-
-    function _useTxId(bytes32 txId) internal {
-        if (ZetoLockableStorage.layout().txIds[msg.sender][txId]) {
-            revert DuplicateTransaction(txId);
-        }
-        ZetoLockableStorage.layout().txIds[msg.sender][txId] = true;
-    }
-
-    /// @dev Project the lock-level spender onto each UTXO in `utxos`.
-    ///      Skips zero-padding entries so it is safe to pass calldata
-    ///      arrays straight from the lock payloads.
-    function _setLockDelegates(
-        uint256[] memory utxos,
-        address spender
-    ) internal {
-        for (uint256 i = 0; i < utxos.length; ++i) {
-            if (utxos[i] != 0) {
-                ZetoLockableStorage.layout().utxoDelegates[utxos[i]] = spender;
-            }
-        }
-    }
-
-    /// @dev Wipe the per-UTXO spender projection for each UTXO in
-    ///      `utxos`. Called when a lock's inputs are consumed (spend or
-    ///      cancel) so that the public {locked} view returns
-    ///      `(false, address(0))` for them immediately, even if some
-    ///      future code path were to resurrect the locked-state entry.
-    function _clearLockDelegates(uint256[] memory utxos) internal {
-        for (uint256 i = 0; i < utxos.length; ++i) {
-            if (utxos[i] != 0) {
-                delete ZetoLockableStorage.layout().utxoDelegates[utxos[i]];
-            }
-        }
-    }
-
-    // ------------------------------------------------------------------
-    // ILockableCapability lifecycle
-    // ------------------------------------------------------------------
-
     /// @inheritdoc IZetoLockableCapability
     function computeLockId(
         bytes calldata createArgs
     ) external view override returns (bytes32) {
-        ZetoCreateLockArgs memory args = abi.decode(
-            createArgs,
-            (ZetoCreateLockArgs)
-        );
-        return _computeLockId(args.txId);
-    }
-
-    function _computeLockId(bytes32 txId) internal view returns (bytes32) {
-        return keccak256(abi.encode(address(this), msg.sender, txId));
+        return ZetoLockableLib.computeLockId(createArgs);
     }
 
-    /// @dev Domain-separation tag for spend-intent commitments.
-    ///      Included in {_buildUnlockHash} so that a payload hashing to
-    ///      a lock's {ZetoLockInfo.spendCommitment} cannot also hash to
-    ///      its {ZetoLockInfo.cancelCommitment}, preventing a spender
-    ///      from transposing a spend payload into {cancelLock} (or vice
-    ///      versa) when one of the commitments is non-zero.
-    bytes32 private constant _SPEND_HASH_DOMAIN =
-        keccak256("Zeto.spendCommitment.v1");
-
-    /// @dev Domain-separation tag for cancel-intent commitments. See
-    ///      {_SPEND_HASH_DOMAIN} for the rationale.
-    bytes32 private constant _CANCEL_HASH_DOMAIN =
-        keccak256("Zeto.cancelCommitment.v1");
-
     /// @inheritdoc IZetoLockableCapability
     function computeSpendHash(
         uint256[] calldata lockedInputs,
@@ -146,12 +55,11 @@ abstract contract ZetoLockable is ZetoCommon, IZetoLockableCapability {
         bytes calldata data
     ) external pure override returns (bytes32) {
         return
-            _buildUnlockHash(
+            ZetoLockableLib.computeSpendHash(
                 lockedInputs,
                 lockedOutputs,
                 outputs,
-                data,
-                _SPEND_HASH_DOMAIN
+                data
             );
     }
 
@@ -163,451 +71,149 @@ abstract contract ZetoLockable is ZetoCommon, IZetoLockableCapability {
         bytes calldata data
     ) external pure override returns (bytes32) {
         return
-            _buildUnlockHash(
+            ZetoLockableLib.computeCancelHash(
                 lockedInputs,
                 lockedOutputs,
                 outputs,
-                data,
-                _CANCEL_HASH_DOMAIN
+                data
             );
     }
 
-    /**
-     * @dev Create a new lock by spending unlocked inputs and producing
-     *      the locked content. See {ILockableCapability.createLock} for
-     *      the generic semantics; the Zeto-specific payload is
-     *      {ZetoCreateLockArgs}.
-     *
-     * Emits {LockCreated} (generic) and {ZetoLockCreated}.
-     */
+    /// @inheritdoc ILockableCapability
     function createLock(
         bytes calldata createArgs,
         bytes32 spendCommitment,
         bytes32 cancelCommitment,
         bytes calldata data
     ) external override returns (bytes32) {
-        ZetoCreateLockArgs memory args = abi.decode(
-            createArgs,
-            (ZetoCreateLockArgs)
-        );
-
-        bytes32 lockId = _computeLockId(args.txId);
-        if (ZetoLockableStorage.layout().locks[lockId].owner != address(0)) {
-            revert DuplicateLock(lockId);
-        }
-        _useTxId(args.txId);
-
-        _doLockTransition(args);
-
-        ZetoLockableStorage.ZetoLockInfo storage lock = ZetoLockableStorage
-            .layout()
-            .locks[lockId];
-        lock.owner = msg.sender;
-        lock.spender = msg.sender;
-        lock.spendCommitment = spendCommitment;
-        lock.cancelCommitment = cancelCommitment;
-        lock.lockedInputs = args.lockedOutputs;
-
-        emit LockCreated(
-            lockId,
-            msg.sender,
-            msg.sender,
-            spendCommitment,
-            cancelCommitment,
-            data
-        );
-        emit ZetoLockCreated(
-            args.txId,
-            lockId,
-            msg.sender,
-            args.inputs,
-            args.outputs,
-            args.lockedOutputs,
-            args.proof,
-            data
-        );
-
-        return lockId;
+        return
+            ZetoLockableLib.createLock(
+                createArgs,
+                spendCommitment,
+                cancelCommitment,
+                data
+            );
     }
 
-    /**
-     * @dev Update the spend/cancel commitments on an active,
-     *      owner-controlled lock. Mirrors the previous prepareUnlock
-     *      flow but with full-update semantics: both commitments are
-     *      replaced atomically.
-     *
-     * Emits {LockUpdated} and {ZetoLockUpdated}.
-     */
+    /// @inheritdoc ILockableCapability
     function updateLock(
         bytes32 lockId,
         bytes calldata updateArgs,
         bytes32 spendCommitment,
         bytes32 cancelCommitment,
         bytes calldata data
-    ) external override lockActive(lockId) onlyLockOwner(lockId) {
-        ZetoLockableStorage.ZetoLockInfo storage lock = ZetoLockableStorage
-            .layout()
-            .locks[lockId];
-        if (lock.spender != lock.owner) {
-            revert LockImmutable(lockId);
-        }
-
-        ZetoUpdateLockArgs memory args = abi.decode(
-            updateArgs,
-            (ZetoUpdateLockArgs)
-        );
-        _useTxId(args.txId);
-
-        lock.spendCommitment = spendCommitment;
-        lock.cancelCommitment = cancelCommitment;
-
-        emit LockUpdated(
+    ) external override {
+        ZetoLockableLib.updateLock(
             lockId,
-            msg.sender,
+            updateArgs,
             spendCommitment,
             cancelCommitment,
             data
         );
-        emit ZetoLockUpdated(args.txId, lockId, msg.sender, data);
     }
 
-    /**
-     * @dev Delegate spending authority for the lock. The per-UTXO
-     *      spender projection used by the public {locked} view is also
-     *      moved here so that subsequent observers see the new spender
-     *      for every locked input belonging to this lock.
-     *
-     * Emits {LockDelegated} and {ZetoLockDelegated}.
-     */
+    /// @inheritdoc ILockableCapability
     function delegateLock(
         bytes32 lockId,
         bytes calldata delegateArgs,
         address newSpender,
         bytes calldata data
-    ) external override lockActive(lockId) onlyLockSpender(lockId) {
-        ZetoDelegateLockArgs memory args = abi.decode(
-            delegateArgs,
-            (ZetoDelegateLockArgs)
-        );
-        _useTxId(args.txId);
-
-        ZetoLockableStorage.ZetoLockInfo storage lock = ZetoLockableStorage
-            .layout()
-            .locks[lockId];
-        address previousSpender = lock.spender;
-        lock.spender = newSpender;
-
-        _setLockDelegates(lock.lockedInputs, newSpender);
-
-        emit LockDelegated(lockId, previousSpender, newSpender, data);
-        emit ZetoLockDelegated(
-            args.txId,
+    ) external override {
+        ZetoLockableLib.delegateLock(
             lockId,
-            previousSpender,
+            delegateArgs,
             newSpender,
             data
         );
     }
 
-    /**
-     * @dev Spend the lock by executing the committed unlock operation.
-     *      If `spendCommitment` is non-zero, the supplied spendArgs MUST
-     *      hash to it.
-     *
-     * Emits {LockSpent} and {ZetoLockSpent}.
-     */
+    /// @inheritdoc ILockableCapability
     function spendLock(
         bytes32 lockId,
         bytes calldata spendArgs,
         bytes calldata data
-    ) external virtual override lockActive(lockId) onlyLockSpender(lockId) {
-        ZetoSpendLockArgs memory args = abi.decode(
-            spendArgs,
-            (ZetoSpendLockArgs)
-        );
-
-        // Snapshot the locked content from storage. The caller is
-        // intentionally not allowed to substitute a different set of
-        // locked inputs.
-        uint256[] memory lockedInputs = ZetoLockableStorage
-            .layout()
-            .locks[lockId]
-            .lockedInputs;
-        bytes32 expectedHash = ZetoLockableStorage
-            .layout()
-            .locks[lockId]
-            .spendCommitment;
-        _consumeLock(
-            lockId,
-            lockedInputs,
-            expectedHash,
-            _SPEND_HASH_DOMAIN,
-            args
-        );
-
-        emit LockSpent(lockId, msg.sender, data);
-        emit ZetoLockSpent(
-            args.txId,
-            lockId,
-            msg.sender,
-            lockedInputs,
-            args.lockedOutputs,
-            args.outputs,
-            args.proof,
-            data
-        );
+    ) external override {
+        ZetoLockableLib.spendLock(lockId, spendArgs, data);
     }
 
-    /**
-     * @dev Cancel the lock by executing the committed cancellation
-     *      operation. If `cancelCommitment` is non-zero, the supplied
-     *      cancelArgs MUST hash to it.
-     *
-     * Emits {LockCancelled} and {ZetoLockCancelled}.
-     */
+    /// @inheritdoc ILockableCapability
     function cancelLock(
         bytes32 lockId,
         bytes calldata cancelArgs,
         bytes calldata data
-    ) external virtual override lockActive(lockId) onlyLockSpender(lockId) {
-        ZetoSpendLockArgs memory args = abi.decode(
-            cancelArgs,
-            (ZetoSpendLockArgs)
-        );
-
-        uint256[] memory lockedInputs = ZetoLockableStorage
-            .layout()
-            .locks[lockId]
-            .lockedInputs;
-        bytes32 expectedHash = ZetoLockableStorage
-            .layout()
-            .locks[lockId]
-            .cancelCommitment;
-        _consumeLock(
-            lockId,
-            lockedInputs,
-            expectedHash,
-            _CANCEL_HASH_DOMAIN,
-            args
-        );
-
-        emit LockCancelled(lockId, msg.sender, data);
-        emit ZetoLockCancelled(
-            args.txId,
-            lockId,
-            msg.sender,
-            lockedInputs,
-            args.lockedOutputs,
-            args.outputs,
-            args.proof,
-            data
-        );
+    ) external override {
+        ZetoLockableLib.cancelLock(lockId, cancelArgs, data);
     }
 
-    // ------------------------------------------------------------------
-    // ILockableCapability views
-    // ------------------------------------------------------------------
-
+    /// @inheritdoc ILockableCapability
     function getLock(
         bytes32 lockId
-    ) external view override lockActive(lockId) returns (LockInfo memory) {
-        ZetoLockableStorage.ZetoLockInfo storage lock = ZetoLockableStorage
-            .layout()
-            .locks[lockId];
-        return
-            LockInfo({
-                owner: lock.owner,
-                spender: lock.spender,
-                spendCommitment: lock.spendCommitment,
-                cancelCommitment: lock.cancelCommitment
-            });
+    ) external view override returns (LockInfo memory) {
+        return ZetoLockableLib.getLock(lockId);
     }
 
+    /// @inheritdoc ILockableCapability
     function isLockActive(
         bytes32 lockId
     ) external view override returns (bool) {
-        return ZetoLockableStorage.layout().locks[lockId].owner != address(0);
+        return ZetoLockableLib.isLockActive(lockId);
     }
 
+    /// @inheritdoc ILockableCapability
     function getLockContent(
         bytes32 lockId
-    ) external view override lockActive(lockId) returns (bytes memory content) {
-        return
-            abi.encode(ZetoLockableStorage.layout().locks[lockId].lockedInputs);
+    ) external view override returns (bytes memory content) {
+        return ZetoLockableLib.getLockContent(lockId);
     }
 
     /// @inheritdoc IZetoLockableCapability
     function getLockedInputs(
         bytes32 lockId
-    )
-        external
-        view
-        override
-        lockActive(lockId)
-        returns (uint256[] memory lockedInputs)
-    {
-        return ZetoLockableStorage.layout().locks[lockId].lockedInputs;
+    ) external view override returns (uint256[] memory lockedInputs) {
+        return ZetoLockableLib.getLockedInputs(lockId);
     }
 
-    /**
-     * @dev Override of {ZetoCommon.locked} that fills in the per-UTXO
-     *      spender from the {_utxoDelegates} projection. The storage
-     *      layer only tells us "is this locked"; the spender lives at
-     *      this layer because the lock model itself does.
-     *
-     *      Returns `(false, address(0))` for any UTXO that is not
-     *      currently locked-unspent, including UTXOs whose lock has
-     *      been spent or cancelled (since both the storage layer's
-     *      locked-set is cleared and `_utxoDelegates[X]` is wiped in
-     *      the consume path).
-     */
+    /// @inheritdoc ZetoCommon
     function locked(uint256 utxo) public view override returns (bool, address) {
-        if (!ZetoCommonStorage.layout().utxoStorage.locked(utxo)) {
-            return (false, address(0));
-        }
-        return (true, ZetoLockableStorage.layout().utxoDelegates[utxo]);
+        return ZetoLockableLib.locked(utxo);
     }
 
-    // ------------------------------------------------------------------
-    // Internals
-    // ------------------------------------------------------------------
-
-    /**
-     * @dev Verify the ZK proof authorizing a {createLock} call and
-     *      apply the resulting state transition. Implementations differ
-     *      between fungible (padding to the next supported batch size)
-     *      and non-fungible (fixed 1-in/1-out) tokens, so this hook is
-     *      left abstract. They MUST:
-     *
-     *        1. {validateTransactionProposal}(args.inputs, args.outputs,
-     *           args.lockedOutputs, args.proof, false).
-     *        2. {constructPublicInputs}(...) and
-     *           {verifyProof}(...) for the unlocked-inputs flavour.
-     *        3. {processInputsAndOutputs}(args.inputs, args.outputs,
-     *           false).
-     *        4. {processLockedOutputs}(args.lockedOutputs).
-     *        5. {_setLockDelegates}(args.lockedOutputs, msg.sender).
-     */
-    function _doLockTransition(ZetoCreateLockArgs memory args) internal virtual;
-
-    /**
-     * @dev Apply the ZK-verified state transition that consumes a
-     *      lock's `lockedInputs`. See {_doLockTransition} for the
-     *      rationale for keeping this abstract.
-     */
-    function _transferLocked(
-        bytes32 lockId,
-        uint256[] memory lockedInputs,
-        uint256[] memory lockedOutputs,
-        uint256[] memory outputs,
-        bytes memory proof,
-        bytes memory data
-    ) internal virtual;
+    /// @inheritdoc IZetoLockHooks
+    function zetoLockDoLockTransition(
+        ZetoCreateLockArgs calldata args
+    ) external override onlySelf {
+        _doLockTransition(args);
+    }
 
-    /**
-     * @dev Consume an active lock.
-     *
-     *      `lockedInputs` MUST be the lock's storage-pinned content
-     *      (read by the caller from `_locks[lockId].lockedInputs`). The
-     *      spender does not get to choose which UTXOs are consumed: that
-     *      decision was made at {createLock} time. This is what makes
-     *      "spending lock A consumes lock A's UTXOs" a hard contract
-     *      invariant.
-     */
-    function _consumeLock(
+    /// @inheritdoc IZetoLockHooks
+    function zetoLockTransferLocked(
         bytes32 lockId,
-        uint256[] memory lockedInputs,
-        bytes32 expectedHash,
-        bytes32 hashDomain,
-        ZetoSpendLockArgs memory args
-    ) internal {
-        _useTxId(args.txId);
-
-        if (expectedHash != 0) {
-            bytes32 actualHash = _buildUnlockHash(
-                lockedInputs,
-                args.lockedOutputs,
-                args.outputs,
-                args.data,
-                hashDomain
-            );
-            if (actualHash != expectedHash) {
-                revert InvalidUnlockHash(expectedHash, actualHash);
-            }
-        }
-
-        // Tear down all lock-spender state BEFORE performing the state
-        // transition, so any reentrant lookup observes both
-        // `_locks[lockId]` and the per-UTXO `_utxoDelegates` projection
-        // as cleared.
-        _clearLockDelegates(lockedInputs);
-        delete ZetoLockableStorage.layout().locks[lockId];
-
+        uint256[] calldata lockedInputs,
+        uint256[] calldata lockedOutputs,
+        uint256[] calldata outputs,
+        bytes calldata proof,
+        bytes calldata data
+    ) external override onlySelf {
         _transferLocked(
             lockId,
             lockedInputs,
-            args.lockedOutputs,
-            args.outputs,
-            args.proof,
-            args.data
+            lockedOutputs,
+            outputs,
+            proof,
+            data
         );
     }
 
-    /// @dev Build the unlock hash committed to by
-    ///      {ZetoLockInfo.spendCommitment} or
-    ///      {ZetoLockInfo.cancelCommitment}. `domain` is a per-intent
-    ///      separation tag (see {_SPEND_HASH_DOMAIN} /
-    ///      {_CANCEL_HASH_DOMAIN}) so that the two commitments live in
-    ///      disjoint hash spaces.
-    ///
-    ///      Each variable-length component is hashed as
-    ///      `abi.encode(...)` rather than `abi.encodePacked(...)` to
-    ///      avoid the cross-array length-ambiguity that `encodePacked`
-    ///      introduces for dynamic arguments (e.g. `[1, 2]` and `[12]`
-    ///      collide under `encodePacked` but not under `encode`).
-    function _buildUnlockHash(
-        uint256[] memory lockedInputs,
-        uint256[] memory lockedOutputs,
-        uint256[] memory outputs,
-        bytes memory data,
-        bytes32 domain
-    ) internal pure returns (bytes32) {
-        return
-            keccak256(
-                abi.encode(
-                    domain,
-                    keccak256(abi.encode(lockedInputs)),
-                    keccak256(abi.encode(lockedOutputs)),
-                    keccak256(abi.encode(outputs)),
-                    keccak256(data)
-                )
-            );
-    }
-}
-
-/// @dev ERC-7201 (`erc7201:zeto.storage.ZetoLockable`): lock lifecycle state for
-///      this abstract contract.
-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 _doLockTransition(
+        ZetoCreateLockArgs calldata args
+    ) internal virtual;
 
-    function layout() internal pure returns (Layout storage $) {
-        assembly {
-            $.slot := STORAGE_LOCATION
-        }
-    }
+    function _transferLocked(
+        bytes32 lockId,
+        uint256[] calldata lockedInputs,
+        uint256[] calldata lockedOutputs,
+        uint256[] calldata outputs,
+        bytes calldata proof,
+        bytes calldata data
+    ) internal virtual;
 }