How to validate and submit your descriptor

This guide shows you how to validate your descriptor, preview it on a Ledger signer, and submit it to the registry so your protocol’s transactions become Clear Signed.

Before you start, make sure you have created your descriptor with the JSON Builder or written it manually.

Validate your descriptor

Validate your file against the ERC-7730 schema before submitting, to catch errors early.

pip install erc7730

# Validate a single file
erc7730 lint your-descriptor.json
 
# Validate multiple files
erc7730 lint registry/**/eip712-*.json registry/**/calldata-*.json

erc7730 format your-descriptor.json

import Ajv from 'ajv';
import { readFileSync } from 'node:fs';
 
const schema = JSON.parse(readFileSync('./erc7730-v1.schema.json', 'utf8'));
const descriptor = JSON.parse(readFileSync('./your-descriptor.json', 'utf8'));
 
const validate = new Ajv({ allErrors: true }).compile(schema);
 
if (!validate(descriptor)) {
  console.error(validate.errors);
  process.exit(1);
}
console.log('Descriptor is valid');

Common validation errors

• Missing required fields — the file must include the context, metadata, and display sections, plus the top-level $schema field.
• Unaccounted parameters — every function parameter must appear in either fields or excluded.
• Incorrect format structure — format types must match the field’s data type. For example, tokenAmount requires either tokenPath or token in params. See the format types reference.
• Incorrect chain ID — verify each deployment’s chainId against the actual deployment. Use ChainList  to look up IDs (1 for Ethereum mainnet, 137 for Polygon, 42161 for Arbitrum).
• Invalid path expression — check the #, $, and @ roots against the path system reference.

Test the display on a signer

Before submitting, preview how your descriptor renders on a real device. The ERC-7730 Tester  injects your descriptor and displays the resulting fields against a live Ledger signer or the Speculos emulator, so you can confirm each label and value before opening a pull request.

Submit to the registry

Once your descriptor passes validation, submit it as a pull request to the registry.

git clone https://github.com/YOUR_USERNAME/clear-signing-erc7730-registry.git
cd clear-signing-erc7730-registry

mkdir -p registry/your-dapp-name
cp /path/to/your-descriptor.json registry/your-dapp-name/descriptive-name.json

If a reviewer requests changes, push to the same branch and the pull request updates automatically. Submissions are most often rejected for:

• Contract addresses that do not match the claimed protocol
• Display labels that are misleading or incomplete
• Schema violations not caught by local validation

After your pull request merges

Once merged, your descriptor becomes available in Ledger Wallet (after the next scheduled update), in all wallets that support the Clear Signing standard, and through the public registry API. Users signing transactions through your protocol then see human-readable details instead of raw hex.

Get help