[ETHEREUM-CONTRACTS] ClearMacro forwarder (+ Permit2 variant)

packages/ethereum-contracts/CHANGELOG.md

@@ -3,10 +3,21 @@ All notable changes to the ethereum-contracts will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [UNRELEASED]
+
+### Added
+
+- `Permit2ClearMacroForwarder`: a new macro forwarder that executes EIP-712-signed meta-transactions with properties giving it additional security guarantees, optionally with Permit2 support (allowing to have underlying upgraded + a macro executed, all with one wallet action).
+- `ClearMacroBase`: a new base contract for clear macro implementations that support multiple actions.
+
+### Breaking
+- `IUserDefinedMacro` renamed to `IMacro`.
+
 ## [v1.15.0]
 
 ### Added
 
+- `[Permit2]ClearMacroForwarder`: a new macro forwarder that executes EIP-712-signed meta-transactions with properties giving it additional security guarantees, optionally with Permit2 support (allowing to have underlying upgraded + a macro executed, all with one wallet action).
 - `SuperToken`: the contract admin can enable/disable a _Yield Backend_ in order to generate a yield on the underlying asset.
 - `SuperToken`: added `VERSION()` which returns the version string of the logic contract set for the SuperToken, and inline CHANGELOG.
 

packages/ethereum-contracts/contracts/interfaces/external/IPermit2.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice Minimal interface for Uniswap Permit2 (SignatureTransfer).
+/// @dev Canonical address: 0x000000000022D473030F116dDEE9F6B43aC78BA3
+/// For the full Permit2 interface, see https://github.com/Uniswap/permit2/blob/main/src/interfaces/IPermit2.sol
+interface IPermit2 {
+    struct TokenPermissions {
+        address token;
+        uint256 amount;
+    }
+    struct PermitTransferFrom {
+        TokenPermissions permitted;
+        uint256 nonce;
+        uint256 deadline;
+    }
+    struct SignatureTransferDetails {
+        address to;
+        uint256 requestedAmount;
+    }
+
+    function DOMAIN_SEPARATOR() external view returns (bytes32);
+
+    function permitWitnessTransferFrom(
+        PermitTransferFrom calldata permit,
+        SignatureTransferDetails calldata transferDetails,
+        address owner,
+        bytes32 witness,
+        string calldata witnessTypeString,
+        bytes calldata signature
+    ) external;
+}

packages/ethereum-contracts/contracts/interfaces/utils/IClearMacro.sol

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.11;
+
+import { IMacro } from "./IMacro.sol";
+
+/**
+ * @dev Interface for a macro used with the ClearMacroForwarder.
+ * Implementations provide the EIP-712 metadata and hashing logic for the
+ * macro-specific action encoded in `params`.
+ */
+interface IClearMacro is IMacro {
+    /**
+     * @dev Returns the primary EIP-712 type name.
+     * This is usually rendered prominently by wallets and should concisely
+     * describe the action or intent to be signed.
+     * @param  params Encoded macro-specific parameters.
+     * @return name  The primary type name.
+     */
+    function getPrimaryTypeName(bytes memory params) external view returns (string memory);
+
+    /**
+     * @dev Returns the EIP-712 type definition of the action.
+     * The type name must be `Action`; only the fields are implementation-specific.
+     * @param  params     Encoded macro-specific parameters.
+     * @return typeDef    The `Action(...)` type definition.
+     */
+    function getActionTypeDefinition(bytes memory params) external view returns (string memory);
+
+    /**
+     * @dev Returns the EIP-712 struct hash of the action encoded in `params`.
+     * The hash must be constructed from the `Action` type definition and the
+     * underlying action data according to the EIP-712 standard.
+     * @param  params        Encoded macro-specific parameters.
+     * @return structHash    The EIP-712 struct hash of the action.
+     */
+    function getActionStructHash(bytes memory params) external view returns (bytes32);
+}

