ENSRainbow Development and Contributions

Local Development

Get the Rainbow Tables

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

pnpm run get-legacy-data

This command will:

Download the required files (rainbow tables, checksum, and MIT license)
Automatically verify the checksum
Place the files in a convenient directory for subsequent use of the ingest command

Produce Data Directory

Run data ingestion and verify the number of unique label-labelhash pairs in the database:

pnpm run ingest

Start ENSRainbow

pnpm run serve

You can verify the service is running by checking the health endpoint or retrieving the label count:

# Health check
curl http://localhost:3223/health

# Get count of healable labels
curl http://localhost:3223/v1/labels/count

Expected count as of January 30, 2024: 133,856,894 unique label-labelhash pairs

Building the Docker Image

For instructions on building the ENSRainbow Docker image, see the Building Docker Images guide.

Building ENSRainbow Docker Images Learn how to build the ENSRainbow Docker image

Service Management

Graceful Shutdown

The service handles graceful shutdown on SIGTERM and SIGINT signals (e.g., when receiving Ctrl+C or Docker stop commands).

Database Management

If you need to start fresh with the database:

Stop any running ENSRainbow processes
Delete the LevelDB data directory (default: ’./data’)
Run the ingest command again

System Requirements

Data Ingestion Requirements (`ingest` command)

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: At least 4 GB RAM recommended

API Server Requirements (`serve` command)

Storage: 7.61 GB for the Docker image (pre-built with LevelDB database)
Memory: Minimum 1 GB RAM (4 GB recommended for optimal performance)
CPU: Minimal requirements - operates well with low CPU resources

Command Line Interface

ENSRainbow provides a command-line interface (CLI) for managing the service. You can view detailed help for any command by adding --help after the command:

Data Ingestion

pnpm run ingest [--input-file path/to/ens_names.sql.gz] [--data-dir path/to/db]

input-file: Path to the gzipped SQL dump file containing ENS rainbow tables (default: ’./ens_names.sql.gz’). Only used during data ingestion.
data-dir: Directory for the LevelDB database. If not provided, defaults to data/

Database Validation

pnpm run validate [--data-dir path/to/db] [--lite]

Validates database integrity by:

Verifying the keys for all rainbow records are valid labelhashes
Ensuring stored labels match their corresponding labelhashes
Validating the total rainbow record count
Verifying no ingestion was interrupted before successful completion

The --lite option performs a faster, less thorough validation by skipping hash verification and record count validation. It only checks that:

The ingestion was completed successfully
The schema version is correct
The precalculated count exists and can be retrieved

The process will exit with:

Code 0: Validation successful
Code 1: Validation failed or errors encountered

Database Purge

pnpm run purge [--data-dir path/to/db]

Completely removes all files from the specified data directory. This is useful when you need to start fresh with a clean database.