ERC-7730 Structured Data Clear Signing Format
Draft · Signatures & auth · created 2024-02-07
A JSON format standard that specifies how to show the contents of a transaction or message on a wallet screen, in a human-readable form, before it is signed.
Why it is needed
Checking on a wallet screen exactly what you are about to sign, known as clear signing, is a core security habit in blockchain. But the data to be signed is not enough to display as is, even with structural descriptions like an ABI or EIP-712 type information. Function names are meant for developers and fail to convey the user's intent, and fields are only primitive types like integers, so there is no way to tell whether a value is a percentage or a date. Token amounts can only be displayed correctly with additional information such as decimals and symbol, and in cases like confidential tokens where the value itself is encrypted, it cannot be interpreted at all without decryption context. In the end, users end up signing data whose meaning they cannot understand, leaving them vulnerable to fake screens and phishing attacks. This standard is an open format that lets app developers write the display method once in a file, which can then be used as is by any wallet that supports it.
In depth
Scope of application and container structure
This standard covers structured data in general that has a type system and a schema. The current version supports two cases. The first is EVM smart contract calldata, where the schema is the function ABI and the container structure is an RLP-serialized EVM transaction. The second is EIP-712 messages, where the schema is extracted from the type strings held in the display.formats keys, and the message itself is signed using the EIP-712 method. The container structure is the outer structure wrapping the structured data, with its own defined serialization, hashing, and signing algorithm, which may not follow the same type system as the structured data. Because field formatting sometimes needs to reference container values, such as the sender address, recipient address, or amount, a separate reference method is defined for that.
Binding constraints in the context section
context is the set of constraints that determines which data this file may be applied to, and the wallet must verify that these constraints are satisfied before applying the format. Contract binding lists deployment addresses as chainId and address pairs in the contract.deployments array, and the target address must match one of these or be a proxy pointing to one of them. contract.factory handles contracts deployed by a factory, checking that the transaction's destination address appears in an event matching the deployEvent signature and that the emitter of that event matches the factory's deployment address. EIP-712 binding verifies a match on the key-value pairs in eip712.domain, a match on chainId and verifyingContract in eip712.deployments, or a match on the eip712.domainSeparator hash value. The contract.abi and eip712.schemas keys remain for backward compatibility and are no longer recommended.
The display.formats key and selector matching
For contracts, each key must be a human-readable ABI function fragment that includes parameter names, such as transfer(address to,uint256 value). Keys must use only canonical Solidity type names (aliases like uint are forbidden), no space is allowed after a comma, and exactly one space must separate the type and the name. The wallet strips the parameter names from the key to build a type-only signature, then matches it against the calldata selector by comparing it with the first 4 bytes of the keccak256 hash. If multiple keys produce the same type-only signature, this must be treated as an invalid descriptor. If no key matches, an unrelated format must not be applied, and a safe fallback display must be shown instead. For EIP-712, keys must be strings formed by applying encodeType to the primary type, and the type hash computed from the message must match the hash of the key.
Path reference notation
Uses a restricted JSON path notation with dot notation only, to reference values across multiple JSON documents. There are three root symbols. # refers to the structured data being signed, pointing to decoded function arguments or EIP-712 message fields. $ refers to the ERC-7730 file itself after includes are merged, referencing constants or enums in metadata or shared definitions in display.definitions. @ refers to container values, such as @.value or @.to, pointing to the transaction's own amount or destination address. Omitting the root makes the path relative to the structure being described. For variable-length types such as bytes or string, a slice selector like [0:20] or [-20:] can be appended to point to a specific byte range, where the start index is inclusive and the end index is exclusive.
Field format specification and intent interpolation
Each field specification consists of a location (path) or constant (value), a display label (label), a conversion method (format), and format-specific parameters (params). The visible key can set the display rule, which besides never, always, and optional includes ifNotIn, which shows a value only under certain conditions, and mustMatch, which checks a value and raises an error on mismatch. The encryption key specifies, for encrypted fields, scheme (the encryption method), plaintextType (the Solidity type of the decrypted value), and fallbackLabel (the text shown when decryption is not possible). interpolatedIntent is a short description string that embeds field values into a sentence using {path} syntax; the wallet must resolve the path in each expression and apply the corresponding format from the fields array to substitute the value, and must fall back to the plain intent display if any interpolation fails. Interpolation paths must only reference fields that are always visible.
Constants in the metadata section
metadata contains constants that can be trusted when the context matches. owner and contractName are the display names of the interaction target, and info is the deployment date and the official URL. The token key provides name, ticker, and decimals values only when a contract with an ERC-20 interface does not support the name(), symbol(), and decimals() calls. constants are key-value pairs that can be reused as formatter parameters. maps represent constants that vary with transaction context such as chain ID, referenced via map and keyPath, and if no matching value exists the wallet MUST treat that file as invalid for that transaction. enums define display strings for parameters that have a fixed set of values, for example converting the integers 1 and 2 into readable values like stable and variable.
File inclusion and schema versioning
The includes key points to the URL of another ERC-7730 file, and the wallet merges the two files into one, with the including file taking precedence in case of conflict. This allows sharing common interface definitions such as ERC-20 approve, while individual contracts override only parameters like threshold. The schema follows Semantic Versioning: a MAJOR bump is a change that invalidates existing valid descriptors, MINOR is an addition that broadens the valid set, and PATCH is a non-normative wording fix. The descriptor's $schema key determines which version applies, and the wallet MUST treat a descriptor with a MAJOR version it does not implement as invalid. Exact version files are immutable once published, and alias files per MAJOR line contain a copy of that line's latest release. Currently 1.0.0 is deprecated and 2.1.0 is the active version, and new integrations are recommended to target the alias file of the active line.
Proposal status
This proposal is in Draft status. Since review and revision are still ongoing, the details of the specification may change. In fact, the source text itself has undergone several revisions around the schema versioning procedure, and some keys such as contract.abi and eip712.schemas are already marked for deprecation.