Kleros Registries

Kleros runs four production curation registries built on Curate V2. Each registry curates a specific type of data; disputed entries are resolved by Kleros Court. Together they form the core data layer used by wallets, block explorers, and token lists to display trusted metadata for contracts and tokens.

Registry	Short name	What it curates	Chain
Address Tags	ATR	Human-readable tags for contract addresses	Gnosis Chain
Tokens	-	ERC-20 token metadata (name, symbol, logo, decimals)	Gnosis Chain
Contract Domain Names	CDN	Mapping from contract address → web domain	Gnosis Chain
Address Tag Query	ATQ	Batch meta-registry of NPM packages that generate address tag data	Gnosis Chain

Address Tags Registry

The Address Tags Registry maps a (address, chain) pair to a short descriptive tag string. It is the primary source for “what is this contract?” labels shown in wallets and explorers.

Item Schema

Each registered item encodes the following columns:

Column	Type	Description
`Contract Address`	`address`	The checksummed contract address
`Contract Name`	`text`	Human-readable name (e.g. “Uniswap V3: Router 2”)
`Public Name Tag`	`text`	Short label shown to end users
`UI/Website`	`link`	Project website
`Chain ID`	`number`	Chain the address belongs to

Subgraph Access

The registry is indexed by an Envio-hosted subgraph (private deployment). Query pattern:

{
  litems(
    where: {
      registryAddress: "0xATR_REGISTRY_ADDRESS"
      status_in: [Registered, ClearingRequested]
    }
    first: 1000
  ) {
    props { label value }
  }
}

Addresses must be lowercase in where filters
Filter by chain_id in props to narrow to a specific network
Items with ClearingRequested are still active - include them in “active tags” queries

Resolution Rules

One tag per address per chain. A second registration for the same (address, chainId) pair triggers a conflict; the curated item with more stake backing is preferred.
ATQ vs ATR conflict: If an address has a tag from both the ATQ meta-registry and the Address Tags Registry, the ATR entry takes priority (it is individually curated and challenged).

Tokens Registry

The Tokens Registry curates ERC-20 token metadata. It is the source for Kleros-maintained token lists used by Uniswap, MetaMask, Ledger, and others.

Item Schema

Column	Type	Description
`Name`	`text`	Full token name (e.g. “Wrapped Ether”)
`Ticker`	`text`	Symbol (e.g. “WETH”)
`Address`	`address`	Token contract address
`Chain ID`	`number`	Chain the token is deployed on
`Decimals`	`number`	Token decimal places
`Logo`	`image`	IPFS URI for the token logo

Subgraph Access

Same Envio-hosted subgraph pattern as ATR. Query by registryAddress for the Tokens registry contract.

Token List Output

The Tokens registry generates a standard Token List JSON at build time. Consumers fetch the static file rather than querying the subgraph directly:

// Fetch the Kleros token list
const res = await fetch("https://t2crtokens.eth.limo");
const tokenList = await res.json();
// tokenList.tokens is an array of TokenInfo objects

CDN Registry (Contract Domain Names)

The CDN Registry maps contract addresses to web domains. It provides a reverse-lookup: given a contract address, find the project’s authoritative domain.

Item Schema

Column	Type	Description
`Contract Address`	`address`	The contract address
`Domain Name`	`text`	Authoritative domain (e.g. `uniswap.org`)
`Chain ID`	`number`	Chain the contract is deployed on

Subgraph Access

Same Envio-hosted subgraph pattern. CDN is smaller than ATR; the full set can typically be fetched in a single query.

Use Cases

Wallet phishing detection: check whether the domain a dApp claims matches the CDN entry for the contract being called
Block explorer “verified project” badges
Reverse DNS resolution for contract addresses

ATQ Registry (Address Tag Query)

The ATQ registry is a meta-registry: instead of curating individual address tags, it curates NPM packages that each generate batches of address tags when run. This allows large-scale tag generation (thousands of addresses) without requiring individual curation submissions per address.

ATQ is not queryable on-the-fly via subgraph. To generate address tags from ATQ, you must download and run each registered NPM package locally. There is no API that returns ATQ-derived tags for a specific address in real time.

Item Schema

Column	Type	Description
`Package Name`	`text`	NPM package name (e.g. `@kleros/address-tags-aave`)
`Version`	`text`	Semver version of the package
`Description`	`text`	Human description of what addresses this package tags
`Publisher`	`address`	Address of the package submitter

Workflow

A data provider publishes an NPM package that exports a function returning Array<{address, chainId, tag, ...}>
They submit the package to the ATQ registry via Curate
Consumers clone all registered packages, run them, and merge the results into a combined address tag dataset
The merged dataset is cached and served statically

// Conceptual: running ATQ packages to generate tags
import { getAddressTags } from "@kleros/address-tags-aave";

const tags = await getAddressTags();
// tags: [{ address: "0x...", chainId: 1, tag: "Aave V3: Pool" }, ...]

Data Model

// curate_atq_package
interface ATQPackage {
  packageName: string;     // NPM package name
  version: string;
  description: string;
  publisher: string;       // submitter address
  status: "Registered" | "RegistrationRequested" | "ClearingRequested";
  registrationTime: number;
}

Data Models

Full normalized data models for each registry:

`curate_address_tag`

interface CurateAddressTag {
  id: string;              // itemID@registryAddress
  contractAddress: string; // lowercase
  contractName: string;
  publicNameTag: string;
  website: string;
  chainId: number;
  status: CurateStatus;
  registrationTime: number;
  source: "ATR" | "ATQ";  // direct registration or via ATQ package
}

`curate_token`

