ERC-6865 On-chain EIP-712 signature visualization (On-Chain EIP-712 Visualization)

Draft · Signatures & auth · created 2023-04-10

Defines a standard lookup function through which a contract directly tells the caller how an EIP-712 signature request will affect their assets. Wallets can use the result to consistently display outgoing and incoming assets.

Why it is needed

Because many protocols use EIP-712 signed messages (structured signing data designed to be human readable) with different structures, it is difficult for a wallet to interpret and display every protocol's messages. As a result, most wallets today show signature requests close to raw data, leaving users unable to tell what will happen when they sign, which exposes them to security threats such as phishing. Proposers tried building off-chain SDKs for wallets to interpret each protocol, but this proved hard to scale to every protocol (scalability), risked misunderstanding a protocol's behavior and showing an incorrect screen (reliability), and risked the interpretation going stale whenever a protocol upgraded (maintenance). This standard shifts the responsibility for visualization from the wallet to the protocol itself, so the contract explains its effects directly on chain.

In depth

Calling convention

A contract implementing this proposal must include a visualizeEIP712Message function in its verifyingContract implementation. When a wallet receives an eth_signTypedData signing request, it may call this function on the contract at the chain indicated by the verifyingContract and chainId fields of the EIP-712 domain separator. If the domain separator lacks verifyingContract or chainId fields, the wallet must ignore this proposal. The input encodedMessage is an EIP-712 message encoded via abi.encode(types, params) and can be decoded with abi.decode, and domainHash is the bytes32 hash of the EIP-712 domain separator.

The Result struct return value

The function must return a Result struct. Result consists of assetsIn and assetsOut, both of type UserAssetMovement[], and a Liveness struct. assetsIn is the minimum assets the user is guaranteed to receive once the message is signed and executed, and assetsOut is the maximum assets the user gives up. Expressing the received side as a minimum and the given side as a maximum shows the user the most conservative possible effect.

Liveness: the validity period

Liveness is a struct defining the time window during which the message is valid, with uint256 fields from and to. from is the start timestamp and to is the expiration timestamp, and from must be less than to.

UserAssetMovement: representing asset movement

UserAssetMovement defines an asset with three fields: assetTokenAddress, id, and amounts. assetTokenAddress is the address of the token contract (ERC-20, ERC-721, ERC-1155), and the zero address must represent the native coin (native ETH on Ethereum). id is the NFT ID; it must be ignored for non-NFT assets, and if no token with that id exists in the NFT collection, it should be understood to mean any token within that collection. amounts is a uint256 array defining a quantity curve over time within the liveness window. amounts[0] must be the quantity at liveness.from and the last element must be the quantity at liveness.to; in most cases a single-element array is used to hold the minimum quantity of that asset.

Why on chain

Something similar could be done off-chain, but the proposers' experience building an off-chain TypeScript SDK exposed its limits. Only the developers who built the protocol can implement the visualization with the most accuracy (reliability); relying on wallets or third parties to individually parse every new protocol cannot keep up with a fast-growing ecosystem (scalability); and with so many upgradeable contracts, off-chain interpretations easily drift out of sync with actual behavior (maintainability). So they chose to put the visualization implementation in the protocol's on-chain contract.

Design rationale for domainHash and the amounts array

domainHash is needed to revert for EIP-712 implementations of a version the protocol does not support. It is used to identify which implementation (name) a protocol is using when it supports multiple EIP-712 implementations, or to reject a domainHash that belongs to a different protocol. Also, if a registry is created in the future linking this standard implementation for existing deployed contracts that can no longer be upgraded, domainHash can be used to identify the protocol. amounts is an array rather than a single uint256 so it can capture cases where quantity changes over time, as is common in auctions in NFT protocols.

Reference implementation and proposal status

An example implementation for OpenSea's Seaport NFT marketplace (SeaPortEIP712Visualizer.sol) is provided as source material. This proposal is in Draft status, an early stage where the content may still change.

Things to watch out for

Original ERC · ← ERCs