ERC-7730 Specifications

Complete technical specification for the Clear Signing metadata format.

This page contains the complete technical reference for the ERC-7730 standard. For a tooling-first overview, see Getting Started. For a step-by-step manual JSON walkthrough, see Manual Implementation.

File Structure

Context

Metadata

Display

Format Types

Path System

Example

Validation

Standard Overview

ERC-7730: Structured Data Clear Signing Format

Defines a JSON format for providing human-readable descriptions of smart contract calls and EIP-712 messages.

Created

February 7, 2024

Author

Laurent Castillo (Ledger)

Requires

EIP-155, EIP-712

View full EIP specification →

File Structure

An ERC-7730 file contains three main sections:

{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
 
  "context": {
    // Binding information: contract address, chain ID, ABI
    // OR EIP-712 schemas for structured messages
  },
 
  "metadata": {
    // Owner information, enums, constants
    // Optional but recommended for attribution
  },
 
  "display": {
    // How to format and display transaction data
    // The core of human-readable transformation
  }
}

Contract Context

"context": {
  "contract": {
    "abi": "https://api.etherscan.io/...", // or embedded ABI
    "deployments": [
      {
        "chainId": 1,
        "address": "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45"
      }
    ]
  }
}

EIP-712 Context

"context": {
  "eip712": {
    "schemas": [
      {
        "primaryType": "Order",
        "domain": {
          "name": "Protocol",
          "version": "1"
        },
        "types": {
          "Order": [...]
        }
      }
    ]
  }
}

"metadata": {
  "owner": "Protocol Name",
  "info": {
    "url": "https://protocol.com",
    "name": "Protocol Display Name",
    "signature": "https://protocol.com/.well-known/signature.json"
  },
  "enums": {
    "interestRateMode": {
      "1": "Stable",
      "2": "Variable"
    }
  },
  "constants": {
    "maxAmount": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
  }
}

"display": {
  "formats": {
    "functionName": {
      "intent": "Send tokens",
      "fields": [
        {
          "path": "parameter.path",
          "label": "Display Label",
          "format": "formatType",
          "params": {
            // Format-specific parameters
          }
        }
      ],
      "required": ["field1", "field2"],
      "excluded": ["internalField"]
    }
  }
}

Includes

Use the optional top-level includes field to reuse shared display definitions across files.

{
  "$schema": ".../erc7730-v1.schema.json",
  "includes": "common-swap.json",
  "context": { /* file-specific overrides */ }
}

When both files define the same key, the including file takes precedence. Shared helpers typically live under display.definitions.

Context Section

The context section provides binding information for the metadata.

Smart Contracts

contract.abi - Contract ABI or URL (required)

contract.deployments - Chain ID and address pairs (required)

contract.addressMatcher - URL to check if transaction matches (optional)

contract.factory - Factory deployment info (optional)

EIP-712 Messages

eip712.schemas - Message type definitions (required)

eip712.domain - Domain requirements (optional)

eip712.deployments - Verifier contracts (optional)

eip712.domainSeparator - Domain separator hex value (optional)

Metadata Section

Contains constants and mappings used by the display section.

owner - Protocol name (required)

info - Additional protocol information (optional)

info.signature - URL to signature verification (optional)

constants - Reusable constant values (optional)

enums - Value-to-label mappings (optional)

token - ERC-20 metadata (token contracts only)

Display Section

The display section defines how transaction data is presented to users.

Format Structure

Each field in the display format follows this structure:

{
  "path": "field.path",              // Path to the value in transaction data
  "label": "User-friendly label",    // Text shown to the user
  "format": "formatType",            // Format type (see below)
  "params": {                        // Format-specific parameters
    // ...
  }
}

Format Types

rawNo params

Display raw integer values

Use for: IDs, counts, generic values

amountNo params

Native currency amounts

Use for: ETH transfers, gas values

tokenAmounttokenPath or token*

Token with decimals

Use for: ERC-20 transfers, approvals

nftNamecollectionPath or collection*

NFT identifier

Use for: NFT transfers, minting

dateencoding*

Date/time display

Use for: Deadlines, expirations

durationNone

Time duration

Use for: Lock periods, timeouts

addressOrNametype

Address or ENS

Use for: Recipients, contracts

enumref to $.enums

Enumerated value

Use for: Status codes, modes

unitunit suffix

Value with unit

Use for: Percentages, rates

● Required parameter ● Optional/No parameters

Format Specifications

raw Format

Displays integers in their natural representation without conversion.

Parameters: None

Example:

{
  "path": "value",
  "label": "Amount",
  "format": "raw"
}

Output Examples:

• Input: 1000 displays as 1000
• Input: 42 displays as 42

amount Format

Displays native cryptocurrency amounts (ETH, BNB, etc.).

Parameters: None

Example:

{
  "path": "value",
  "label": "Payment",
  "format": "amount"
}

Output Examples:

• Input: 0x2c1c986f1c48000 displays as 0.19866144 ETH
• Input: 1000000000000000000 displays as 1 ETH

tokenAmount Format

Displays token amounts with proper decimals and symbols.

Parameters:

Parameter	Required	Description
`tokenPath`	Yes*	Path to token address in data
`token`	Yes*	Direct token address
`threshold`	No	Value for special message
`message`	No	Message above threshold
`nativeCurrencyAddress`	No	Addresses treated as native

*Either tokenPath or token required

Example:

{
  "path": "amount",
  "label": "Amount",
  "format": "tokenAmount",
  "params": {
    "tokenPath": "token",
    "threshold": "0xFFFFFFFF",
    "message": "Unlimited"
  }
}

Output Examples:

• Input: 1000000 (6 decimals) displays as 1 DAI
• Input: 0xFFFFFFFF with threshold displays as Unlimited

