Refine ENSRainbow Docs

.changeset/fifty-spies-call.md

@@ -0,0 +1,9 @@
+---
+"ensindexer": patch
+"ensrainbow": patch
+"@docs/ensnode": patch
+"@ensnode/ensnode-sdk": patch
+"@ensnode/ensrainbow-sdk": patch
+---
+
+Refine ENSRainbow Docs

apps/ensindexer/.env.local.example

@@ -206,27 +206,17 @@ PLUGINS=subgraph,basenames,lineanames,threedns,protocol-acceleration,registrars,
 ENSRAINBOW_URL=http://localhost:3223
 
 # Pinned Label Set Configuration for requests to ENSRainbow
+# ENSRainbow label set configuration (see https://ensnode.io/ensrainbow/usage/configuration for details)
 # Required. ENSIndexer must be pinned to a specific label set ID and version to ensure deterministic
 # indexing results across time.
 #
 # For a list of available label sets and their configurations, visit:
 # https://ensnode.io/ensrainbow/usage/available-label-sets/
 #
-# LABEL_SET_ID: The label set identifier that will be used for label healing requests sent to ENSRainbow.
-# Each label set id references a collection of rainbow records.
-# This must match the label set ID configured in your ENSRainbow server.
-#
-# For full subgraph backwards compatibility, LABEL_SET_ID must be set to "subgraph"
-# and LABEL_SET_VERSION must be set to 0.
+# LABEL_SET_ID: see https://ensnode.io/ensrainbow/concepts/glossary#label-set-id.
 LABEL_SET_ID=subgraph
 
-# LABEL_SET_VERSION: A non-negative integer representing the version of the label set to request from ENSRainbow.
-# This "fully pins" ENSIndexer to a deterministic set of ENSRainbow label healing responses across time,
-# even if the connected ENSRainbow later ingests additional records into the same label set.
-# This must be less than or equal to the label set version configured in your ENSRainbow server.
-#
-# For full subgraph backwards compatibility, LABEL_SET_ID must be set to "subgraph"
-# and LABEL_SET_VERSION must be set to 0.
+# LABEL_SET_VERSION: see https://ensnode.io/ensrainbow/concepts/glossary#label-set-version.
 LABEL_SET_VERSION=0
 
 # The "primary" ENSIndexer service URL

apps/ensrainbow/.env.local.example

@@ -12,49 +12,11 @@ LOG_LEVEL=info
 # container will download on its first startup. This approach keeps the Docker
 # image small and allows data to be updated independently of the application code.
 
-# --- Database Schema Version ---
-#
-# Definition: Specifies the version of the physical database layout. It is not
-#             related to the application's API version.
-#
-# Goal: Ensures the application's code is compatible with the on-disk database
-#       format. Think of it like a migration version for a traditional database.
-#
-# How to configure: You should almost always use the latest available version
-# (e.g., `3`) to run the most recent and efficient database structure. Only use
-# an older version if you have a specific, legacy system requirement.
+# Database schema version (see https://ensnode.io/ensrainbow/usage/configuration for details)
 DB_SCHEMA_VERSION=3
 
-# --- Label Set ID ---
-#
-# Definition: An identifier that categorizes the type of ENSRainbow data (e.g., a
-#             full production set vs. a minimal test set).
-#
-# Goal: To provide different "namespaces" or categories of ENSRainbow data. This allows
-#       ENSRainbow to serve different datasets for different use cases from the
-#       same Docker image, such as a tiny dataset for testing versus a
-#       comprehensive one for production.
-#
-# How to configure: Choose the Label Set ID that matches your needs.
-# - `subgraph`:  The current production dataset. Use this for current production applications.
-# - `ens-test-env`:   A very small, lightweight dataset used for testing with the ens-test-env.
-# - `searchlight`: (Future) An extended dataset with additional label discoveries.
-# - `discovery-a`:  (Future) A dataset for dynamically discovered labels.
+# Label set ID (see https://ensnode.io/ensrainbow/concepts/glossary#label-set-id)
 LABEL_SET_ID=ens-test-env
 
