Quick Start

ENSRainbow

ENSRainbow is an ENSNode sidecar service for healing ENS labels. It provides a simple API endpoint to heal ENS labelhashes back to their original labels.

Special thanks to The Graph for their work to generate the original ENS rainbow table used in the ENS Subgraph.

Prerequisites

• Docker installed on your system
• Node.js v20 or later (for local development)

System Requirements

• Storage:
  • At least 15 GB of free disk space:
    • 6.37 GB for the compressed rainbow tables download
    • ~7 GB for the LevelDB database after ingestion
    • Additional temporary space during build/ingestion
• Memory: Minimum 4 GB RAM recommended for optimal performance
• Docker: The final Docker image size is 7.61 GB due to the included LevelDB database

Architecture Overview

For backwards compatibility with the ENS Subgraph, the current rainbow tables (6.37 GB) are exactly the same as those published by The Graph which are MIT licensed.

• Storage Layer: Uses LevelDB as an embedded key-value store to efficiently map labelhashes to their original labels
• API Layer: Exposes a REST API endpoint that accepts labelhashes and returns the corresponding original label
• Data Ingestion: Processes a pre-computed rainbow table (SQL dump) to populate the LevelDB store
• Performance: Provides fast, constant-time lookups for known ENS labels through LevelDB’s efficient indexing

The service is designed to be run as a sidecar alongside ENSNode, helping to “heal” the labelhashes of unknown labels by finding their original labels when available.

Current Release & Future Direction

The initial release of ENSRainbow focuses on backwards compatibility with the ENS Subgraph, providing the same label healing capabilities that ENS ecosystem tools rely on today. However, we’re actively working on significant enhancements that will expand ENSRainbow’s healing capabilities far beyond what’s currently possible with the ENS Subgraph. These upcoming features will allow ENSRainbow to heal many previously unknown labels, making it an even more powerful tool for ENS data analysis and integration.

Getting the Rainbow Tables

Our copies of the original ENS rainbow tables (6.37 GB) are stored in a public bucket. To download them:

1. Download the original ENS rainbow tables and verify checksum:

# Download files
wget https://bucket.ensrainbow.io/ens_names.sql.gz
wget https://bucket.ensrainbow.io/ens_names.sql.gz.sha256sum

# Verify checksum
sha256sum -c ens_names.sql.gz.sha256sum

Quick Start with Docker

1. Build the Docker image (includes data ingestion):

# while in the monorepo root directory
docker build -t ensnode/ensrainbow -f apps/ensrainbow/Dockerfile .

2. Run the container:

docker run -d -p 3001:3001 ensnode/ensrainbow

The service will be available at http://localhost:3001.

NameHash Labs Hosted Instance

NameHash Labs operates a freely available instance of ENSRainbow for the ENS community at https://api.ensrainbow.io. This service:

• Is provided free of charge with no API key required
• Has no rate limiting
• Is maintained and monitored by the NameHash Labs team
• Runs the latest version of ENSRainbow

Using the Hosted Instance

Simply replace localhost:3001 with api.ensrainbow.io in the API examples:

# Health check
curl https://api.ensrainbow.io/health

# Heal a label
curl https://api.ensrainbow.io/v1/heal/0x[labelhash]

# Get count of healable labels
curl https://api.ensrainbow.io/v1/labels/count

While we aim for high availability, if you need guaranteed uptime or want to keep your requests private, we recommend running your own instance using the instructions above.

API Endpoints

Health Check

curl http://localhost:3001/health

Response: {"status":"ok"}

Heal Label

curl http://localhost:3001/v1/heal/0x[labelhash]

Example:

curl http://localhost:3001/v1/heal/0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc

Response:

{
  "status": "success",
  "label": "vitalik"
}

Note on returned labels: The service returns labels exactly as they appear in the source data. This means:

• Labels may or may not be ENS-normalized
• Labels can contain any valid string, including dots, null bytes, or be empty
• Clients should handle all possible string values appropriately

Error Responses:

• 400 Bad Request: When the labelhash parameter is missing or invalid

  {
    "status": "error",
    "error": "Invalid labelhash - must be a valid hex string",
    "errorCode": 400
  }

• 404 Not Found: When no label is found for the given labelhash

  {
    "status": "error",
    "error": "Label not found",
    "errorCode": 404
  }

• 500 Internal Server Error: When an unexpected error occurs

  {
    "status": "error",
    "error": "Internal server error",
    "errorCode": 500
  }

Get Count of Healable Labels

curl http://localhost:3001/v1/labels/count

Response:

{
  "status": "success",
  "count": 133856894,
  "timestamp": "2024-01-30T11:18:56Z"
}

Local Development

1. Install dependencies:

pnpm install

2. Run data ingestion (requires ens_names.sql.gz):

pnpm ingest

3. Verify database contents (optional):

# Count and verify the number of labels in the database
pnpm count-keys

This will:

• Read and display the existing count from the database (if present)
• Count all unique labels in the database
• Store the count for future reference
• Expected count as of January 30, 2024: 133,856,894 unique label-labelhash pairs

4. Start the service:

pnpm start

Note: The steps above use the development mode which runs TypeScript files directly. For production builds:

# Build TypeScript
pnpm build

# Run with compiled JavaScript
pnpm start:prod
pnpm ingest:prod
pnpm count-keys:prod

Environment Variables

Server Variables

• PORT: Server port (default: 3001)
• DATA_DIR: Directory for LevelDB data (default: ’./data’)

Data Ingestion Variables

• INPUT_FILE: Path to the gzipped SQL dump file containing ENS rainbow tables (default: ’./ens_names.sql.gz’). Only used during data ingestion.

License

Licensed under the MIT License, Copyright © 2023-present NameHash Labs.

See LICENSE for more information.