nftName Format

Displays NFT collection and token ID.

Parameters:

Parameter	Required	Description
`collectionPath`	Yes*	Path to collection address
`collection`	Yes*	Direct collection address

*Either collectionPath or collection required

Example:

{
  "path": "tokenId",
  "label": "NFT",
  "format": "nftName",
  "params": {
    "collection": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"
  }
}

Output Example:

• Token ID 1036 displays as BoredApeYachtClub #1036

date Format

Converts timestamps or block numbers to readable dates.

Parameters:

Parameter	Required	Description
`encoding`	Yes	”timestamp” or “blockheight”

Example:

{
  "path": "expiration",
  "label": "Expires",
  "format": "date",
  "params": {
    "encoding": "timestamp"
  }
}

Output Examples:

• Input: 1709191632 (timestamp) displays as 2024-02-29 08:27:12
• Input: 19332140 (block) displays as 2024-02-29 09:00:35

duration Format

Displays time duration in HH:MM:SS format.

Parameters: None

Example:

{
  "path": "lockTime",
  "label": "Lock period",
  "format": "duration"
}

Output Examples:

• Input: 3600 displays as 01:00:00 (1 hour)
• Input: 86400 displays as 24:00:00 (1 day)

addressOrName Format

Displays addresses with optional ENS resolution.

Parameters:

Parameter	Required	Description
`type`	No	Address type hint

Address Types:

wallet - User’s own address
eoa - External account
contract - Smart contract
token - Token contract
collection - NFT collection

Example:

{
  "path": "recipient",
  "label": "To",
  "format": "addressOrName",
  "params": {
    "type": "eoa"
  }
}

enum Format

Displays enumerated values using metadata mappings.

Parameters:

Parameter	Required	Description
`$ref`	Yes	Reference to enum in $.metadata.enums

Example:

{
  "path": "interestRateMode",
  "label": "Rate Type",
  "format": "enum",
  "params": {
    "$ref": "$.metadata.enums.interestRateMode"
  }
}

Output Example:

• Value 1 with enum mapping displays as Stable
• Value 2 with enum mapping displays as Variable

unit Format

Displays values with units and SI prefixes.

Parameters:

Parameter	Required	Description
`unit`	Yes	Unit suffix to append

Example:

{
  "path": "fee",
  "label": "Fee Rate",
  "format": "unit",
  "params": {
    "unit": "bps"
  }
}

Output Examples:

• Input: 100 with unit “bps” displays as 100 bps
• Input: 3600 with unit “s” displays as 3.6ks

Format Keys

Entries in display.formats accept any of the following identifiers:

"transfer(address _to,uint256 _value)": { },   // Solidity declaration
"transfer(address,uint256)": { },              // Canonical signature
"0xa9059cbb": { }                             // 4-byte selector

All three map to the same function; use the form that best fits your tooling.

Path System

Paths reference data using three root identifiers:

# Root

Current context

#.params.amount

$ Root

Metadata constants

$.constants.maxUint256

@ Root

Transaction container

@.from

Container References

Special references for transaction data:

Reference	Description	Example
@.from	Transaction sender	0x1234…5678
@.to	Target contract	0xabcd…ef01
@.value	Native currency value	0.1 ETH

Array Handling

Arrays can be accessed individually or collectively:

// Specific elements
"tokens[0]"                    // First element
"tokens[tokens.length-1]"      // Last element
 
// All elements
"tokens[]"                     // Format all array items
 
// Slice selectors (bytes/string)
"data[4:]"                     // Skip first 4 bytes
"data[:32]"                    // First 32 bytes
"data[4:36]"                   // Bytes 4-36

Array Format Example:

{
  "path": "approvals[]",
  "fields": [
    {
      "path": "amount",
      "label": "Amount",
      "format": "tokenAmount",
      "params": { "tokenPath": "token" }
    },
    {
      "path": "expiration",
      "label": "Expires",
      "format": "date",
      "params": { "encoding": "timestamp" }
    }
  ]
}

Complete Example

{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v1.schema.json",
 
  "context": {
    "$id": "Example ERC-20",
    "contract": {
      "abi": "https://api.example.io/api?module=contract&action=getabi&address=0xdac17f958d2ee523a2206206994597c13d831ec7",
      "deployments": [
        {
          "chainId": 1,
          "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
        }
      ]
    }
  },
 
  "metadata": {
    "owner": "Example",
    "info": {
      "legalName": "Example Inc.",
      "url": "https://example.io/"
    }
  },
 
  "display": {
    "formats": {
      "transfer(address _to,uint256 _value)": {
        "intent": "Send",
        "fields": [
          {
            "path": "_to",
            "label": "To",
            "format": "addressOrName"
          },
          {
            "path": "_value",
            "label": "Amount",
            "format": "tokenAmount",
            "params": {
              "tokenPath": "@.to"
            }
          }
        ],
        "required": ["_to", "_value"]
      }
    }
  }
}

Validation Checklist

Include required $schema field

Define contract or EIP-712 context

Add display formats for all user functions

Use correct path root identifiers (#, $, @)

Match format types to data types

Validate against JSON schema

Resources

JSON Schema →

Complete validation schema

Registry →

Browse existing metadata

For Wallets Design Rationale

ERC-7730 Specifications

Quick Navigation

Standard Overview

File Structure

Contract Context

EIP-712 Context

Includes

Context Section

Metadata Section

Display Section

Format Structure

Format Types

Format Specifications

raw Format

amount Format

tokenAmount Format

nftName Format

date Format

duration Format

addressOrName Format

enum Format

unit Format

Format Keys

Path System

Container References

Array Handling

Complete Example

Validation Checklist

Resources