@lfdecentralizedtrust/zeto-contracts 0.2.2 → 0.5.1

package/contracts/lib/interfaces/ILockableCapability.sol

@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.27;
+
+/**
+ * @title ILockableCapability
+ * @dev Generic interface for representing a locked capability that can be
+ *      delegated and eventually consumed ("spent") or cancelled by a
+ *      designated spender.
+ *
+ *      A "capability" here is any predefined state-changing operation: it may
+ *      involve tokens, a function call, or any other effect defined by the
+ *      implementing contract.
+ *
+ *      Core guarantees:
+ *        - Each lock is identified by a unique lockId, generated by the
+ *          implementing contract.
+ *        - For each active lock, there is exactly one current spender
+ *          address (the "authorized spender").
+ *        - Initially, the lock creator is both the owner and the spender.
+ *        - Only the current spender is allowed to spend, cancel, or delegate
+ *          the lock.
+ *        - This interface does not prescribe expiry, auto-cancellation, or
+ *          owner-controlled clawback. Once a lock is created and delegated,
+ *          the original owner cannot prevent the current spender from using
+ *          it (except by becoming the current spender again through delegation).
+ *        - Constraints beyond this base model should be implemented by delegating
+ *          the lock to a separate policy contract.
+ *
+ *      The intent is that, so long as a lock remains active and the caller is
+ *      the current spender, the implementing contract MUST NOT introduce
+ *      arbitrary revocation or expiry logic beyond:
+ *        - the lock having already been spent or cancelled; or
+ *        - the caller not being the current spender; or
+ *        - the provided data failing validation as defined by the specific
+ *          implementation.
+ *
+ *      Notes on dynamically typed arguments:
+ *        - Each `*Args` parameter contains implementation-specific,
+ *          ABI-encoded calldata used to carry out that lifecycle action.
+ *          Implementations are RECOMMENDED to define and document a canonical
+ *          struct type for each such argument payload, and to encode that
+ *          struct using `abi.encode(...)` when calling the interface methods.
+ *        - Each `data` parameter contains application-specific calldata,
+ *          which is passed through to emitted events.
+ */
+interface ILockableCapability {
+    /**
+     * @dev Stored lock info available to query by lockId.
+     */
+    struct LockInfo {
+        /**
+         * @dev The address that originally created the lock.
+         *      Immutable for the lifetime of the lock.
+         */
+        address owner;
+        /**
+         * @dev The address currently authorized to spend, cancel, or delegate the lock.
+         *      Mutable by the current spender while the lock remains active.
+         */
+        address spender;
+        /**
+         * @dev An implementation-defined commitment to the spend operation permitted for this lock.
+         *      Zero must be supported by the spending logic and treated as "unrestricted".
+         *      Mutable if and only if the lock is active and owner-controlled
+         *      (`spender == owner`).
+         */
+        bytes32 spendCommitment;
+        /**
+         * @dev An implementation-defined commitment to the cancellation operation permitted for this lock.
+         *      Zero must be supported by the cancellation logic and treated as "unrestricted".
+         *      Mutable if and only if the lock is active and owner-controlled
+         *      (`spender == owner`).
+         */
+        bytes32 cancelCommitment;
+    }
+
+    /**
+     * @dev Emitted when a lock is created.
+     */
+    event LockCreated(
+        bytes32 indexed lockId,
+        address indexed owner,
+        address indexed spender,
+        bytes32 spendCommitment,
+        bytes32 cancelCommitment,
+        bytes data
+    );
+
+    /**
+     * @dev Emitted when an active lock is updated.
+     */
+    event LockUpdated(
+        bytes32 indexed lockId,
+        address indexed owner,
+        bytes32 spendCommitment,
+        bytes32 cancelCommitment,
+        bytes data
+    );
+
+    /**
+     * @dev Emitted when spending authority is delegated from one address to another.
+     */
+    event LockDelegated(
+        bytes32 indexed lockId,
+        address indexed from,
+        address indexed to,
+        bytes data
+    );
+
+    /**
+     * @dev Emitted when a lock is successfully spent.
+     */
+    event LockSpent(
+        bytes32 indexed lockId,
+        address indexed spender,
+        bytes data
+    );
+
+    /**
+     * @dev Emitted when a lock is successfully cancelled.
+     */
+    event LockCancelled(
+        bytes32 indexed lockId,
+        address indexed spender,
+        bytes data
+    );
+
+    /**
+     * @dev Thrown when a lock does not exist or is not active.
+     */
+    error LockNotActive(bytes32 lockId);
+
+    /**
+     * @dev Thrown when the caller is not the current spender for the given lock.
+     */
+    error LockUnauthorized(bytes32 lockId, address spender, address caller);
+
+    /**
+     * @dev Thrown when an attempted mutation is not permitted under the lock's
+     *      mutability rules.
+     */
+    error LockImmutable(bytes32 lockId);
+
+    /**
+     * @dev Create a new lock.
+     *      Moves control of the relevant value/state/activity to the lock.
+     *
+     *      Locks are identified by a unique lockId, generated in an
+     *      implementation-specific way.
+     *      Implementations SHOULD generate lockId deterministically from
+     *      immutable lock properties where practical.
+     *
+     * Requirements:
+     *  - MUST create the lock in the active state
+     *  - MUST set owner to msg.sender
+     *  - MUST set spender to msg.sender initially
+     *
+     * @param createArgs       Implementation-specific calldata needed to create the lock.
+     * @param spendCommitment  An implementation-defined commitment to the spend operation permitted for this lock.
+     * @param cancelCommitment An implementation-defined commitment to the cancellation operation permitted for this lock.
+     * @param data             Auxiliary application-specific calldata.
+     * @return lockId          The generated unique identifier for the lock.
+     *
+     * Emits a {LockCreated} event.
+     */
+    function createLock(
+        bytes calldata createArgs,
+        bytes32 spendCommitment,
+        bytes32 cancelCommitment,
+        bytes calldata data
+    ) external returns (bytes32 lockId);
+
+    /**
+     * @dev Update an existing active, owner-controlled lock.
+     *
+     *      `spendCommitment` and `cancelCommitment` fully replace the previous
+     *      commitment values.
+     *      Delegates can never alter the shape or purpose of a lock.
+     *
+     * Requirements:
+     *  - MUST revert with LockNotActive(lockId) if the lock is not active
+     *  - MUST revert with LockImmutable(lockId) unless the lock is currently
+     *    owner-controlled (`spender == owner`) and the requested mutation is
+     *    permitted by the implementation
+     *
+     * @param lockId           The unique identifier for the lock.
+     * @param updateArgs       Implementation-specific calldata needed to update the lock.
+     * @param spendCommitment  Replacement spend commitment.
+     * @param cancelCommitment Replacement cancel commitment.
+     * @param data             Auxiliary application-specific calldata.
+     *
+     * Emits a {LockUpdated} event.
+     */
+    function updateLock(
+        bytes32 lockId,
+        bytes calldata updateArgs,
+        bytes32 spendCommitment,
+        bytes32 cancelCommitment,
+        bytes calldata data
+    ) external;
+
+    /**
+     * @dev Delegate spending authority for this lock to a new address.
+     *
+     *      After delegation:
+     *        - The previous spender MUST no longer be allowed to spend or
+     *          cancel the lock (unless they later regain spender status).
+     *        - `spendCommitment` and `cancelCommitment` MUST be immutable while
+     *          the lock is not owner-controlled.
+     *
+     *      Delegation is reversible by the current spender, including
+     *      delegation back to the owner.
+     *
+     * Requirements:
+     *  - MUST revert with LockUnauthorized(lockId, currentSpender, msg.sender)
+     *    if msg.sender is not the current spender for lockId
+     *  - MUST revert with LockNotActive(lockId) if the lock is not active
+     *
+     * @param lockId       The unique identifier for the lock.
+     * @param delegateArgs Implementation-specific calldata needed to delegate the lock.
+     * @param newSpender   The address to delegate the lock to.
+     * @param data         Auxiliary application-specific calldata.
+     *
+     * Emits a {LockDelegated} event.
+     */
+    function delegateLock(
+        bytes32 lockId,
+        bytes calldata delegateArgs,
+        address newSpender,
+        bytes calldata data
+    ) external;
+
+    /**
+     * @dev Spend the lock.
+     *      Consumes or executes the effect of the lock (for example: releasing tokens,
+     *      executing a function call, etc).
+     *
+     * Requirements:
+     *  - MUST revert with LockUnauthorized(lockId, currentSpender, msg.sender)
+     *    if msg.sender is not the current spender for lockId
+     *  - MUST revert with LockNotActive(lockId) if the lock is not active
+     *  - MUST remove the lock (or mark as inactive) if successful
+     *
+     * @param lockId    The unique identifier for the lock.
+     * @param spendArgs Implementation-specific calldata needed to spend the lock.
+     * @param data      Auxiliary application-specific calldata.
+     *
+     * Emits a {LockSpent} event.
+     */
+    function spendLock(
+        bytes32 lockId,
+        bytes calldata spendArgs,
+        bytes calldata data
+    ) external;
+
+    /**
+     * @dev Cancel the lock.
+     *      Performs the cancellation operation for the lock (for example: refunding
+     *      tokens, executing a function call, etc).
+     *
+     * Requirements:
+     *  - MUST revert with LockUnauthorized(lockId, currentSpender, msg.sender)
+     *    if msg.sender is not the current spender for lockId
+     *  - MUST revert with LockNotActive(lockId) if the lock is not active
+     *  - MUST remove the lock (or mark as inactive) if successful
+     *
+     * @param lockId     The unique identifier for the lock.
+     * @param cancelArgs Implementation-specific calldata needed to cancel the lock.
+     * @param data       Auxiliary application-specific calldata.
+     *
+     * Emits a {LockCancelled} event.
+     */
+    function cancelLock(
+        bytes32 lockId,
+        bytes calldata cancelArgs,
+        bytes calldata data
+    ) external;
+
+    /**
+     * @dev Get stored lock information for an active lock.
+     *
+     * Requirements:
+     *  - MUST revert with LockNotActive(lockId) if the lock is not active.
+     *
+     * @param lockId The unique identifier for the lock.
+     * @return info  Stored lock information.
+     */
+    function getLock(
+        bytes32 lockId
+    ) external view returns (LockInfo memory info);
+
+    /**
+     * @dev Query whether the lock is currently active.
+     *
+     *      MUST return false for locks that do not exist and for locks that
+     *      have been spent or cancelled.
+     *
+     * @param lockId The unique identifier for the lock.
+     * @return active Whether the lock is currently active.
+     */
+    function isLockActive(bytes32 lockId) external view returns (bool active);
+
+    /**
+     * @dev Get implementation-specific lock content for an active lock.
+     *
+     *      This represents the data or operation that was locked, and is
+     *      immutable once the lock is created.
+     *
+     * Requirements:
+     *  - MUST revert with LockNotActive(lockId) if the lock is not active.
+     *
+     * @param lockId The unique identifier for the lock.
+     * @return content The implementation-specific lock content.
+     */
+    function getLockContent(
+        bytes32 lockId
+    ) external view returns (bytes memory content);
+}