interface CurateToken {
  id: string;
  name: string;
  ticker: string;
  address: string;         // lowercase
  chainId: number;
  decimals: number;
  logoURI: string;         // IPFS URI
  status: CurateStatus;
}

`curate_cdn`

interface CurateCDN {
  id: string;
  contractAddress: string; // lowercase
  domainName: string;
  chainId: number;
  status: CurateStatus;
}

`curate_atq_package`

interface CurateATQPackage {
  id: string;
  packageName: string;
  version: string;
  description: string;
  publisher: string;
  status: CurateStatus;
}

type CurateStatus =
  | "Absent"
  | "Registered"
  | "RegistrationRequested"
  | "ClearingRequested";

Consumers

The following products and services consume data from Kleros registries:

Consumer	Registry Used	How
Etherscan	ATR, CDN	Contract name tags, domain labels
Blockscout	ATR	Address name tags
MetaMask Core	ATR, Tokens	Token metadata, address labels
MetaMask Snap	ATR	Address warnings
Ledger Live	Tokens	Token display metadata
Uniswap Token List	Tokens	Default token list
Kleros Scout	ATR, Tokens, CDN	Cross-chain address and token explorer

Consumers typically fetch a pre-built static export (JSON file) rather than querying the subgraph at runtime, to avoid exposing API keys in client-side code.

Architecture

Level 1 - System Context

                    ┌─────────────────────┐
                    │   Data Providers    │
                    │  (submit items via  │
                    │   Curate UI)        │
                    └────────┬────────────┘
                             │  Curate V2 submission
                             ▼
                    ┌─────────────────────┐
                    │   Curate V2         │
                    │   Smart Contracts   │◄──── Kleros Court (disputes)
                    │   (Gnosis Chain)    │
                    └────────┬────────────┘
                             │  Events indexed
                             ▼
                    ┌─────────────────────┐
                    │   Envio Subgraph    │
                    │   (private)         │
                    └────────┬────────────┘
                             │  GraphQL queries + static exports
                             ▼
                    ┌─────────────────────┐
                    │   Consumers         │
                    │   (wallets,         │
                    │    explorers,       │
                    │    token lists)     │
                    └─────────────────────┘

Level 2 - Container View

Gnosis Chain
├── ATR Registry Contract     0x[address]
├── Tokens Registry Contract  0x[address]
├── CDN Registry Contract     0x[address]
└── ATQ Registry Contract     0x[address]

Envio Indexer
├── ATR subgraph   → /api/v1/atr/graphql
├── Tokens subgraph → /api/v1/tokens/graphql
└── CDN subgraph   → /api/v1/cdn/graphql

Static Export Pipeline (CI)
├── Reads from Envio subgraphs
├── Runs ATQ NPM packages
├── Merges and deduplicates
└── Publishes → CDN (cdn.kleros.link)

Known Limitations

Limitation	Impact	Workaround
ATQ packages are not queryable in real time	Cannot look up an address in ATQ without running all packages	Use the pre-built static export; run packages in CI
Graph API keys in frontend code	API key exposure risk if subgraph URL is hardcoded client-side	Use server-side proxy or static export; do not embed API keys in browser bundles
No address request logging	Cannot audit who queried a specific address	Use server-side proxy and log at the proxy layer
Max 1 ATR tag per `(address, chainId)` pair	Conflicts require challenge and resolution	Submit the most accurate/general tag; challenges are resolved by jurors

Adding Data to a Registry

To contribute address tags, tokens, or domain names:

Go to curate.kleros.io and select the registry
Review the registry policy (linked from the registry page)
Submit your item and pay the deposit
Wait for the challenge period to expire (typically 3–7 days)

For bulk submissions via ATQ:

Create an NPM package exporting an async function returning an array of {address, chainId, tag} objects
Publish it to NPM
Register it in the ATQ registry on Curate

Contact the Kleros team via Discord or integrations@kleros.io if you need registry contract addresses, Envio subgraph endpoints, or assistance with bulk ATQ submissions.

Getting Started

V2 Architecture

Arbitrable Apps

Products

Cross-chain

Examples

Subgraph & Data

Address Tags Registry

Item Schema

Subgraph Access

Resolution Rules

Tokens Registry

Item Schema

Subgraph Access

Token List Output

CDN Registry (Contract Domain Names)

Item Schema

Subgraph Access

Use Cases

ATQ Registry (Address Tag Query)

Item Schema

Workflow

Data Model

Data Models

`curate_address_tag`

`curate_token`

`curate_cdn`

`curate_atq_package`

Consumers

Architecture

Level 1 - System Context

Level 2 - Container View

Known Limitations

Adding Data to a Registry

​Address Tags Registry

​Item Schema

​Subgraph Access

​Resolution Rules

​Tokens Registry

​Item Schema

​Subgraph Access

​Token List Output

​CDN Registry (Contract Domain Names)

​Item Schema

​Subgraph Access

​Use Cases

​ATQ Registry (Address Tag Query)

​Item Schema

​Workflow

​Data Model

​Data Models

​curate_address_tag

​curate_token

​curate_cdn

​curate_atq_package

​Consumers

​Architecture

​Level 1 - System Context

​Level 2 - Container View

​Known Limitations

​Adding Data to a Registry

Address Tags Registry

Item Schema

Subgraph Access

Resolution Rules

Tokens Registry

Item Schema

Subgraph Access

Token List Output

CDN Registry (Contract Domain Names)

Item Schema

Subgraph Access

Use Cases

ATQ Registry (Address Tag Query)

Item Schema

Workflow

Data Model

Data Models

`curate_address_tag`

`curate_token`

`curate_cdn`

`curate_atq_package`

Consumers

Architecture

Level 1 - System Context

Level 2 - Container View

Known Limitations

Adding Data to a Registry