chore: Update RPC configuration guidance and validation

.changeset/many-coins-wait.md

@@ -0,0 +1,7 @@
+---
+"ensadmin": patch
+"ensindexer": patch
+"@docs/ensnode": patch
+---
+
+Enhance RPC configuration guidance.

apps/ensadmin/.env.local.example

@@ -15,19 +15,23 @@ NEXT_PUBLIC_DEFAULT_ENSNODE_URLS=https://api.alpha.ensnode.io,https://api.mainne
 
 # RPC URLs
 # Required for each chain indexed by the connected ENSNode — if not provided, ENSAdmin may refuse to connect.
-# Replace these with your actual RPC URLs (e.g., from Alchemy, Infura, etc.)
+# Use private (paid) RPC endpoints from providers like drpc.org, Alchemy, QuickNode, Infura, or host your own RPC service.
+# Replace these with your actual RPC URLs
+# Note: Each of these RPC URLs (including any API keys that might be in the URL) will be publicly exposed.
+# E.g. for Ethereum Mainnet using Alchemy:
+# NEXT_PUBLIC_RPC_URL_1=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
 
-# Mainnet (Chain ID: 1)
-NEXT_PUBLIC_RPC_URL_1=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
+# Ethereum Mainnet
+NEXT_PUBLIC_RPC_URL_1=
 
-# Sepolia (Chain ID: 11155111)
-NEXT_PUBLIC_RPC_URL_11155111=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
+# Ethereum Sepolia (public testnet)
+NEXT_PUBLIC_RPC_URL_11155111=
 
-# Holesky (Chain ID: 17000)
-NEXT_PUBLIC_RPC_URL_17000=https://eth-holesky.g.alchemy.com/v2/YOUR_API_KEY
+# Ethereum Holesky (public testnet)
+NEXT_PUBLIC_RPC_URL_17000=
 
-# ens-test-env (Chain ID: 1337)
-NEXT_PUBLIC_RPC_URL_1337=http://localhost:8545
+# ens-test-env (local testnet)
+NEXT_PUBLIC_RPC_URL_1337=
 
 # Anthropic API Key
 # Used by the GQLPT client to generate GQL queries and variables

apps/ensindexer/.env.local.example

@@ -2,25 +2,113 @@
 PORT=42069
 
 # RPC configuration
+# When ENSIndexer starts up it verifies RPCs are defined for each of the chains
+# that are to be indexed based on the configured NAMESPACE and PLUGINS.
+#
+# NOTE: You must configure your own private RPC endpoints.
+# ENSIndexer makes millions of RPC requests during operation.
+# Public RPC endpoints are rate limited and will not provide acceptable performance.
+# You must use only private (paid) RPC endpoints or your own self-hosted RPC service
+# that is prepared to support millions of requests (ex: 500+ requests / second)
+#
+# Each configured RPC endpoint must be prepared to receive and quickly 
+# process millions of RPC requests. Private RPC service options include:
+# - drpc.org (paid plan) - https://drpc.org/
+# - Alchemy (paid plan) - https://www.alchemy.com/
+# - QuickNode (paid plan) - https://www.quicknode.com/
+# - Infura (paid plan) - https://infura.io/
+# - Self-hosted RPC nodes
+#
 # For the RPC URL of each chain, follow the format: RPC_URL_{chainId}={rpcUrl}
-RPC_URL_1=https://eth.drpc.org
-RPC_URL_10=https://optimism.drpc.org
-RPC_URL_8453=https://base.drpc.org
-RPC_URL_59144=https://linea.drpc.org
-
+#
+# E.g. for Ethereum Mainnet using Alchemy:
+# RPC_URL_1=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
+#
 # For the RPC rate limits of each chain, follow the format:
 # RPC_REQUEST_RATE_LIMIT_{chainId}={rateLimitInRequestsPerSecond}
 # The rate limit is the maximum number of requests per second that can be made
-# to the RPC endpoint. For public RPC endpoints, it is recommended to set
-# a rate limit to low values (i.e. below 30 rps) to avoid being rate limited.
-# For private RPC endpoints, the rate limit can be set to higher values,
-# depending on the capacity of the endpoint. For example, 500 rps.
-# If no rate limit is set for a given chainId, the DEFAULT_RPC_RATE_LIMIT value
+# to the RPC endpoint. For private (paid) RPC endpoints, the rate limit can be 
+# set to higher values, depending on the capacity of the endpoint. 
+# Default: 500 (suitable for private paid RPC services - public endpoints will fail)
+# If no rate limit is set for a given chainId, the DEFAULT_RPC_RATE_LIMIT (500)
 # will be applied.
