ERC-7988: Minimal Avatar Smart Wallet (MASW)

A smart‑wallet interface for EIP‑7702 account‑code delegation.

Abstract

Minimal Avatar Smart Wallet (MASW) is an immutable delegate‑wallet that any EOA can designate via EIP‑7702 (txType 0x04). Once designated, the wallet’s code remains active for every subsequent transaction until the owner sends a new 0x04 to clear or replace it. During each delegated call the EOA is the avatar and MASW’s code executes as the delegate at the same address, enabling atomic batched calls (EIP‑712 signed) and optional sponsor gas reimbursement in ETH or ERC‑20.

The contract offers one primary function, executeBatch, plus two plug‑in hooks: a Policy Module for pre/post guards and a Recovery Module for alternate signature validation. Replay attacks are prevented by a global metaNonce, an expiry, and a chain‑bound EIP‑712 domain separator. Standardising this seven‑parameter ABI removes wallet fragmentation while still allowing custom logic through modules.

Motivation

A single‑transaction code‑injection model (EIP‑7702) grants EOAs full implementation freedom, but unconstrained diversity would impose high coordination costs:

• Interoperability – Divergent ABIs and fee‑settlement conventions force dApps and relayers to maintain per‑wallet adapters, increasing integration complexity and failure modes.
• Economic alignment – Gas‑sponsorship relies on deterministic fee‑reimbursement paths; heterogeneity erodes relayer incentives and throttles sponsored‑transaction volume.
• Tooling precision – Indexers, debuggers, and static‑analysis frameworks achieve optimal decoding and gas estimation when targeting a single, fixed byte‑code and seven‑field call schema.
• Extensibility focus – Constraining variability to two module boundaries (Policy, Recovery) localizes complexity, allowing research and hardening efforts to concentrate on higher‑level security primitives rather than re‑engineering core wallet logic.

By standardising the immutable byte‑code, signature domain, and minimal ABI while exposing clearly defined extension hooks, MASW minimizes fragmentation and maximizes composability across the Ethereum tooling stack.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Overview of Delegation Flow

1. Deploy MASW with constructor argument _owner = EOA.
2. The owner sends an EIP‑7702 transaction (txType 0x04) referencing the contract’s byte‑code hash.
3. After that transaction the EOA acts as the avatar wallet while the MASW logic executes as the delegate wallet at the same address.

Public Interface

function executeBatch(
    address[] calldata targets,
    uint256[] calldata values,
    bytes[]   calldata calldatas,
    address token,
    uint256 fee,
    uint256 expiry,
    bytes   calldata signature
) external;

function setPolicyModule(address newModule)   external;
function setRecoveryModule(address newModule) external;

event BatchExecuted(bytes32 indexed structHash);
event ModuleChanged(bytes32 indexed kind, address oldModule, address newModule);

Transaction Type Hash

bytes32 constant BATCH_TYPEHASH = keccak256(
  "Batch(address[] targets,uint256[] values,bytes[] calldatas,address token,uint256 fee,uint256 exp,uint256 metaNonce)"
);

Storage Layout

owner and DOMAIN_SEPARATOR are immutable and occupy no storage slots.

Domain Separator Construction

DOMAIN_SEPARATOR = keccak256(
  abi.encode(
    keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"),
    keccak256("MASW"),
    keccak256("1"),
    block.chainid,   // MUST be the live chain‑ID; using 0 is disallowed
    _owner           // keeps separator stable before & after delegation
  )
);

Batch Execution (executeBatch)

Gas Sponsorship

The relayer and owner agree off‑chain on (token, fee) prior to submission.
Because the fee is part of the signed batch, a relayer cannot unilaterally raise it.
If a rival relayer broadcasts the same signed batch first, they earn the fee and the original relayer’s transaction reverts—aligning incentives naturally.
Relayers MUST confirm the avatar’s balance up‑front; insufficient funds render the transaction invalid in the mem‑pool.

Modules

Policy Module

interface IPolicyModule {
  function preCheck (address sender, bytes calldata rawData, uint256 value) external view returns (bool);
  function postCheck(address sender, bytes calldata rawData, uint256 value) external view returns (bool);
}

• A module MAY veto by reverting or by returning false.
• The value parameter represents the total ETH sent with the transaction (msg.value), allowing the policy module to validate this against the batch requirements contained in rawData.
• Aggregator designs are encouraged: forward to child policies and stop on first failure (revert or return false).

Recovery Module

interface IRecoveryModule {
  function isValidSignature(bytes32 hash, bytes calldata sig) external view returns (bytes4);
}

Must return 0x1626ba7e.

Nonce‑Race Consideration

A single global metaNonce is used. Two relayers submitting the same nonce concurrently results in one success and one revert. The expiry field (wallets typically set ≤ 30 s) makes such races low‑impact, but UIs should surface the failure.

Rationale

• Immutable logic minimizes upgrade risk; a new version requires an explicit 7702 0x04 call.
• A two‑module boundary captures common customizations without growing byte‑code.
• No hard maxTargets; advanced users can bundle many calls, while conservative users install a size‑capping Policy module.
• Domain separator binds the real chainId to mitigate cross‑chain replays.

Reference Implementation

Reference implementation can be found here MASW.sol.

Security Considerations

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

0xMostafas (@MostafaS) <0xmostafas@proton.me>, "ERC-7988: Minimal Avatar Smart Wallet (MASW) [DRAFT]," Ethereum Improvement Proposals, no. 7988, July 2025. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7988.