---
title: ERC-7730 Specifications
category: reference
---

# ERC-7730 Specifications

Complete technical specification for the Clear Signing metadata format.

> **Note:** This page contains the complete technical reference for the ERC-7730 standard. For a tooling-first overview, see [Getting Started](/docs/clear-signing/for-dapps/get-started). For a step-by-step manual JSON walkthrough, see [Manual Implementation](/docs/clear-signing/for-dapps/manual-implementation).

## Quick Navigation

[File Structure](#file-structure)

[Context](#context-section)

[Metadata](#metadata-section)

[Display](#display-section)

[Format Types](#format-types)

[Path System](#path-system)

[Example](#complete-example)

[Validation](#validation-checklist)

## 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 →](https://eips.ethereum.org/EIPS/eip-7730)

## File Structure

An ERC-7730 file contains three main sections:

### Complete Structure

```json
{
  "$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
  }
}
```

### Context

### Contract Context

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

### EIP-712 Context

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

### Metadata

```json
"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

```json
"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.

```json
{
  "$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:

```json
{
  "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

raw
No params

Display raw integer values
Use for: IDs, counts, generic values

amount
No params

Native currency amounts
Use for: ETH transfers, gas values

tokenAmount
tokenPath or token\*

Token with decimals
Use for: ERC-20 transfers, approvals

nftName
collectionPath or collection\*

NFT identifier
Use for: NFT transfers, minting

date
encoding\*

Date/time display
Use for: Deadlines, expirations

duration
None

Time duration
Use for: Lock periods, timeouts

addressOrName
type

Address or ENS
Use for: Recipients, contracts

enum
ref to $.enums

Enumerated value
Use for: Status codes, modes

unit
unit suffix

Value with unit
Use for: Percentages, rates

● Required parameter
● Optional/No parameters

### Format Specifications

### raw

#### raw Format

Displays integers in their natural representation without conversion.

**Parameters:** None

**Example:**

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

**Output Examples:**

• Input: `1000` displays as `1000`\

• Input: `42` displays as `42`

### amount

#### amount Format

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

**Parameters:** None

**Example:**

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

**Output Examples:**

• Input: `0x2c1c986f1c48000` displays as `0.19866144 ETH`\

• Input: `1000000000000000000` displays as `1 ETH`

### tokenAmount

#### 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:**

```json
{
  "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

#### 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:**

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

**Output Example:**

• Token ID `1036` displays as `BoredApeYachtClub #1036`

### date

#### date Format

Converts timestamps or block numbers to readable dates.

**Parameters:**

| Parameter  | Required | Description                  |
| ---------- | -------- | ---------------------------- |
| `encoding` | Yes      | "timestamp" or "blockheight" |

**Example:**

```json
{
  "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

#### duration Format

Displays time duration in HH:MM:SS format.

**Parameters:** None

**Example:**

```json
{
  "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

#### 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:**

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

### enum

#### enum Format

Displays enumerated values using metadata mappings.

**Parameters:**

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

**Example:**

```json
{
  "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

#### unit Format

Displays values with units and SI prefixes.

**Parameters:**

| Parameter | Required | Description           |
| --------- | -------- | --------------------- |
| `unit`    | Yes      | Unit suffix to append |

**Example:**

```json
{
  "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:

```json
"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:

```javascript
// 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:**

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

## Complete Example

```json
{
  "$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

[<div className="font-semibold mb-2">JSON Schema →</div>
<div className="text-sm text-gray-400">Complete validation schema</div>](https://github.com/LedgerHQ/clear-signing-erc7730-registry/blob/master/specs/erc7730-v1.schema.json)

[<div className="font-semibold mb-2">Registry →</div>
<div className="text-sm text-gray-400">Browse existing metadata</div>](https://github.com/LedgerHQ/clear-signing-erc7730-registry)