ERC-6900: 模块化智能合约账户

/// @dev 模块函数的打包表示。
/// 包含以下内容，左对齐：
/// 模块地址：20字节
/// 实体ID：4字节
type ModuleEntity is bytes24;

/// @dev 验证函数及其关联标志的打包表示。
/// 包含以下内容，左对齐：
/// 模块地址：20字节
/// 实体ID：4字节
/// ValidationFlags：1字节
type ValidationConfig is bytes25;

// ValidationFlags 布局：
// 0b00000___ // 未使用
// 0b_____A__ // isGlobal
// 0b______B_ // isSignatureValidation
// 0b_______C // isUserOpValidation
type ValidationFlags is uint8;

/// @dev 钩子函数及其关联标志的打包表示。
/// 包含以下内容，左对齐：
/// 模块地址：20字节
/// 实体ID：4字节
/// 标志：1字节
///
/// 钩子标志布局：
/// 0b00000___ // 未使用
/// 0b_____A__ // hasPre（仅执行）
/// 0b______B_ // hasPost（仅执行）
/// 0b_______C // 钩子类型（执行为0，验证为1）
type HookConfig is bytes25;

struct Call {
    // 账户调用的目标地址。
    address target;
    // 随调用发送的值。
    uint256 value;
    // 调用的calldata。
    bytes data;
}

interface IERC6900Account {
    event ExecutionInstalled(address indexed module, ExecutionManifest manifest);
    event ExecutionUninstalled(address indexed module, bool onUninstallSucceeded, ExecutionManifest manifest);
    event ValidationInstalled(address indexed module, uint32 indexed entityId);
    event ValidationUninstalled(address indexed module, uint32 indexed entityId, bool onUninstallSucceeded);

    /// @notice 标准执行方法。
    /// @param target 账户调用的目标地址。
    /// @param value 随调用发送的值。
    /// @param data 调用的calldata。
    /// @return 来自调用的返回数据。
    function execute(address target, uint256 value, bytes calldata data) external payable returns (bytes memory);

    /// @notice 标准 executeBatch 方法。
    /// @dev 如果目标是一个模块，调用应该revert。如果任何调用revert，则整个批处理必须revert。
    /// @param calls 调用的数组。
    /// @return 包含来自调用的返回数据的数组。
    function executeBatch(Call[] calldata calls) external payable returns (bytes[] memory);

    /// @notice 使用指定的运行时验证执行调用。
    /// @param data 要发送到账户的calldata。
    /// @param authorization 用于调用的授权数据。前24个字节是一个 ModuleEntity，它指定要使用的运行时验证，其余部分作为参数发送到运行时验证。
    function executeWithRuntimeValidation(bytes calldata data, bytes calldata authorization)
        external
        payable
        returns (bytes memory);

    /// @notice 将模块安装到模块化账户。
    /// @param module 要安装的模块。
    /// @param manifest 描述要安装的函数的清单。
    /// @param installData 账户用于处理初始执行设置的可选数据。数据编码是特定于实现的。
    function installExecution(
        address module,
        ExecutionManifest calldata manifest,
        bytes calldata installData
    ) external;

    /// @notice 从模块化账户卸载模块。
    /// @param module 要卸载的模块。
    /// @param manifest 描述要卸载的函数的清单。
    /// @param uninstallData 账户用于处理执行卸载的可选数据。数据编码是特定于实现的。
    function uninstallExecution(
        address module,
        ExecutionManifest calldata manifest,
        bytes calldata uninstallData
    ) external;

    /// @notice 在一组执行选择器上安装验证函数，并可选择将其标记为全局验证函数。
    /// @param validationConfig 要安装的验证函数，以及配置标志。
    /// @param selectors 要安装验证函数的选择器。
    /// @param installData 账户用于处理初始验证设置的可选数据。数据编码是特定于实现的。
    /// @param hooks 要安装并与验证函数关联的可选钩子。数据编码是特定于实现的。
    function installValidation(
        ValidationConfig validationConfig,
        bytes4[] calldata selectors,
        bytes calldata installData,
        bytes[] calldata hooks
    ) external;

    /// @notice 从一组执行选择器卸载验证函数。
    /// @param validationFunction 要卸载的验证函数。
    /// @param uninstallData 账户用于处理验证卸载的可选数据。数据编码是特定于实现的。
    /// @param hookUninstallData 账户用于处理钩子卸载的可选数据。数据编码是特定于实现的。
    function uninstallValidation(
        ModuleEntity validationFunction,
        bytes calldata uninstallData,
        bytes[] calldata hookUninstallData
    ) external;