package/contracts/lib/interfaces/{izeto.sol → IZeto.sol}

@@ -17,7 +17,8 @@ pragma solidity ^0.8.27;
 
 uint256 constant MAX_BATCH = 10;
 uint256 constant MAX_SMT_DEPTH = 64;
-interface IZeto {
+
+interface IZetoConstants {
     error UTXODuplicate(uint256 utxo);
     error UTXOArrayTooLarge(uint256 maxAllowed);
     error UTXONotMinted(uint256 utxo);
@@ -46,6 +47,15 @@ interface IZeto {
         address indexed submitter,
         bytes data
     );
+    event UTXOTransferWithMlkemEncryptedValues(
+        uint256[] inputs,
+        uint256[] outputs,
+        uint256 encryptionNonce,
+        uint256[25] encapsulatedSharedSecret,
+        uint256[] encryptedValues,
+        address indexed submitter,
+        bytes data
+    );
     event UTXOWithdraw(
         uint256 amount,
         uint256[] inputs,
@@ -53,7 +63,9 @@ interface IZeto {
         address indexed submitter,
         bytes data
     );
+}
 
+interface IZeto is IZetoConstants {
     /**
      * @dev Returns the name of the token.
      */

package/contracts/lib/interfaces/{izeto_initializable.sol → IZetoInitializable.sol}

@@ -15,23 +15,25 @@
 // limitations under the License.
 pragma solidity ^0.8.27;
 
+import {IGroth16Verifier} from "./IZetoVerifier.sol";
+
 interface IZetoInitializable {
     struct VerifiersInfo {
-        address verifier;
-        address depositVerifier;
-        address withdrawVerifier;
-        address lockVerifier;
-        address burnVerifier;
-        address batchVerifier;
-        address batchWithdrawVerifier;
-        address batchLockVerifier;
-        address batchBurnVerifier;
+        IGroth16Verifier verifier;
+        IGroth16Verifier depositVerifier;
+        IGroth16Verifier withdrawVerifier;
+        IGroth16Verifier lockVerifier;
+        IGroth16Verifier burnVerifier;
+        IGroth16Verifier batchVerifier;
+        IGroth16Verifier batchWithdrawVerifier;
+        IGroth16Verifier batchLockVerifier;
+        IGroth16Verifier batchBurnVerifier;
     }
 
     function initialize(
-        string memory name,
-        string memory symbol,
+        string calldata name,
+        string calldata symbol,
         address initialOwner,
-        VerifiersInfo memory verifiersInfo
+        VerifiersInfo calldata verifiersInfo
     ) external;
 }

package/contracts/lib/interfaces/{izeto_kyc.sol → IZetoKyc.sol}

@@ -15,18 +15,18 @@
 // limitations under the License.
 pragma solidity ^0.8.27;
 
-import {Commonlib} from "../common.sol";
+import {Commonlib} from "../common/common.sol";
 
 interface IZetoKyc {
     event IdentityRegistered(uint256[2] publicKey, bytes data);
 
     function register(
-        uint256[2] memory publicKey,
+        uint256[2] calldata publicKey,
         bytes calldata data
     ) external;
 
     function isRegistered(
-        uint256[2] memory publicKey
+        uint256[2] calldata publicKey
     ) external view returns (bool);
 
     function getIdentitiesRoot() external view returns (uint256);

package/contracts/lib/interfaces/IZetoLockHooks.sol

@@ -0,0 +1,42 @@
+// 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 {IZetoLockableCapability} from "./IZetoLockableCapability.sol";
+
+/**
+ * @title IZetoLockHooks
+ * @dev Callback surface invoked by {ZetoLockableLib} (via `address(this)`)
+ *      so circuit-specific lock transitions stay in the embedding token
+ *      while shared lock lifecycle logic lives in the external library.
+ */
+interface IZetoLockHooks {
+    /// @dev Thrown when a hook is invoked by an address other than `address(this)`.
+    error NotSelf(address caller);
+
+    function zetoLockDoLockTransition(
+        IZetoLockableCapability.ZetoCreateLockArgs calldata args
+    ) external;
+
+    function zetoLockTransferLocked(
+        bytes32 lockId,
+        uint256[] calldata lockedInputs,
+        uint256[] calldata lockedOutputs,
+        uint256[] calldata outputs,
+        bytes calldata proof,
+        bytes calldata data
+    ) external;
+}

package/contracts/lib/interfaces/IZetoLockableCapability.sol

@@ -0,0 +1,237 @@
+// 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 {ILockableCapability} from "./ILockableCapability.sol";
+
+/**
+ * @title IZetoLockableCapability
+ * @dev Zeto-specific extension of {ILockableCapability}.
+ *
+ *      Defines the canonical ABI-encoded payloads (`*Args` parameters) and the
+ *      Zeto-specific events emitted alongside the generic ILockableCapability
+ *      events, mirroring the pattern used by the noto domain in Paladin.
+ *
+ *      The lockId is generated deterministically as
+ *      `keccak256(abi.encode(address(this), msg.sender, args.txId))` and can be
+ *      predicted via {computeLockId} before calling {createLock}.
+ */
+interface IZetoLockableCapability is ILockableCapability {
+    // ----------------------------------------------------------------------
+    // Errors retained from the previous IZetoLockable interface
+    // ----------------------------------------------------------------------
+
+    /// @dev Thrown when a UTXO is already locked at the storage layer.
+    error AlreadyLocked(uint256 utxo);
+
+    /// @dev Thrown when a UTXO is referenced as locked input but is not locked.
+    error NotLocked(uint256 utxo);
+
+    /// @dev Thrown when the caller is not the current per-UTXO storage delegate.
+    error NotLockDelegate(
+        uint256 utxo,
+        address currentDelegate,
+        address sender
+    );
+
+    /// @dev Thrown when a provided spend/cancel payload does not hash to the
+    ///      previously committed value.
+    error InvalidUnlockHash(bytes32 expected, bytes32 actual);
+
+    /// @dev Thrown when the caller-supplied txId has already been used.
+    error DuplicateTransaction(bytes32 txId);
+
+    /// @dev Thrown when computeLockId would collide with an already-active lock.
+    error DuplicateLock(bytes32 lockId);
+
+    // ----------------------------------------------------------------------
+    // ABI-encoded argument payloads carried by the generic *Args parameters
+    // ----------------------------------------------------------------------
+
+    /**
+     * @dev Payload for {ILockableCapability.createLock}.createArgs.
+     *
+     *      The transaction consumes `inputs` (regular UTXOs/nullifiers) and
+     *      produces `outputs` (regular UTXOs) and `lockedOutputs` (the locked
+     *      content held under the lock). `proof` is the ZK proof authorising
+     *      the state transition.
+     */
+    struct ZetoCreateLockArgs {
+        bytes32 txId;
+        uint256[] inputs;
+        uint256[] outputs;
+        uint256[] lockedOutputs;
+        bytes proof;
+    }
+
+    /**
+     * @dev Payload for {ILockableCapability.updateLock}.updateArgs.
+     *
+     *      Update is metadata-only on Zeto (it rewrites the spend/cancel
+     *      commitments), so only a fresh txId is required.
+     */
+    struct ZetoUpdateLockArgs {
+        bytes32 txId;
+    }
+
+    /**
+     * @dev Payload for {ILockableCapability.delegateLock}.delegateArgs.
+     */
+    struct ZetoDelegateLockArgs {
+        bytes32 txId;
+    }
+
+    /**
+     * @dev Payload for {ILockableCapability.spendLock}.spendArgs and
+     *      {ILockableCapability.cancelLock}.cancelArgs.
+     *
+     *      The set of locked UTXOs being consumed is intentionally NOT carried
+     *      here: it is taken verbatim from the lock's storage-pinned content
+     *      (see {getLockContent}) so that "spending lock A always consumes lock
+     *      A's UTXOs" is a hard contract invariant rather than a soft hash
+     *      check. The {InvalidUnlockHash} check is therefore computed over
+     *      `(lock.lockedInputs, lockedOutputs, outputs, data)` where
+     *      `lock.lockedInputs` is read from storage.
+     */
+    struct ZetoSpendLockArgs {
+        bytes32 txId;
+        uint256[] lockedOutputs;
+        uint256[] outputs;
+        bytes proof;
+        bytes data;
+    }
+
+    // ----------------------------------------------------------------------
+    // Zeto-specific events emitted alongside the generic events
+    // ----------------------------------------------------------------------
+
+    /// @dev Emitted alongside {LockCreated} with decoded Zeto parameters.
+    event ZetoLockCreated(
+        bytes32 indexed txId,
+        bytes32 indexed lockId,
+        address indexed owner,
+        uint256[] inputs,
+        uint256[] outputs,
+        uint256[] lockedOutputs,
+        bytes proof,
+        bytes data
+    );
+
+    /// @dev Emitted alongside {LockUpdated} with the Zeto txId.
+    event ZetoLockUpdated(
+        bytes32 indexed txId,
+        bytes32 indexed lockId,
+        address indexed owner,
+        bytes data
+    );
+
+    /// @dev Emitted alongside {LockDelegated} with the Zeto txId.
+    event ZetoLockDelegated(
+        bytes32 indexed txId,
+        bytes32 indexed lockId,
+        address indexed from,
+        address to,
+        bytes data
+    );
+
+    /// @dev Emitted alongside {LockSpent} with decoded Zeto parameters.
+    ///      `lockedInputs` is the lock's storage-pinned content, not a
+    ///      caller-supplied value (see {ZetoSpendLockArgs}).
+    event ZetoLockSpent(
+        bytes32 indexed txId,
+        bytes32 indexed lockId,
+        address indexed spender,
+        uint256[] lockedInputs,
+        uint256[] lockedOutputs,
+        uint256[] outputs,
+        bytes proof,
+        bytes data
+    );
+
+    /// @dev Emitted alongside {LockCancelled} with decoded Zeto parameters.
+    ///      `lockedInputs` is the lock's storage-pinned content, not a
+    ///      caller-supplied value (see {ZetoSpendLockArgs}).
+    event ZetoLockCancelled(
+        bytes32 indexed txId,
+        bytes32 indexed lockId,
+        address indexed spender,
+        uint256[] lockedInputs,
+        uint256[] lockedOutputs,
+        uint256[] outputs,
+        bytes proof,
+        bytes data
+    );
+
+    // ----------------------------------------------------------------------
+    // Zeto-specific view helpers
+    // ----------------------------------------------------------------------
+
+    /**
+     * @dev Compute the lockId that {createLock} would generate for a given
+     *      caller and createArgs payload. Useful for off-chain pre-computation.
+     *
+     * @param createArgs ABI-encoded {ZetoCreateLockArgs}.
+     * @return lockId    The lockId that would be assigned.
+     */
+    function computeLockId(
+        bytes calldata createArgs
+    ) external view returns (bytes32 lockId);
+
+    /**
+     * @dev Compute the spend-intent commitment for a prospective
+     *      {ZetoSpendLockArgs} payload. The returned hash is what the lock
+     *      creator should pass as `spendCommitment` to {createLock} (or to
+     *      {updateLock}) if they want to bind the spender to a specific
+     *      spend payload.
+     *
+     *      Implementations MUST compute this in a hash space that is
+     *      disjoint from {computeCancelHash} so that a spender cannot
+     *      transpose a spend payload into {cancelLock} (or vice versa).
+     */
+    function computeSpendHash(
+        uint256[] calldata lockedInputs,
+        uint256[] calldata lockedOutputs,
+        uint256[] calldata outputs,
+        bytes calldata data
+    ) external pure returns (bytes32);
+
+    /**
+     * @dev Compute the cancel-intent commitment for a prospective
+     *      {ZetoSpendLockArgs} payload. See {computeSpendHash} for the
+     *      domain-separation rationale.
+     */
+    function computeCancelHash(
+        uint256[] calldata lockedInputs,
+        uint256[] calldata lockedOutputs,
+        uint256[] calldata outputs,
+        bytes calldata data
+    ) external pure returns (bytes32);
+
+    /**
+     * @dev Typed view returning the locked UTXOs held under `lockId`.
+     *
+     *      This is the canonical accessor for the lock content. The generic
+     *      {ILockableCapability.getLockContent} returns the same data
+     *      `abi.encode`-d into `bytes` for compatibility with callers that
+     *      treat lock contents opaquely.
+     *
+     * Requirements:
+     *  - MUST revert with {LockNotActive}(lockId) if the lock is not active.
+     */
+    function getLockedInputs(
+        bytes32 lockId
+    ) external view returns (uint256[] memory lockedInputs);
+}