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

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

Original ERC · ← ERCs