ERC-7272 Ethereum Access Token
Draft · Signatures & auth · created 2023-07-03
A standard in which a signed message (EAT) issued by an off-chain service authorizes calling a specific smart contract function. It verifies on-chain who can call which function and until when.
Why it is needed
Existing methods of restricting function access in smart contracts are mostly on-chain approaches such as role-based access control or checking ownership of a specific NFT. However, these methods make it difficult to grant access that is valid only for a short time, and on-chain data must be modified every time the eligibility criteria change. When using an on-chain registry, the operator must keep the registry constantly up to date, and during any delay in updating it, someone who has lost eligibility can gain access incorrectly. Also, since most chains are public, granting permission based on sensitive personal information creates a privacy problem, because that information would need to be put on-chain to be checked. This standard solves the problem by having an off-chain service first verify the user in whatever way it wants, then issue a short-lived approval token tied to a specific account. Because the structure has the user come to request approval, the issuer can re-verify eligibility each time, and no personally identifying information remains on-chain.
In depth
Composition of an EAT and its differences from a JWT
An Ethereum Access Token (EAT) consists of a signature and an expiry time. Specifically, it is a signature value made up of uint8 v, bytes32 r, bytes32 s, and a uint256 expiry. The signature is created over the EAT payload using the EIP-712 typed structured data hashing and signing standard. The original text explains that an EAT is similar to a JSON Web Token (JWT) in that both are used for short lived authorization, but differs in that it is designed to be verified on chain and is tailored to authorizing smart contract function calls.
Signed payload: AccessToken and FunctionCall
The AccessToken struct that is signed has two fields: uint256 expiry and FunctionCall functionCall. FunctionCall consists of four fields. functionSignature is the identifier of the function being called (bytes4) and must match msg.sig. target is the address of the contract being called. caller is the current caller address and must match msg.sender. parameters is the remainder of the calldata after removing the leading parameters v, r, s, and expiry. expiry is a Unix timestamp and serves as the basis for checking whether the token has expired during verification.
What on chain verification guarantees
An EAT MUST be bound to specific parameters at issuance time, and on chain verification guarantees all of the following: that the function being called is the expected function, that the function parameters are the expected values, that the caller is the expected account, that the call is within the approved period (checking for expiry), that the target contract being called is the expected contract, and that the approval is a valid one signed by one of the expected issuers. Because these six checks are bundled together, fine grained access control becomes possible.
AccessTokenConsumer and AccessTokenVerifier
The reference implementation uses two contracts. AccessTokenConsumer is the contract that any contract wanting to gate some of its functions inherits, while AccessTokenVerifier is responsible for EAT verification. The Consumer calls the Verifier to check the integrity of the EAT. The Verifier's verify() function takes a signature and an AccessToken as input, checks that the token has not expired, recovers the signer from the reconstructed EIP-712 digest and the signature, and then verifies that the recovered signer is a valid expected signer.
Design rationale: single use, EIP-712, comparison with ZKPs
The reference implementation guarantees that EATs cannot be reused (single use), but other implementations may take different approaches. Following EIP-712 makes the token compatible with existing Ethereum infrastructure, allows access control to be built with minimal code changes, and also ensures that an issued EAT is bound to a specific chain. Compared to zero knowledge proofs (ZKPs), ZKPs come with the cost of added complexity and have many varieties with poor interoperability, whereas an EAT is closer to a signed message, making it simple to handle, and ecrecover can be used directly in any Ethereum contract. The scope of application is broad: an EAT can be attached to any function except the special functions receive and fallback.
A proposal still at the Draft stage
This proposal was created in July 2023 and is currently in Draft status. Since it is not yet a finalized standard, details of the specification may change.
Things to watch out for
- Replay attacks: An implementation MAY ensure that a consumed EAT cannot be used again. In the reference implementation, this is achieved by marking the EAT as consumed inside the _consumeAccessToken function.
- Security of the off chain issuance service: The security of functions protected by an EAT depends on the security of the off chain service that issues the EAT. If this service is compromised, a malicious actor could obtain EATs for on chain resources they should not be able to access.
- Setting the expiry time: The expiry time must be chosen carefully to balance usability and security. If it is too long, the risk of EAT misuse grows; if it is too short, the application's usability suffers.