-# --- Label Set Version ---
-#
-# Definition: A non-negative integer representing an incremental update to a
-#             dataset within a specific `LABEL_SET_ID`.
-#
-# Goal: To support the deterministic evolution of datasets over time. As new
-#       ENS names are discovered, they are added in new, incremental versions.
-#       This allows services like ENSIndexer to achieve reproducible results
-#       by targeting a specific, immutable version of the data.
-#
-# How to configure:
-# - To get the most up-to-date data, use the highest available version number
-#   for your chosen `LABEL_SET_ID`. Versions start at `0`.
-# - If you need to reproduce a result from an earlier point in time, you would
-#   use a specific, older version number.
+# Label set version (see https://ensnode.io/ensrainbow/concepts/glossary#label-set-version)
 LABEL_SET_VERSION=0

apps/ensrainbow/scripts/download-ensrainbow-files.sh

@@ -8,8 +8,10 @@ set -euo pipefail
 # This script downloads a specific ENSRainbow labelset file.
 #
 # The labelsets are identified by:
-#   - LABEL_SET_ID: The identifier for a label set, which is a collection of ENS labelhash-to-label mappings from a specific source.
-#   - LABEL_SET_VERSION: A non-negative integer representing the version of a label set.
+#   - LABEL_SET_ID
+#   - LABEL_SET_VERSION
+#
+# See https://ensnode.io/ensrainbow/concepts/glossary/ for details.
 #
 # This script requires these two identifiers as command-line arguments to
 # download the correct labelset file (.ensrainbow), its checksum, and a

apps/ensrainbow/scripts/download-prebuilt-database.sh

@@ -12,9 +12,11 @@ set -euo pipefail
 # saving the end-user from a slow and resource-intensive data ingestion process.
 #
 # The database is versioned using a three-part system:
-#   - DB_SCHEMA_VERSION: The physical layout/structure of the database.
-#   - LABEL_SET_ID: The identifier for a label set, which is a collection of ENS labelhash-to-label mappings from a specific source.
-#   - LABEL_SET_VERSION: A non-negative integer representing the version of a label set.
+#   - DB_SCHEMA_VERSION
+#   - LABEL_SET_ID
+#   - LABEL_SET_VERSION
+#
+# See https://ensnode.io/ensrainbow/concepts/glossary/ for details.
 #
 # This script requires these three identifiers as command-line arguments to
 # download the correct pre-built database archive (.tgz), its checksum, and a

apps/ensrainbow/src/lib/database.ts