-RPC_REQUEST_RATE_LIMIT_1=50
-RPC_REQUEST_RATE_LIMIT_10=20
-RPC_REQUEST_RATE_LIMIT_8453=20
-RPC_REQUEST_RATE_LIMIT_59144=20
+#
+# Note: Ponder dynamically adapts to the configured rate limits to avoid 429 errors and
+# maximize performance. More details at: https://ponder.sh/docs/config/chains#rpc-endpoints
+
+# === ENS Namespace: Mainnet ===
+# Ethereum Mainnet
+# - required by plugins: subgraph, reverse-resolvers
+RPC_URL_1=
+RPC_REQUEST_RATE_LIMIT_1=500
+
+# Optimism Mainnet
+# - required by plugins: threedns, reverse-resolvers
+RPC_URL_10=
+RPC_REQUEST_RATE_LIMIT_10=500
+
+# Base Mainnet
+# - required by plugins: basenames, threedns, reverse-resolvers
+RPC_URL_8453=
+RPC_REQUEST_RATE_LIMIT_8453=500
+
+# Arbitrum Mainnet
+# - required by plugins: reverse-resolvers
+RPC_URL_42161=
+RPC_REQUEST_RATE_LIMIT_42161=500
+
+# Linea Mainnet
+# - required by plugins: lineanames, reverse-resolvers
+RPC_URL_59144=
+RPC_REQUEST_RATE_LIMIT_59144=500
+
+# Scroll Mainnet
+# - required by plugins: reverse-resolvers
+RPC_URL_534352=
+RPC_REQUEST_RATE_LIMIT_534352=500
+
+# === ENS Namespace: Sepolia ===
+# Ethereum Sepolia (public testnet)
+# - required by plugins: subgraph, reverse-resolvers
+RPC_URL_11155111=
+RPC_REQUEST_RATE_LIMIT_11155111=500
+
+# Base Sepolia (public testnet)
+# - required by plugins: basenames, reverse-resolvers
+RPC_URL_84532=
+RPC_REQUEST_RATE_LIMIT_84532=500
+
+# Linea Sepolia (public testnet)
+# - required by plugins: lineanames, reverse-resolvers
+RPC_URL_59141=
+RPC_REQUEST_RATE_LIMIT_59141=500
+
+# Optimism Sepolia (public testnet)
+# - required by plugins: reverse-resolvers
+RPC_URL_11155420=
+RPC_REQUEST_RATE_LIMIT_11155420=500
+
+# Arbitrum Sepolia (public testnet)
+# - required by plugins: reverse-resolvers
+RPC_URL_421614=
+RPC_REQUEST_RATE_LIMIT_421614=500
+
+# Scroll Sepolia (public testnet)
+# - required by plugins: reverse-resolvers
+RPC_URL_534351=
+RPC_REQUEST_RATE_LIMIT_534351=500
+
+# === ENS Namespace: Holesky ===
+# Ethereum Holesky (public testnet)
+# - required by plugins: subgraph
+RPC_URL_17000=
+RPC_REQUEST_RATE_LIMIT_17000=500
+
+# === ENS Namespace: ens-test-env ===
+# ens-test-env (local testnet)
+# - required by plugins: subgraph
+RPC_URL_1337=
+RPC_REQUEST_RATE_LIMIT_1337=500
 
 # Database configuration
 # This is a namespace for the tables that the indexer will create to store indexed data.

apps/ensindexer/src/lib/lib-config.ts

@@ -1,6 +1,8 @@
 import type { RpcConfigEnvironment } from "@/config/types";
 import { ENSNamespaceIds } from "@ensnode/datasources";
 
+// Default rate limit for RPC services
+// Public (rate limited) RPC endpoints will not provide acceptable performance.
 export const DEFAULT_RPC_RATE_LIMIT = 500;
 export const DEFAULT_ENSADMIN_URL = new URL("https://admin.ensnode.io");
 export const DEFAULT_PORT = 42069;

docker-compose.yml

@@ -15,6 +15,7 @@ services:
       ENSNODE_PUBLIC_URL: http://localhost:42069
     env_file:
       # NOTE: must define apps/ensindexer/.env.local (see apps/ensindexer/.env.local.example)
+      # Copy .env.local.example to .env.local and configure all required values
       - path: ./apps/ensindexer/.env.local
         required: true
     depends_on:
@@ -43,6 +44,7 @@ services:
       ENSNODE_PUBLIC_URL: http://localhost:42069
     env_file:
       # NOTE: must define apps/ensindexer/.env.local (see apps/ensindexer/.env.local.example). Requires same env configuration as ensindexer
+      # Copy .env.local.example to .env.local and configure all required values
       - path: ./apps/ensindexer/.env.local
         required: true
     depends_on:

docs/ensnode.io/src/content/docs/ensindexer/usage/configuration.mdx

@@ -9,11 +9,17 @@ import { LinkCard } from '@astrojs/starlight/components';
 import { Code } from '@astrojs/starlight/components';
 import envExample from '@workspace/apps/ensindexer/.env.local.example?raw';
 
+:::danger[Custom RPC Configuration Required]
+**ENSIndexer requires private RPC endpoints.** Public (rate limited) RPC endpoints will not provide acceptable performance.
+
+You must configure private (paid) RPC services from providers like drpc.org, Alchemy, QuickNode, or Infura or host your own RPC service that can handle high-volume requests.
+:::
+
 :::caution[Performance Tip: ENSRainbow Server]
 Warning: Configuring ENSIndexer to use the public ENSRainbow server (`https://api.ensrainbow.io`) will significantly slow down indexing.
 For optimal indexing performance, always colocate ENSIndexer and ENSRainbow. For example, if you are running ENSIndexer locally, you should also run a local instance of ENSRainbow and set `ENSRAINBOW_URL` to your local ENSRainbow server.
 :::
-ENSIndexer's behavior can be configured through environment variables.
+ENSIndexer's behavior can be configured through environment variables. Copy `.env.local.example` to `.env.local` and configure all required values.
 
 <Code code={envExample} lang="bash" title=".env.local.example" />
 

examples/example-docker-compose/docker-compose.yml

@@ -15,6 +15,7 @@ services:
       ENSNODE_PUBLIC_URL: http://localhost:42069
     env_file:
       # NOTE: must define apps/ensindexer/.env.local (see apps/ensindexer/.env.local.example)
+      # Copy .env.local.example to .env.local and configure all required values
       - path: ./apps/ensindexer/.env.local
         required: true
     depends_on:
@@ -43,6 +44,7 @@ services:
       ENSNODE_PUBLIC_URL: http://localhost:42069
     env_file:
       # NOTE: must define apps/ensindexer/.env.local (see apps/ensindexer/.env.local.example). Requires same env configuration as ensindexer
+      # Copy .env.local.example to .env.local and configure all required values
       - path: ./apps/ensindexer/.env.local
         required: true
     depends_on: