Skip to content

Commit 0119363

Browse files
MostafaSMostafaS
authored
Add ERC: Minimal Avatar Smart Wallet (MASW)
Merged by EIP-Bot.
1 parent d46503e commit 0119363

File tree

2 files changed

+604
-0
lines changed

2 files changed

+604
-0
lines changed

‎ERCS/erc-7988.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
eip: 7988
3+
title: Minimal Avatar Smart Wallet (MASW)
4+
description: A smart‑wallet interface for EIP‑7702 account‑code delegation.
5+
author: 0xMostafas (@MostafaS) <[email protected]>
6+
discussions-to: https://ethereum-magicians.org/t/erc-tbd-minimal-avatar-smart-wallet-masw-delegate-wallet-for-eip-7702/24761
7+
status: Draft
8+
type: Standards Track
9+
category: ERC
10+
created: 2025-07-08
11+
requires: 7702
12+
---
13+
14+
## Abstract
15+
16+
Minimal Avatar Smart Wallet (MASW) is an immutable delegate‑wallet that any EOA can designate via [EIP‑7702](./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](./eip-712) signed) and optional sponsor gas reimbursement in ETH or [ERC‑20](./eip-20).
17+
18+
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.
19+
20+
## Motivation
21+
22+
A single‑transaction code‑injection model (EIP‑7702) grants EOAs full implementation freedom, but unconstrained diversity would impose high coordination costs:
23+
24+
- **Interoperability** – Divergent ABIs and fee‑settlement conventions force dApps and relayers to maintain per‑wallet adapters, increasing integration complexity and failure modes.
25+
- **Economic alignment** – Gas‑sponsorship relies on deterministic fee‑reimbursement paths; heterogeneity erodes relayer incentives and throttles sponsored‑transaction volume.
26+
- **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.
27+
- **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.
28+
29+
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.
30+
31+
## Specification
32+
33+
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.
34+
35+
### Overview of Delegation Flow
36+
37+
1. **Deploy** `MASW` with constructor argument `_owner = EOA`.
38+
2. The owner sends an EIP‑7702 transaction (txType `0x04`) referencing the contract's byte‑code hash.
39+
3. After that transaction the EOA acts as the **avatar wallet** while the MASW logic executes as the **delegate wallet** at the _same_ address.
40+
41+
### Public Interface
42+
43+
```solidity
44+
function executeBatch(
45+
address[] calldata targets,
46+
uint256[] calldata values,
47+
bytes[] calldata calldatas,
48+
address token,
49+
uint256 fee,
50+
uint256 expiry,
51+
bytes calldata signature
52+
) external;
53+
54+
function setPolicyModule(address newModule) external;
55+
function setRecoveryModule(address newModule) external;
56+
57+
event BatchExecuted(bytes32 indexed structHash);
58+
event ModuleChanged(bytes32 indexed kind, address oldModule, address newModule);
59+
```
60+
61+
### Transaction Type Hash
62+
63+
```solidity
64+
bytes32 constant BATCH_TYPEHASH = keccak256(
65+
"Batch(address[] targets,uint256[] values,bytes[] calldatas,address token,uint256 fee,uint256 exp,uint256 metaNonce)"
66+
);
67+
```
68+
69+
### Storage Layout
70+
71+
| Slot | Name | Type | Description |
72+
| ---: | ---------------- | ------- | ---------------------------------------- |
73+
| 0 | `metaNonce` | uint256 | Monotonically increasing meta‑nonce |
74+
| 1 | `_entered` | uint256 | Re‑entrancy guard flag |
75+
| 2 | `policyModule` | address | Optional `IPolicyModule` (zero = none) |
76+
| 3 | `recoveryModule` | address | Optional `IRecoveryModule` (zero = none) |
77+
78+
`owner` and `DOMAIN_SEPARATOR` are `immutable` and occupy no storage slots.
79+
80+
### Domain Separator Construction
81+
82+
```solidity
83+
DOMAIN_SEPARATOR = keccak256(
84+
abi.encode(
85+
keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"),
86+
keccak256("MASW"),
87+
keccak256("1"),
88+
block.chainid, // MUST be the live chain‑ID; using 0 is disallowed
89+
_owner // keeps separator stable before & after delegation
90+
)
91+
);
92+
```
93+
94+
### Batch Execution (`executeBatch`)
95+
96+
| Stage | Behaviour |
97+
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98+
| **Validation** | ‑ `targets.length == values.length == calldatas.length > 0`<br>‑ `block.timestamp ≤ expiry`<br>‑ `metaNonce` matches then increments<br>‑ `EIP712` digest recovers `owner` **or** is approved by `recoveryModule` |
99+
| **Policy pre‑hook** | If `policyModule != address(0)`, `preCheck` **MUST** return `true`; a revert or `false` vetoes the batch |
100+
| **Calls** | For each index _i_: `targets[i].call{value:values[i]}(calldatas[i])`; revert on first failure |
101+
| **Policy post‑hook** | Same semantics as pre‑hook |
102+
| **Fee reimbursement** | If `fee > 0`: native transfer (`token == address(0)`) or `ERC20` `transfer` with OpenZeppelin‑style return‑value check <!-- TODO --> |
103+
| **Emit** | `BatchExecuted(structHash)` |
104+
105+
#### Gas Sponsorship
106+
107+
The relayer and owner agree off‑chain on `(token, fee)` prior to submission.
108+
Because the fee is part of the signed batch, a relayer cannot unilaterally raise it.
109+
If a rival relayer broadcasts the same signed batch first, they earn the fee and the original relayer's transaction reverts—aligning incentives naturally.
110+
Relayers **MUST** confirm the avatar's balance up‑front; insufficient funds render the transaction invalid in the mem‑pool.
111+
112+
### Modules
113+
114+
#### Policy Module
115+
116+
```solidity
117+
interface IPolicyModule {
118+
function preCheck (address sender, bytes calldata rawData, uint256 value) external view returns (bool);
119+
function postCheck(address sender, bytes calldata rawData, uint256 value) external view returns (bool);
120+
}
121+
```
122+
123+
- A module **MAY** veto by reverting _or_ by returning `false`.
124+
- 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`.
125+
- Aggregator designs are encouraged: forward to child policies and stop on first failure (revert or return `false`).
126+
127+
#### Recovery Module
128+
129+
```solidity
130+
interface IRecoveryModule {
131+
function isValidSignature(bytes32 hash, bytes calldata sig) external view returns (bytes4);
132+
}
133+
```
134+
135+
Must return `0x1626ba7e`.
136+
137+
### Nonce‑Race Consideration
138+
139+
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.
140+
141+
## Rationale
142+
143+
- **Immutable logic** minimizes upgrade risk; a new version requires an explicit 7702 `0x04` call.
144+
- A **two‑module** boundary captures common customizations without growing byte‑code.
145+
- No hard `maxTargets`; advanced users can bundle many calls, while conservative users install a size‑capping Policy module.
146+
- Domain separator binds the real `chainId` to mitigate cross‑chain replays.
147+
148+
## Reference Implementation
149+
150+
Reference implementation can be found here [`MASW.sol`](../assets/eip-7988/MASW.sol).
151+
152+
## Security Considerations
153+
154+
| Threat | Mitigation |
155+
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
156+
| Same‑chain replay | Global `metaNonce` |
157+
| Cross‑chain replay | Chain‑bound domain separator |
158+
| Fee grief / over‑charge | Fee is part of signed data; front‑running risk sits with relayer |
159+
| Batch gas grief | Optional Policy can reject oversized batches |
160+
| `ERC20` non‑standard returns | OpenZeppelin `SafeERC20` transfer check |
161+
| Re‑entrancy | `nonReentrant` guard; state mutated only before external calls (nonce++) and after (fee transfer) |
162+
| Malicious Module | Core logic immutable; swapping modules needs an owner‑signed tx |
163+
164+
## Copyright
165+
166+
Copyright and related rights waived via [CC0](../LICENSE.md).

0 commit comments

Comments
 (0)