    /// @notice 返回账户实现的唯一标识符。
    /// @dev 此函数必须以“vendor.account.semver”格式返回一个字符串。供应商和账户名称不得包含句点字符。
    /// @return 账户 ID。
    function accountId() external view returns (string memory);
}

/// @dev 表示与特定函数选择器关联的数据。
struct ExecutionDataView {
    // 实现此执行函数的模块。
    // 如果这是一个原生函数，则地址必须是账户的地址。
    address module;
    // 该函数是否需要运行时验证，或者是否可以由任何人调用。如果此标志设置为 true，该函数仍然可以更改状态。
    // 请注意，即使将其设置为 true，仍然需要用户操作验证，否则任何人都可以通过浪费 gas 来耗尽账户的原生代币。
    bool skipRuntimeValidation;
    // 是否可以使用全局验证函数来验证此函数。
    bool allowGlobalValidation;
    // 此函数选择器的执行钩子。
    HookConfig[] executionHooks;
}

struct ValidationDataView {
    // ValidationFlags 布局：
    // 0b00000___ // 未使用
    // 0b_____A__ // isGlobal
    // 0b______B_ // isSignatureValidation
    // 0b_______C // isUserOpValidation
    ValidationFlags validationFlags;
    // 此验证函数的验证钩子。
    HookConfig[] validationHooks;
    // 要使用此验证函数运行的执行钩子。
    HookConfig[] executionHooks;
    // 可能由此验证函数验证的选择器集。
    bytes4[] selectors;
}

interface IERC6900AccountView {
    /// @notice 获取选择器的执行数据。
    /// @dev 如果选择器是一个原生函数，则模块地址将是账户的地址。
    /// @param selector 要获取数据的选择器。
    /// @return 此选择器的执行数据。
    function getExecutionData(bytes4 selector) external view returns (ExecutionDataView memory);

    /// @notice 获取验证函数的验证数据。
    /// @dev 如果选择器是一个原生函数，则模块地址将是账户的地址。
    /// @param validationFunction 要获取数据的验证函数。
    /// @return 此验证函数的验证数据。
    function getValidationData(ModuleEntity validationFunction)
        external
        view
        returns (ValidationDataView memory);
}

interface IERC6900Module is IERC165 {
    /// @notice 初始化模块化账户的模块数据。
    /// @dev 由模块化账户在 `installExecution` 期间调用。
    /// @param data 可选的字节数组，由模块解码和使用，以设置模块化账户的初始模块数据。
    function onInstall(bytes calldata data) external;

    /// @notice 清除模块化账户的模块数据。
    /// @dev 由模块化账户在 `uninstallExecution` 期间调用。
    /// @param data 可选的字节数组，由模块解码和使用，以清除模块化账户的模块数据。
    function onUninstall(bytes calldata data) external;

    /// @notice 返回模块的唯一标识符。
    /// @dev 此函数必须以“vendor.module.semver”格式返回一个字符串。供应商和模块名称不得包含句点字符。
    /// @return 模块 ID。
    function moduleId() external view returns (string memory);
}

interface IERC6900ValidationModule is IERC6900Module {
    /// @notice 运行由 `entityId` 指定的用户操作验证函数。
    /// @param entityId 一个标识符，用于将调用路由到不同的内部实现，如果有多个内部实现。
    /// @param userOp 用户操作。
    /// @param userOpHash 用户操作哈希。
    /// @return 用于 validAfter（6个字节）、validUntil（6个字节）和 authorizer（20个字节）的打包验证数据。
    function validateUserOp(uint32 entityId, PackedUserOperation calldata userOp, bytes32 userOpHash)
        external
        returns (uint256);

    /// @notice 运行由 `entityId` 指定的运行时验证函数。
    /// @dev 为了指示整个调用应该 revert，该函数必须 revert。
    /// @param account 要验证的账户。
    /// @param entityId 一个标识符，用于将调用路由到不同的内部实现，如果有多个内部实现。
    /// @param sender 调用者地址。
    /// @param value 调用值。
    /// @param data 发送的calldata。
    /// @param authorization 供验证函数使用的其他数据。
    function validateRuntime(
        address account,
        uint32 entityId,
        address sender,
        uint256 value,
        bytes calldata data,
        bytes calldata authorization
    ) external;

    /// @notice 使用 ERC-1271 验证签名。
    /// @dev 为了指示整个调用应该 revert，该函数必须 revert。
    /// @param account 要验证的账户。
    /// @param entityId 一个标识符，用于将调用路由到不同的内部实现，如果有多个内部实现。
    /// @param sender 将 ERC-1271 请求发送到智能账户的地址。
    /// @param hash ERC-1271 请求的哈希。
    /// @param signature ERC-1271 请求的签名。
    /// @return 如果签名有效，则返回 ERC-1271 `MAGIC_VALUE`，如果无效，则返回 0xFFFFFFFF。
    function validateSignature(
        address account,
        uint32 entityId,
        address sender,
        bytes32 hash,
        bytes calldata signature
    ) external view returns (bytes4);
}