@@ -84,6 +84,8 @@ export function isRainbowRecordKey(key: ByteArray): boolean {
 /**
  * Type representing the ENSRainbow LevelDB database.
  *
+ * For user-facing documentation, see the [Data Model documentation](/docs/ensrainbow/concepts/data-model).
+ *
  * Schema:
  * - Keys are binary encoded and represent:
  *   - For rainbow records: The raw bytes of the ENS labelHash. Always a byte length of 32.

apps/ensrainbow/src/lib/rainbow-record.ts

@@ -3,7 +3,7 @@ import { buildLabelSetVersion, type Label, type LabelSetVersion } from "@ensnode
 import { getErrorMessage } from "@/utils/error-utils";
 
 /**
- * A versioned rainbow record.
+ * A versioned [rainbow record](/docs/ensrainbow/concepts/glossary#rainbow-record).
  */
 export interface VersionedRainbowRecord {
   /** The original label string */

apps/ensrainbow/src/utils/rainbow-record.ts

@@ -3,6 +3,9 @@ import type { ByteArray } from "viem";
 import type { LabelHash } from "@ensnode/ensnode-sdk";
 import { labelHashToBytes } from "@ensnode/ensnode-sdk";
 
+/**
+ * A [rainbow record](/docs/ensrainbow/concepts/glossary#rainbow-record) interface.
+ */
 export interface RainbowRecord {
   labelHash: ByteArray;
   label: string;

docs/ensnode.io/src/content/docs/docs/reference/terminology.mdx

@@ -89,7 +89,7 @@ When rendering a **name**, one must take care to differentiate between an _unkno
 
 ### LabelHash, labelhash function
 
-In this terminology reference, we say that the **LabelHash** of a **Label** is the 32-byte hashed result of calling the **`labelhash` function** with that **Label** as input.
+In this terminology reference, we say that the **LabelHash** of a **Label** is the result of calling the **`labelhash` function** with that **Label** as input. For the complete technical definition, see the [ENSRainbow Glossary](/docs/ensrainbow/concepts/glossary#labelhash).
 
 That is, `0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc` is the **LabelHash** of `vitalik`, which is the result of calling the **`labelhash` function** like so:
 

docs/ensnode.io/src/content/docs/ensrainbow/concepts/data-model.mdx

@@ -19,6 +19,8 @@ ENSRainbow stores its rainbow table in a **LevelDB** database. The schema is int
 
 ## Versioned Rainbow Record
 
+A [rainbow record](/docs/ensrainbow/concepts/glossary#rainbow-record) with versioning information:
+
 ```ts
 interface VersionedRainbowRecord {
   label: string;          // original label
@@ -58,6 +60,7 @@ Protocol Buffers is Google's language-neutral, platform-neutral extensible mecha
 The `.ensrainbow` file format uses two main message types:
 
 ```protobuf
+// Protobuf serialization format for [rainbow records](/docs/ensrainbow/concepts/glossary#rainbow-record)
 message RainbowRecord {
   bytes labelhash = 1;    // 32-byte labelhash
   string label = 2;       // original label string
@@ -136,6 +139,6 @@ graph LR;
 
 ## Related Documentation
 
-- **[Glossary](/ensrainbow/concepts/glossary)** - Key terms like System Key, Ingestion, etc.
+- **[Glossary](/ensrainbow/concepts/glossary)** - Key terms like [System Key](/ensrainbow/concepts/glossary#system-key), [Ingestion](/ensrainbow/concepts/glossary#ingestion), etc.
 - **[Label Sets & Versioning](/ensrainbow/concepts/label-sets-and-versioning)** - Understanding the versioning system
 - **[TypeScript Interfaces](/ensrainbow/concepts/typescript-interfaces)** - Type definitions for working with the data 

docs/ensnode.io/src/content/docs/ensrainbow/concepts/glossary.mdx

@@ -9,22 +9,103 @@ keywords: [ensrainbow, glossary, terminology, definitions]
 
 This page defines the **core terminology** used throughout the ENSRainbow codebase and documentation. If you notice an unfamiliar word elsewhere in the docs, come back to this page – it is probably defined here.
 
-| Term | Definition | Example |
-|------|------------|---------|
-| **Label** | A single component of an ENS name (characters between two dots). Can contain **any** valid UTF-8 string – it may or may not be ENS-normalised. | `vitalik`, `😺`, `example.eth` has labels `example` & `eth` |
-| **Labelhash** | `keccak256` hash of the UTF-8 bytes of a label (no pre-normalisation), represented as a **0x-prefixed 64-digit lowercase hex** string (32 bytes). | `0xaf2caa…03cc` |
-| **Heal** | The act of converting a _labelhash_ back to its original _label_ via a rainbow table lookup. | `heal('0xaf2c…') → 'vitalik'` |
-| **Rainbow Record** | An entry mapping a `labelhash` ➜ `label`. Persisted as a LevelDB key (labelhash bytes) and UTF-8 value (_see Data Model_). | – |
-| **Label Set** | A logical collection of rainbow records that share a common **source** and **versioning** scheme (e.g. subgraph v0). Identified by `labelSetId` & `labelSetVersion`. | id: `subgraph`, version: `0` |
-| **Label Set ID** | String (1-50 chars) consisting of lowercase ASCII letters and hyphens that names a label set. | `subgraph`, `discovery-a` |
-| **Label Set Version** | Non-negative integer that monotonically increases when new labelhash-to-label mappings are added to a label set. Each version contains incremental additions since the previous version. Enables deterministic healing across time. | `0`, `1`, `2` |
-| **Healable Count** | Total number of labels that can currently be healed by the running server. Exposed via `/count`. | `7 892 001` |
-| **Status Code** | High-level outcome of an API call – either `success` or `error`. | – |
-| **Error Code** | HTTP-style numeric code describing the error (`400`, `404`, `500`). | – |
-| **Rainbow Table** | A pre-computed set of `labelhash → label` pairs used for healing. | – |
-| **Ingestion** | One-off process that streams a `.ensrainbow` snapshot into LevelDB. | `pnpm run ingest subgraph_0.ensrainbow` |
-| **System Key** | Special LevelDB key (length ≠ 32 bytes) storing metadata such as schema version, label set id, etc. | `0xff 0xff 0xff 0xfd` |
-| **ENS Normalization** | The ENSIP-15 canonicalisation process; ENSRainbow stores labels **as-is**, even if not normalised. | – |
+## Label
+
+A single component of an ENS name (characters between two dots). Can contain **any** valid UTF-8 string – it may or may not be ENS-normalised.
+
+**Example:** `vitalik`, `😺`, `example.eth` has labels `example` & `eth`
+
+## Labelhash
+
+`keccak256` hash of the UTF-8 bytes of a label (no pre-normalisation), represented as a **0x-prefixed 64-digit lowercase hex** string (32 bytes).
+
+**Example:** `0xaf2caa…03cc`
+
+## Heal
+
+The act of converting a _labelhash_ back to its original _label_ via a rainbow table lookup.
+
+**Example:** `heal('0xaf2c…') → 'vitalik'`
+
+## Rainbow Record
+
+An entry mapping a `labelhash` ➜ `label`. Persisted as a LevelDB key (labelhash bytes) and UTF-8 value (_see Data Model_).
+
+## Label Set
+
+A logical collection of [rainbow records](#rainbow-record) that share a common **source** and **versioning** scheme. Each label set represents a dataset snapshot that enables deterministic healing across time. Label sets are identified by a `labelSetId` and `labelSetVersion`.
+
+**Example:** id: `subgraph`, version: `0`
+
+## Label Set ID
+
+String (1-50 chars) consisting of lowercase ASCII letters and hyphens that names a label set.
+
+**Example:** `subgraph`, `discovery-a`, `searchlight`
+
+## Label Set Version
+
+Non-negative integer that monotonically increases when new labelhash-to-label mappings are added to a label set. Each version contains incremental additions since the previous version. Version `0` is always the initial dataset. Enables deterministic healing across time by allowing clients to pin to specific versions for reproducible results.
+
+**Example:** `0`, `1`, `2`
+
+## Healable Count
+
+Total number of labels that can currently be healed by the running server. Exposed via `/count`.
+
+**Example:** `7 892 001`
+
+## Status Code
+
+High-level outcome of an API call – either `success` or `error`.
+
+## Error Code
+
+HTTP-style numeric code describing the error (`400`, `404`, `500`).
+
+## Rainbow Table
+
+A pre-computed set of `labelhash → label` pairs used for healing.
+
+## Ingestion
+
+One-off process that streams a `.ensrainbow` snapshot into LevelDB.
+
+**Example:** `pnpm run ingest subgraph_0.ensrainbow`
+
+## System Key
+
+Special LevelDB key (length ≠ 32 bytes) storing metadata such as schema version, label set id, etc.
+
+**Example:** `0xff 0xff 0xff 0xfd`
+
+## ENS Normalization
+
+The ENSIP-15 canonicalisation process; ENSRainbow stores labels **as-is**, even if not normalised.
+
+## Environment Variables
+
+These environment variables are typically set in Docker containers, shell scripts, or system configuration files. See the [Configuration](/ensrainbow/usage/configuration) guide for complete setup instructions.
+
+### LABEL_SET_ID
+
+Environment variable that specifies the identifier for a [label set](#label-set). See [Label Set ID](#label-set-id) for the definition of this identifier.
+
+**Used by:** Download scripts and Docker entrypoint to fetch the correct label set
+
+### LABEL_SET_VERSION
+
+Environment variable that specifies the version of a [label set](#label-set). See [Label Set Version](#label-set-version) for the definition of this version number.
+
+**Used by:** Download scripts and Docker entrypoint to fetch the correct label set version
+
+### LOG_LEVEL
+
+Environment variable that controls the verbosity of logging output.
+
+**Format:** String  
+**Valid Values:** `fatal`, `error`, `warn`, `info`, `debug`, `trace`, `silent`  
+**Default:** `info`
 
 ## Related Documentation
 

docs/ensnode.io/src/content/docs/ensrainbow/concepts/label-sets-and-versioning.mdx

@@ -9,7 +9,7 @@ keywords: [ensrainbow, versioning, label sets, deterministic]
 
 ## 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:
+A **[label set](/ensrainbow/concepts/glossary#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](/ensrainbow/concepts/glossary#label-set-version)** so that:
 
 ### 1. Deterministic Results
 Clients that pin _version `N`_ are guaranteed to get the _exact same_ heal response today, tomorrow, and two years from now.
@@ -51,6 +51,6 @@ This flexibility ensures applications can choose between **staying current** wit
 
 ## Related Documentation
 
-- **[Glossary](/ensrainbow/concepts/glossary)** - Key terminology including version-related terms
+- **[Glossary](/ensrainbow/concepts/glossary)** - Key terminology including [label set](/ensrainbow/concepts/glossary#label-set) and [label set version](/ensrainbow/concepts/glossary#label-set-version) terms
 - **[TypeScript Interfaces](/ensrainbow/concepts/typescript-interfaces)** - Type definitions for ENSRainbow's server and client
 - **[Data Model](/ensrainbow/concepts/data-model)** - How versions are stored in the database 

docs/ensnode.io/src/content/docs/ensrainbow/concepts/performance.mdx

@@ -10,6 +10,6 @@ keywords: [ensrainbow, performance]
 |---------|-------------------|--------------|--------------|
 | `ens-test-env / 0` | 1 MB | 5 MB | < 30 s |
 | `subgraph / 0` | 3 GB | 7 GB | ~20 min |
-| `searchlight / latest` | 8 GB | 18 GB | ~50 min |
+| `searchlight / 0` | 13 GB | 29 GB | ~30 min |
 
 `*` Times measured on a 4-core CPU & NVMe SSD. 

docs/ensnode.io/src/content/docs/ensrainbow/concepts/typescript-interfaces.mdx

@@ -7,7 +7,7 @@ sidebar:
 keywords: [ensrainbow, typescript, interfaces, types]
 ---
 
-ENSRainbow's TypeScript APIs expose two companion interfaces that describe **which label sets are available (server-side) or requested (client-side)**.
+ENSRainbow's TypeScript APIs expose two companion interfaces that describe **which [label sets](/ensrainbow/concepts/glossary#label-set)** **are available (server-side) or requested (client-side)**.
 
 ## Server Label Set
 
@@ -24,7 +24,7 @@ interface EnsRainbowServerLabelSet {
 
 #### Fields
 
-- **`labelSetId`** identifies **which label set** the server is currently serving.
+- **`labelSetId`** identifies **which [label set](/ensrainbow/concepts/glossary#label-set)** the server is currently serving.
 - **`highestLabelSetVersion`** is the **highest version** available through the server for the label set id. The server will not return labels from a version _greater_ than this value (unless it ingests another incremental label set).
 
 ## Client Label Set

docs/ensnode.io/src/content/docs/ensrainbow/contributing/index.mdx

@@ -185,11 +185,11 @@ When using ENSRainbow with Docker, the following environment variables control w
   - **Goal**: Ensures compatibility between the ENSRainbow software and the structure of downloaded database files that are prebuilt for startup-time optimizations.
   - **Configuration**: It is strongly recommended to use the latest available schema version unless you have specific compatibility requirements.
 
-- **`LABEL_SET_ID`**: The identifier for a **Label Set**, which is a collection of ENS labelhash-to-label mappings from a specific source.
+- **`LABEL_SET_ID`**: See **[Label Set ID](/ensrainbow/concepts/glossary#label-set-id)**.
   - **Goal**: To enable the extensible definition of new label sets (e.g., subgraph vs. production vs. test).
   - **Configuration**: See the [Available Label Sets](/ensrainbow/usage/available-label-sets) page for a complete list of currently available label set IDs and their descriptions.
 
-- **`LABEL_SET_VERSION`**: A non-negative integer representing the version of a **Label Set**.
+- **`LABEL_SET_VERSION`**: See **[Label Set Version](/ensrainbow/concepts/glossary#label-set-version)**.
   - **Goal**: To support the deterministic evolution of datasets over time, allowing services to achieve reproducible results.
   - **Configuration**: Use the highest available version number for the most up-to-date data. Versions are sequential and incremental:
     - `0` - The initial/base version of the **Label Set**.