ENSVision

ENSVision is an open, end-to-end platform for Ethereum Name Service (ENS) names. It brings registering, renewing, trading, and managing .eth names together in one self-hostable stack, built around a self-managed Seaport v1.6 orderbook.

Everything you need to run a full ENS service is here: Solidity smart contracts for bulk registration and renewal, a self-managed orderbook for listings and offers, an API layer, background workers, on-chain and off-chain indexers, a scheduling service, a Next.js client, and the tooling to run it all locally or in production.

License

This project is released under the MIT License. See LICENSE for details.

Key Features

• Register & renew ENS names in bulk via custom Solidity smart contracts.
• Self-managed orderbook for listings and offers, with on-chain settlement on a self-hosted Seaport v1.6 orderbook (no third-party marketplace dependency).
• Real-time indexing via direct database polling and Elasticsearch to keep search and analytics in sync with blockchain activity.
• Modular services: REST/TRPC API, indexer with job queue and ENS label resolution, and an on-chain event indexer share common utility packages.
• Reproducible environments: Docker Compose for local development, Kubernetes manifests, and Terraform for DigitalOcean & Cloudflare.

Repository Layout

• apps/
  • api/ – Express/TRPC API serving marketplace data and operations.
  • client/ – Next.js 15 frontend for browsing and trading ENS names.
  • evm-indexer/ – Blockchain indexer that writes ENS events to the database for processing.
  • indexer/ – BullMQ-based job processor that polls and processes blockchain events with integrated ENS label resolution.
• contracts/ – Solidity smart contracts for ENS bulk operations.
• packages/
  • Shared libraries such as database access, caching, logging, Elasticsearch integrations, and env configuration.
• infrastructure/
  • Docker Compose stack, Kubernetes manifests, Terraform definitions, and operational scripts (see the dedicated README for details).
• packages/env/ – Source of typed environment configuration shared across services.

Documentation

In-depth guides live in docs/:

• Development guide – architecture overview, local setup, and deployment.
• Multi-cloud infrastructure – provider comparison and shared deployment CLI behavior.
• AWS infrastructure – AWS Terraform, EKS deployment, ACM/ALB, and IAM.
• EVM indexer v2 migration – schema migration runbook for the on-chain indexer.

For operations and infrastructure runbooks, see docs/infrastructure/. For the smart contracts, see contracts/README.md.

Prerequisites

• Node.js ≥ 22
• Yarn 1.x (classic) – the repo uses yarn install / yarn <script> commands
• Docker Engine & Docker Compose v2 for local infrastructure
• (Optional) Kind, kubectl, doctl, and Terraform for kubernetes/Cloud deployments

Getting Started

1. Install dependencies:

   yarn install

2. Provision supporting services (Postgres, Redis, Elasticsearch, RisingWave, MinIO, etc.):

   yarn docker:up

   The compose file lives in infrastructure/docker-compose.yml. Use yarn docker:down or yarn docker:reset when needed.
3. Configure environment variables. Copy the root template and fill in the required values:

   cp .env.example .env

   See docs/development.md for the minimum set of variables needed to run locally.
4. Start the app layer:

   yarn dev

   Turborepo will run dev tasks across the workspaces (API, client, workers, etc.). Use filters for focused development, e.g. turbo run dev --filter=client.

ENS Label Resolution (Rainbow)

The indexer includes integrated ENS label resolution using the ENSRainbow database. The rainbow data is automatically downloaded and ingested on first startup in production. For local development, the data will be downloaded automatically when you start the indexer.

Configuration:

• ENSRAINBOW_LABEL_SET_ID: Label set identifier (default: eth-mainnet)
• ENSRAINBOW_LABEL_SET_VERSION: Label set version (default: 0)
• RAINBOW_DATA_DIR: LevelDB data directory (default: ./data/ensrainbow)

Note: The initial download is ~2GB and takes approximately 15-30 minutes to ingest. Subsequent startups use the cached data.

Common Tasks

• yarn build – Run production builds for every app and package via Turborepo.
• yarn lint / yarn check-types / yarn format – Quality gates shared across the workspace.
• yarn k8s ... – Multi-target Kubernetes/DigitalOcean helper CLI. See infrastructure/README.md for full command reference.
• yarn docker:up / yarn docker:down / yarn docker:reset – Manage the local data services.

Smart Contracts

The contracts/ directory contains the Solidity sources (for example BatchENSManager.sol) and deployment scripts for ENS bulk operations such as batch registrations. Use your preferred Foundry/Hardhat workflow to compile and deploy; keep ABI artifacts in sync with the consuming services.

Infrastructure & Operations

The infrastructure folder documents everything from local Docker setup to production deployments:

• Local stack: docker-compose.yml for databases, queues, search, and storage.
• Kubernetes manifests: k8s/local for Kind, k8s/prod for DigitalOcean clusters.
• Terraform: DigitalOcean managed services (Postgres, Redis, Kubernetes) plus Cloudflare R2 storage and Elastic Cloud.
• Operational CLI: yarn k8s <target> <command>.

Refer to infrastructure/README.md for detailed workflows (Kind bootstrap, production deploys, Terraform setup).

Contributing & Workflow

• Commit linting/formatting relies on the shared ESLint + Prettier setup found in packages/eslint-config.
• Shared TypeScript configs live in packages/typescript-config to keep build targets aligned.
• Use turbo run <task> filters to scope work to specific apps or packages when iterating quickly.
• Keep secrets out of the repository—environment files in packages/env should stay local or be managed via secure secret stores.

Support & Questions

For infrastructure-specific commands, migrations, or troubleshooting, start with infrastructure/README.md. Otherwise open a discussion or issue in this repository.