packages/ethereum-contracts/contracts/interfaces/utils/IClearMacroForwarder.sol

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.11;
+
+import { IClearMacro } from "./IClearMacro.sol";
+
+/**
+ * @dev Interface for ClearMacro forwarders.
+ * A ClearMacro forwarder executes EIP-712 signed meta-transactions whose
+ * payload consists of macro-specific action data and additional security
+ * parameters.
+ */
+interface IClearMacroForwarder {
+    /**
+     * @dev Opaque macro-specific action payload, ABI-encoded for transport.
+     * The forwarder does not decode these fields itself; the macro defines the
+     * actual EIP-712 `Action` type and computes its struct hash from these bytes.
+     */
+    struct EncodedAction {
+        bytes params;
+    }
+
+    /**
+     * @dev Top-level wire format passed to `runMacro`.
+     * Callers typically build this using `encodeParams`, but it can also be
+     * constructed manually and ABI-encoded as `bytes`.
+     */
+    struct Payload {
+        EncodedAction action;
+        Security security;
+    }
+
+    /**
+     * @dev Security parameters for a ClearMacro payload.
+     * Includes the provider identifier, validity window, and ERC-4337-style nonce.
+     */
+    struct Security {
+        string domain;
+        string provider;
+        uint256 validAfter;
+        uint256 validBefore;
+        uint256 nonce;
+    }
+
+    /**
+     * @dev Runs the macro with an EIP-712 signed payload.
+     * Reverts if the signature is invalid or if the payload fails security checks.
+     * @param  m          Target macro contract.
+     * @param  params     ABI-encoded `Payload`.
+     * @param  signer     Address which signed the payload and on whose behalf the macro runs.
+     * @param  signature  EIP-712 signature over the payload digest.
+     * @return success    True if the macro execution succeeded.
+     */
+    function runMacro(
+        IClearMacro m,
+        bytes calldata params,
+        address signer,
+        bytes calldata signature
+    ) external payable returns (bool);
+
+    /**
+     * @dev Encodes the action and security data into the payload bytes expected by `runMacro`.
+     * @param  params     ABI-encoded macro-specific parameters, opaque to the forwarder.
+     * @param  security   Security parameters (domain, provider, validAfter, validBefore, nonce).
+     * @return payload    ABI-encoded `Payload` to pass to `runMacro`.
+     */
+    function encodeParams(
+        bytes calldata params,
+        Security calldata security
+    ) external pure returns (bytes memory);
+
+    /**
+     * @dev Returns the full EIP-712 type definition string for the given macro and payload.
+     * @param  m          Target macro contract.
+     * @param  params     ABI-encoded `Payload`.
+     * @return typeDef    Full EIP-712 type definition string.
+     */
+    function getTypeDefinition(IClearMacro m, bytes calldata params)
+        external
+        view
+        returns (string memory);
+
+    /**
+     * @dev Returns the keccak256 hash of the EIP-712 type definition.
+     * @param  m          Target macro contract.
+     * @param  params     ABI-encoded `Payload`.
+     * @return typeHash   keccak256 hash of the type definition.
+     */
+    function getTypeHash(IClearMacro m, bytes calldata params)
+        external
+        view
+        returns (bytes32);
+
+    /**
+     * @dev Returns the EIP-712 struct hash of the payload.
+     * @param  m            Target macro contract.
+     * @param  params       ABI-encoded `Payload`.
+     * @return structHash   EIP-712 struct hash of the payload.
+     */
+    function getStructHash(IClearMacro m, bytes calldata params)
+        external
+        view
+        returns (bytes32);
+
+    /**
+     * @dev Returns the EIP-712 digest of the payload.
+     * This is the value which should be signed off-chain.
+     * @param  m          Target macro contract.
+     * @param  params     ABI-encoded `Payload`.
+     * @return digest     EIP-712 digest of the payload.
+     */
+    function getDigest(IClearMacro m, bytes calldata params)
+        external
+        view
+        returns (bytes32);
+
+    /**
+     * @dev Returns the next nonce for the given sender and key.
+     * Nonces follow ERC-4337-style semantics: `(uint256(key) << 64) | sequence`.
+     * @param  sender    Address for which the nonce is queried.
+     * @param  key       Nonce key.
+     * @return nonce     The next nonce for (`sender`, `key`).
+     */
+    function getNonce(address sender, uint192 key) external view returns (uint256);
+}

packages/ethereum-contracts/contracts/interfaces/utils/IUserDefinedMacro.sol → packages/ethereum-contracts/contracts/interfaces/utils/IMacro.sol

@@ -4,9 +4,9 @@ pragma solidity >=0.8.11;
 import { ISuperfluid } from "../superfluid/ISuperfluid.sol";
 
 /**
- * @dev User-defined macro used in implementations of TrustedMacros.
+ * @dev Macro used in implementations of TrustedMacros.
  */