interface IERC6900ValidationHookModule is IERC6900Module {
    /// @notice 运行由 `entityId` 指定的预用户操作验证钩子。
    /// @dev 预用户操作验证钩子不得返回 0 或 1 以外的 authorizer 值。
    /// @param entityId 一个标识符，用于将调用路由到不同的内部实现，如果有多个内部实现。
    /// @param userOp 用户操作。
    /// @param userOpHash 用户操作哈希。
    /// @return 用于 validAfter（6个字节）、validUntil（6个字节）和 authorizer（20个字节）的打包验证数据。
    function preUserOpValidationHook(uint32 entityId, PackedUserOperation calldata userOp, bytes32 userOpHash)
        external
        returns (uint256);

    /// @notice 运行由 `entityId` 指定的预运行时验证钩子。
    /// @dev 为了指示整个调用应该 revert，该函数必须 revert。
    /// @param entityId 一个标识符，用于将调用路由到不同的内部实现，如果有多个内部实现。
    /// @param sender 调用者地址。
    /// @param value 调用值。
    /// @param data 发送的calldata。
    /// @param authorization 供钩子使用的其他数据。
    function preRuntimeValidationHook(
        uint32 entityId,
        address sender,
        uint256 value,
        bytes calldata data,
        bytes calldata authorization
    ) external;

    /// @notice 运行由 `entityId` 指定的预签名验证钩子。
    /// @dev 为了指示调用应该revert，该函数必须 revert。
    /// @param entityId 一个标识符，用于将调用路由到不同的内部实现，如果有多个内部实现。
    /// @param sender 调用者地址。
    /// @param hash 要签名的消息的哈希值。
    /// @param signature 消息的签名。
    function preSignatureValidationHook(uint32 entityId, address sender, bytes32 hash, bytes calldata signature)
        external
        view;
}

struct ManifestExecutionFunction {
    // 要安装的选择器。
    bytes4 executionSelector;
    // 如果为 true，则该函数不需要运行时验证，并且可以由任何人调用。
    bool skipRuntimeValidation;
    // 如果为 true，则该函数可以由全局验证函数验证。
    bool allowGlobalValidation;
}

struct ManifestExecutionHook {
    bytes4 executionSelector;
    uint32 entityId;
    bool isPreHook;
    bool isPostHook;
}

/// @dev 一个描述模块应如何在模块化账户上安装的结构。
struct ExecutionManifest {
    // 此模块中定义的要在 MSCA 上安装的执行函数。
    ManifestExecutionFunction[] executionFunctions;
    ManifestExecutionHook[] executionHooks;
    // 要添加到账户以支持自省检查的 ERC-165 接口 ID 列表。这不得包括 IERC6900Module 的接口 ID。
    bytes4[] interfaceIds;
}

interface IERC6900ExecutionModule is IERC6900Module {
    /// @notice 描述模块的内容和预期配置。
    /// @dev 此清单必须始终保持不变。
    /// @return 一个描述模块的内容和预期配置的清单。
    function executionManifest() external pure returns (ExecutionManifest memory);
}

interface IERC6900ExecutionHookModule is IERC6900Module {
    /// @notice 运行由 `entityId` 指定的预执行钩子。
    /// @dev 为了指示整个调用应该 revert，该函数必须 revert。
    /// @param entityId 一个标识符，用于将调用路由到不同的内部实现，如果有多个内部实现。
    /// @param sender 调用者地址。
    /// @param value 调用值。
    /// @param data 发送的calldata。对于与验证关联的钩子的 `executeUserOp` 调用，钩子模块应接收完整的calldata。
    /// @return 要传递给执行后钩子的上下文（如果存在）。可能会返回一个空的字节数组。
    function preExecutionHook(uint32 entityId, address sender, uint256 value, bytes calldata data)
        external
        returns (bytes memory);

    /// @notice 运行由 `entityId` 指定的执行后钩子。
    /// @dev 为了指示整个调用应该 revert，该函数必须 revert。
    /// @param entityId 一个标识符，用于将调用路由到不同的内部实现，如果有多个内部实现。
    /// @param preExecHookData 与其关联的预执行钩子返回的上下文。
    function postExecutionHook(uint32 entityId, bytes calldata preExecHookData) external;
}