ERC-7521 Generalized intents for smart contract wallets (General Intents for Smart Contract Wallets)
Draft · Accounts & wallets · created 2023-09-19
A shared entry-point contract standard that lets users sign their desired transaction intent just once and then opt into whichever new intent standards emerge later, without needing to upgrade their wallet.
Why it is needed
With intents, instead of specifying the entire transaction process, a user signs only the desired outcome, and other participants execute it on their behalf. However, the standards used to express intents keep emerging and changing. If wallets had to support each standard directly, they would need a code upgrade every time a new standard appeared, and developers of new standards would have to individually persuade wallet providers to adopt them. Without this standard, users would have to wait for their wallet to support a new intent scheme they want to use, and it would also be difficult to bundle multiple actions into one complex intent signed just once. ERC-7521 solves this by having a single shared entry-point contract handle signature verification, while delegating the actual interpretation and execution of intents to separate intent standard contracts specified by the user at signing time.
What to implement
function handleIntents (IntentSolution calldata solution) external;: Receives the solution (IntentSolution) built by the solver, verifies each intent's signature, and executes the segments in order.function validateIntent (UserIntent calldata intent) external;: Confirms that an intent's signature and data format are valid. Called locally before the solver picks up the intent.function registerIntentStandard (IIntentStandard intentStandard) external returns (bytes32);: Registers a new intent standard contract without permission and returns a unique standard ID.function verifyExecutingIntentSegmentForStandard (IIntentStandard intentStandard) external view returns (bool);: Used when a wallet needs to check whether the entry point is currently executing a segment of that standard.function validateIntentSegment (bytes calldata segmentData) external pure;: Lets an intent standard contract check whether its own segment data is correctly formatted.function executeIntentSegment (IntentSolution calldata solution, uint256 executionIndex, uint256 segmentIndex, bytes calldata context) external returns (bytes memory);: Lets an intent standard contract execute one segment. The bytes it returns are passed back as context the next time a segment of the same intent is executed.function validateUserIntent (UserIntent calldata intent, bytes32 intentHash) external;: The wallet receives the intent and its hash and verifies that the signature is actually its own. It throws an error if invalid.function generalizedIntentDelegateCall (bytes memory data) external;: The wallet delegatecalls the given call data to the intent standard contract it invoked. It must check the execution state at the entry point before the call.handleIntentsMulti(IntentSolution[] calldata solutions): Executes multiple solutions in a single transaction, saving gas for intents that touch similar storage (extension feature).getNonce(address sender, uint256 key): Lets anyone read the per-sender nonces kept in the entry point's storage (extension feature).setNonce(uint256 key, uint256 nonce): Only the currently executing intent standard can record a nonce, and only for that intent's sender (extension feature).
In depth
The UserIntent structure and segments
Users encode their intent as an ABI-encoded UserIntent struct. sender is the wallet address creating the intent, segments is a bytes array holding data for multiple intent standards, and signature is data passed to the wallet verification step. Each entry in the segments array is called an intent segment, and the first 32 bytes of each segment specify the intent standard ID that data belongs to. How the segment bytes are interpreted is entirely up to that intent standard contract. Users broadcast their UserIntent using the mempool strategy appropriate to the standard they are using.
IntentSolution and the two loops in handleIntents
The solver bundles intents into an IntentSolution. Its fields are timestamp, the evaluation time; intents, the array of UserIntents to execute; and order, the execution order across intents. The entry point's handleIntents runs two loops. In the verification loop, it checks that timestamp is within the allowed range of, or earlier than, block.timestamp, and calls validateUserIntent on each wallet. If a verification fails, at minimum that intent's execution must be skipped, and the whole transaction may also be reverted. In the execution loop, it calls executeIntentSegment on the contract indicated by each segment's standard ID, passing the full IntentSolution along with executionIndex, segmentIndex, and context.
Execution order rules and context data
Segments within a single intent always execute in the order given in the segments array. The order between intents is specified by the order array. For example, if order is [1,1,0,1], segments 1 and 2 of the second intent execute first, then segment 1 of the first intent, then segment 3 of the second intent. If no order is specified, or if order is exhausted while segments remain, the default order is used, cycling from the first intent to the last. If an intent that has already finished all its segments is referenced again, that call is skipped. The bytes returned by executeIntentSegment are remembered by the entry point and passed back as context on the next call for the same intent. This lets a standard track state changes even while other intents execute in between, such as a standard that sends out one token and then checks whether a different token was received.
Permissionless registration of intent standards
The entry point's registerIntentStandard function must allow permissionless registration of new intent standard contracts. During registration, the entry point assigns a unique standard ID to the combination of intent standard contract, entry point contract, and chain ID. Since standards are not hardcoded into wallets, users can sign intents using a newly registered standard immediately, without any extra work. Extensions are also defined that let commonly used standards be built into the code at entry point creation time, reducing external calls and saving gas.
The wallet's role: verification and delegated calls
The entry point calls validateUserIntent on each UserIntent's sender wallet, passing the full intent and a precomputed hash. The wallet must analyze whether this was actually sent by the sender and throw an error otherwise. This function is not restricted to view, but state updates such as nonce management are best done in the intent's individual segments. During execution, when the standard wants the wallet to act, it calls generalizedIntentDelegateCall, and before performing the delegatecall the wallet must use the entry point's verifyExecutingIntentSegmentForStandard to confirm two things: that the caller, msg.sender, is the standard contract the entry point is currently invoking executeIntentSegment on, and that it is itself the sender of the UserIntent currently being executed.
Solver pre-validation and simulation
Before accepting a UserIntent, the solver must make a view call to the entry point's validateIntent over RPC. This function checks whether the signature is valid and whether the segment format is correct, and if it reverts with any error the solver must reject that intent. Simulation is handled by the solver following the usual MEV workflow: it dry-runs the solution at the current block height to confirm the result is as expected, then submits the successful solution as a bundle to a block builder for inclusion in the next block. The solver also acts as the transaction sender, fronting the gas fee so the user bears no cost.
Extensions: multiple solutions, nonces, data blobs
Optional extensions are defined for gas savings. handleIntentsMulti(IntentSolution[] calldata solutions) executes multiple solutions in a single transaction, saving gas for intents that touch similar storage. getNonce(address sender, uint256 key) and setNonce(uint256 key, uint256 nonce) store nonces per sender in the entry point's storage, and writes may only be made by the intent standard currently executing, for the sender of the intent currently being executed. The data blob extension skips validation and execution for intents whose sender is address(0) or whose segments are empty, and uses that field as a channel for injecting arbitrary data. This can be used for standards that need to prove some secret value, or for intents whose behavior depends on surrounding intents.
Relationship to ERC-4337, upgrading, proposal status
This proposal does not change the consensus layer, so there are no Ethereum-wide backward compatibility concerns. If a wallet already supports ERC-4337, the validateUserIntent implementation is very similar to validateUserOp, but it requires a wallet upgrade from the user. It is recommended that wallets be built as DELEGATECALL forwarding contracts with the entry point address hardcoded, for gas efficiency and upgradeability. When a new entry point appears, the user must replace the wallet code address via a self-call and intent standards must also re-register with the new entry point. As an alternative to hardcoding, the reference implementation also shows an example of verifying the signature of an arbitrary entry point and recording it in transient storage. This proposal is currently in Draft status, and its contents may still change.
Things to watch out for
- Trust concentrated in the entry point contract: Because the entry point contract is the central point of trust for every wallet that supports ERC-7521, it requires very intensive auditing and formal verification. In exchange, what individual wallets need to verify is reduced to the signature-checking logic in validateUserIntent and the call gate in generalizedIntentDelegateCall, which lowers the overall audit burden across the ecosystem.
- Safety against arbitrary hijacking: The entry point must return true from verifyExecutingIntentSegmentForStandard only when it has successfully verified the UserIntent's signature, is currently calling executeIntentSegment on the standard specified by that intent's segments, and that intent's sender matches the msg.sender wallet requesting the check. This claim is the core target of verification.
- Need for auditing intent standard contracts: Additional intensive auditing and formal verification are also required for every intent standard contract a user chooses to interact with.