Skip to content
ENSNode

Label Sets & Versioning

Why Label Sets & Versions?

Section titled “Why Label Sets & Versions?”

A label set is analogous to a dataset snapshot. Every time the upstream data (e.g. an on-chain subgraph export) changes, we mint a new label set version so that:

1. Deterministic Results

Section titled “1. Deterministic Results”

Clients that pin version N are guaranteed to get the exact same heal response today, tomorrow, and two years from now.

2. Decentralized Ecosystem

Section titled “2. Decentralized Ecosystem”

Anyone can create and publish their own labelsets, opening ENSRainbow as a solution for the wider ENS ecosystem. Distinct labelSetId values enable diverse data sources, community-driven curation, and maintenance of labelhash-to-label mappings.

3. Extensibility Across Time

Section titled “3. Extensibility Across Time”

Label sets can grow organically as new labelhash-to-label mappings are discovered. Each new version incrementally adds fresh data without invalidating previous versions, ensuring applications can evolve their data coverage while maintaining backward compatibility.

Version Management

Section titled “Version Management”

Label Set IDs

Section titled “Label Set IDs”
  • String (1-50 chars) consisting of lowercase ASCII letters and hyphens
  • Examples: subgraph, discovery-a, ens-test-env
  • Each ID represents a different data source or curation strategy

Label Set Versions

Section titled “Label Set Versions”
  • Non-negative integers that increase monotonically: 0, 1, 2, etc.
  • Version 0 is always the initial dataset for a given label set ID
  • Each new version contains only the new labelhash-to-label mappings added since the previous version

File Naming Convention

Section titled “File Naming Convention”
subgraph_0.ensrainbow     # labelSetId = "subgraph", version = 0
subgraph_1.ensrainbow     # next version with incremental labelhash-to-label mappings added
discovery-a_0.ensrainbow  # different dataset, initial version

Client Behavior

Section titled “Client Behavior”

When constructing an ENSRainbow client, you can specify versioning preferences:

  1. No constraints → Always use the latest available version
  2. Pin to label set ID → Use a specific dataset but stay current
  3. Pin to exact version → Lock to a specific snapshot for deterministic results

This flexibility ensures applications can choose between staying current with the latest data or maintaining consistency for reproducible results.

Section titled “Related Documentation”