-interface IUserDefinedMacro {
+interface IMacro {
     /**
      * @dev Build batch operations according to the parameters provided.
      * It's up to the macro contract to map the provided params (can also be empty) to any
@@ -33,7 +33,7 @@ interface IUserDefinedMacro {
     /*
      * Additional to the required interface, we recommend to implement one or multiple view functions
      * which take operation specific typed arguments and return the abi encoded bytes.
-     * As a convention, the name of those functions shall start with `params`.
+     * As a convention, the name of those functions shall start with `encode`.
      *
      * Implementing this view function(s) has several advantages:
      * - Allows to build more complex macros with internally encapsulated dispatching logic

packages/ethereum-contracts/contracts/utils/ClearMacroBase.sol

@@ -0,0 +1,111 @@
+
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import { IClearMacro } from "../interfaces/utils/IClearMacro.sol";
+import { IClearMacroForwarder } from "../interfaces/utils/IClearMacroForwarder.sol";
+import { ISuperfluid } from "../interfaces/superfluid/ISuperfluid.sol";
+
+/**
+ * @dev Abstract base for ClearMacro implementations that support multiple actions.
+ * The forwarder handles EIP-712 and signature verification; this base only provides
+ * dispatch by action code.
+ * Wire format: `abi.encode(uint8 actionCode, bytes32 lang, bytes actionParams)`.
+ * Caller must specify lang; it is passed to getActionStructHash for i18n descriptions.
+ */
+abstract contract ClearMacroBase is IClearMacro {
+
+    error UnknownActionCode(uint8 actionCode);
+    error UnsupportedLanguage();
+
+    /**
+     * @dev Per-action handler. All function pointers use the same signatures so they can be stored and dispatched.
+     */
+    struct Action {
+        uint8 actionCode;
+        bool exists;
+        function(bytes memory) internal view returns (string memory) getPrimaryTypeName;
+        function(bytes memory) internal view returns (string memory) getActionTypeDefinition;
+        function(bytes memory, bytes32) internal view returns (bytes32)
+            getActionStructHash;
+        function(ISuperfluid, bytes memory, address) internal view
+            returns (ISuperfluid.Operation[] memory)
+            buildOperations;
+        bool skipPostCheck;
+        function(ISuperfluid, bytes memory, address) internal view postCheckHandler;
+    }
+
+    mapping(uint8 => Action) internal _actionHandlers;
+
+    constructor() {
+        Action[] memory actions = _getActions();
+        for (uint256 i = 0; i < actions.length; i++) {
+            _actionHandlers[actions[i].actionCode] = actions[i];
+        }
+    }
+
+    /**
+     * @dev Override to return the list of actions supported by this macro.
+     */
+    function _getActions() internal view virtual returns (Action[] memory);
+
+    /**
+     * @dev Decode full Payload and then action code + lang + inner params. Used when the forwarder passes full params.
+     */
+    function _decodePayloadAndAction(bytes memory params)
+        internal
+        pure
+        returns (uint8 actionCode, bytes32 lang, bytes memory actionParams)
+    {
+        IClearMacroForwarder.Payload memory payload = abi.decode(params, (IClearMacroForwarder.Payload));
+        (actionCode, lang, actionParams) = abi.decode(payload.action.params, (uint8, bytes32, bytes));
+    }
+
+    /**
+     * @dev Decode action params (actionCode, lang, actionParams). Used when the
+     * forwarder passes only payload.action.params.
+     */
+    function _decodeActionParams(bytes memory params)
+        internal
+        pure
+        returns (uint8 actionCode, bytes32 lang, bytes memory actionParams)
+    {
+        (actionCode, lang, actionParams) = abi.decode(params, (uint8, bytes32, bytes));
+    }
+
+    function getPrimaryTypeName(bytes memory params) external view override returns (string memory) {
+        (uint8 actionCode, , bytes memory actionParams) = _decodePayloadAndAction(params);
+        if (!_actionHandlers[actionCode].exists) revert UnknownActionCode(actionCode);
+        return _actionHandlers[actionCode].getPrimaryTypeName(actionParams);
+    }
+
+    function getActionTypeDefinition(bytes memory params) external view override returns (string memory) {
+        (uint8 actionCode, , bytes memory actionParams) = _decodePayloadAndAction(params);
+        if (!_actionHandlers[actionCode].exists) revert UnknownActionCode(actionCode);
+        return _actionHandlers[actionCode].getActionTypeDefinition(actionParams);
+    }
+
+    function getActionStructHash(bytes memory params) external view override returns (bytes32) {
+        (uint8 actionCode, bytes32 lang, bytes memory actionParams) = _decodeActionParams(params);
+        if (!_actionHandlers[actionCode].exists) revert UnknownActionCode(actionCode);
+        return _actionHandlers[actionCode].getActionStructHash(actionParams, lang);
+    }
+
+    function buildBatchOperations(ISuperfluid host, bytes memory params, address msgSender)
+        external
+        view
+        override
+        returns (ISuperfluid.Operation[] memory)
+    {
+        (uint8 actionCode, , bytes memory actionParams) = _decodeActionParams(params);
+        if (!_actionHandlers[actionCode].exists) revert UnknownActionCode(actionCode);
+        return _actionHandlers[actionCode].buildOperations(host, actionParams, msgSender);
+    }
+
+    function postCheck(ISuperfluid host, bytes memory params, address msgSender) external view override {
+        (uint8 actionCode, , bytes memory actionParams) = _decodeActionParams(params);
+        if (_actionHandlers[actionCode].skipPostCheck) return;
+        if (!_actionHandlers[actionCode].exists) revert UnknownActionCode(actionCode);
+        _actionHandlers[actionCode].postCheckHandler(host, actionParams, msgSender);
+    }
+}