diff --git a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts index b6436c6e00..b164f78a55 100644 --- a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts +++ b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/self-host.ts @@ -15,5 +15,9 @@ export const selfHostSidebarTopic = { label: "Terraform", link: "/docs/self-host/terraform", }, + { + label: "Scalability", + link: "/docs/self-host/scalability", + }, ], }; diff --git a/docs/ensnode.io/public/ensnode-scalability.svg b/docs/ensnode.io/public/ensnode-scalability.svg new file mode 100644 index 0000000000..58ce088f1c --- /dev/null +++ b/docs/ensnode.io/public/ensnode-scalability.svg @@ -0,0 +1,4 @@ + + + +

ENSIndexer layer

No horizontal scalability needed

ENSRainbow
heals unknown labels
writes
ENSIndexer
async replication
ENSDb
(Single Writer Target)

Horizontally scale
ENSDb

ENSDb Replica 1
ENSDb Replica 2
ENSDb Replica M
reads
Load balancer
(Single Reader Target)

Horizontally scale
ENSApi

ENSApi Instance 1
ENSApi Instance 2
reads
ENSApi Instance N
reads
Load balancer
(Single Reader Target)
Web Client 1
Web Client 2
Web Client X
Web Client 3
reads
Web Client 4
 \ No newline at end of file diff --git a/docs/ensnode.io/src/components/molecules/HostedInstanceSdkVersionWarning.astro b/docs/ensnode.io/src/components/molecules/HostedInstanceSdkVersionWarning.astro new file mode 100644 index 0000000000..f05ea3fb3e --- /dev/null +++ b/docs/ensnode.io/src/components/molecules/HostedInstanceSdkVersionWarning.astro @@ -0,0 +1,40 @@ +--- +import { Aside } from "@astrojs/starlight/components"; + +interface Props { + /** + * Which SDK(s) the warning is for. + * - "enssdk": only enssdk + * - "enskit": both enskit and enssdk (enskit depends on enssdk) + * - "both": mention both enssdk and enskit, show both install commands + */ + for?: "enssdk" | "enskit" | "both"; +} + +const { for: target = "enssdk" } = Astro.props; + +const isEnskit = target === "enskit"; +const isBoth = target === "both"; + +const sdkList = isEnskit + ? "enskit@1.13.1 and enssdk@1.13.1" + : isBoth + ? "enssdk@1.13.1 (and enskit@1.13.1 when using React)" + : "enssdk@1.13.1"; +--- + + diff --git a/docs/ensnode.io/src/components/molecules/IntegrateHostedEnsNodeTip.astro b/docs/ensnode.io/src/components/molecules/IntegrateHostedEnsNodeTip.astro index 4369656c3d..eaa37598be 100644 --- a/docs/ensnode.io/src/components/molecules/IntegrateHostedEnsNodeTip.astro +++ b/docs/ensnode.io/src/components/molecules/IntegrateHostedEnsNodeTip.astro @@ -1,13 +1,25 @@ --- import { Aside, LinkCard } from "@astrojs/starlight/components"; +import HostedInstanceSdkVersionWarning from "./HostedInstanceSdkVersionWarning.astro"; + +interface Props { + /** + * Which SDK the warning should target. Passed through to HostedInstanceSdkVersionWarning. + * - "enssdk": enssdk-only warning + * - "enskit": both enskit and enssdk warning + * - "both": mention both enssdk and enskit, show both install commands (default) + */ + for?: "enssdk" | "enskit" | "both"; +} + +const { for: target = "both" } = Astro.props; --- + - - diff --git a/docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx b/docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx index 4cdd5bb7d9..99e6fbbf5a 100644 --- a/docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx +++ b/docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx @@ -7,6 +7,7 @@ sidebar: import { LinkCard } from "@astrojs/starlight/components"; import HostedEnsNodeInstances from "@components/molecules/HostedEnsNodeInstances.astro"; +import HostedInstanceSdkVersionWarning from "@components/molecules/HostedInstanceSdkVersionWarning.astro"; ## Hosted Instances @@ -14,6 +15,8 @@ NameHash Labs provides freely available hosted instances for ENS developers look These instances are provided free of charge with no API key required, have no rate limiting, and are maintained and monitored by the NameHash Labs team. + + ### Available instance configurations Each ENSNode hosted instance is configured for a specific ENS **namespace** and activated ENSNode **plugins**. The ENS namespace identifies which ENS protocol deployment will be indexed by ENSNode (ex: mainnet or sepolia). The activated plugins determine the specific indexed data model ENSIndexer will produce in ENSDb and therefore which APIs ENSApi will make available to query. diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx index 9e2be956d5..f683f81417 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx @@ -7,6 +7,7 @@ sidebar: --- import { LinkCard, CardGrid, Aside } from "@astrojs/starlight/components"; +import HostedInstanceSdkVersionWarning from "@components/molecules/HostedInstanceSdkVersionWarning.astro"; import OmnigraphAPIExample from "@components/organisms/OmnigraphAPIExample.astro"; ## What is ENSv2? @@ -44,6 +45,9 @@ Here's a summary of some popular integration strategies: With `enskit`, leverage ENSNode and the Omnigraph to power your React components using `useOmnigraphQuery`. `enskit` comes with built-in type-safety, Omnigraph-specific cache directives, easy infinite pagination, and much much more. + + + ```tsx // this is fully typechecked and supports editor autocomplete! const DomainFragment = graphql(` @@ -137,6 +141,9 @@ export function RenderDomainAndSubdomains({ name }: { name: InterpretedName }) { With `enssdk`, leverage ENSNode and the Omnigraph from any JavaScript runtime to power your frontend or backend apps. `enssdk` comes with built-in type-safety and editor autocomplete for Omnigraph queries. + + + ```ts // create and extend an EnsNodeClient with Omnigraph API support const client = createEnsNodeClient({ url: process.env.ENSNODE_URL! }).extend(omnigraph); diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enskit/example.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enskit/example.mdx index 44f0746fd3..a1d681abe1 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enskit/example.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enskit/example.mdx @@ -8,11 +8,14 @@ sidebar: --- import EnskitExampleInteractivePlayground from "@components/organisms/EnskitExampleInteractivePlayground"; +import HostedInstanceSdkVersionWarning from "@components/molecules/HostedInstanceSdkVersionWarning.astro"; This playground loads the same source as [`enskit-react-example`](https://github.com/namehash/ensnode/tree/main/examples/enskit-react-example): a Vite + React app with routing, domain and account browsers, registry cache, and search — powered by [`enskit`](/docs/integrate/integration-options/enskit) and the [ENS Omnigraph API](/docs/integrate/omnigraph). -:::note[First load may take a few minutes] -The embedded StackBlitz editor runs entirely in your browser. Downloading and installing all npm packages may take a few minutes. Watch the install progress in the terminal of the StackBlitz editor. + + +:::note[First load may take a moment] +The editor runs entirely in your browser. Downloading of **enskit**, **enssdk** and their heavy dependencies may take 30-60 seconds. ::: After the project is ready, edit the app and run **`npm start`** in the terminal to restart the Vite dev server. Use the **preview** pane to interact with the running UI. diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enskit/index.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enskit/index.mdx index da1f58b86f..251b972037 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enskit/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enskit/index.mdx @@ -10,7 +10,7 @@ import IntegrateHostedEnsNodeTip from '@components/molecules/IntegrateHostedEnsN This guide walks you from an empty directory to a working React component that renders an [ENS Domain](/docs/concepts/the-ens-protocol) and a paginated list of its subdomains — the same flow as the [`DomainView`](https://github.com/namehash/ensnode/blob/main/examples/enskit-react-example/src/DomainView.tsx) in our example app. - + ## 1. Scaffold a React app @@ -31,8 +31,10 @@ npm install npm install enskit@1.13.1 enssdk@1.13.1 ``` -:::tip[Pin exact versions] +:::caution[Pin exact versions — hosted instance compatibility] Always pin **exact** versions (no `^` or `~`) of `enskit` and `enssdk`, and keep them on the same version. The Omnigraph GraphQL schema is bundled inside `enssdk` and consumed by the `gql.tada` TypeScript plugin to type your queries — a minor or patch bump can change the schema and silently drift your generated types away from your queries. Locking exact versions keeps types and runtime in sync. + +**Important:** Our hosted ENSNode instances currently run ENSNode v1.13. The latest published versions of `enskit` and `enssdk` are `1.14.0+`, which contain breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. If you are querying a hosted instance from your own app, you **must** use `enskit@1.13.1` and `enssdk@1.13.1` to avoid type errors and runtime mismatches. This notice will be removed once the hosted instances are upgraded. ::: ## 3. Configure the `gql.tada` TypeScript plugin diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enssdk/example.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enssdk/example.mdx index 5e826d1dee..44612e5b00 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enssdk/example.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enssdk/example.mdx @@ -8,9 +8,12 @@ sidebar: --- import EnssdkExampleInteractivePlayground from "@components/organisms/EnssdkExampleInteractivePlayground"; +import HostedInstanceSdkVersionWarning from "@components/molecules/HostedInstanceSdkVersionWarning.astro"; This playground loads the same source as [`enssdk-example`](https://github.com/namehash/ensnode/tree/main/examples/enssdk-example): a TypeScript script that queries the `eth` domain and lists its first 20 subdomains via [`enssdk`](/docs/integrate/integration-options/enssdk) and the [ENS Omnigraph API](/docs/integrate/omnigraph). + + :::note[First load may take a few minutes] The embedded StackBlitz editor runs entirely in your browser. Downloading and installing all npm packages may take a few minutes. Watch the install progress in the terminal of the StackBlitz editor. ::: diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enssdk/index.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enssdk/index.mdx index 5835f9e4ca..f109a44538 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enssdk/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/enssdk/index.mdx @@ -12,7 +12,7 @@ import IntegrateHostedEnsNodeTip from '@components/molecules/IntegrateHostedEnsN This guide walks you from an empty directory to a working TypeScript script that queries the `eth` Domain and queries its subdomains — the same flow as our [enssdk-example](https://github.com/namehash/ensnode/tree/main/examples/enssdk-example). - + ## 1. Scaffold a TypeScript project @@ -35,8 +35,10 @@ npm install enssdk@1.13.1 npm install -D tsx typescript @types/node ``` -:::tip[Pin exact versions] +:::caution[Pin exact versions — hosted instance compatibility] Always pin an **exact** version (no `^` or `~`) of `enssdk`. The Omnigraph GraphQL schema is bundled inside `enssdk` and consumed by the `gql.tada` TypeScript plugin to type your queries — a minor or patch bump can change the schema and silently drift your generated types away from your queries. Locking the exact version keeps types and runtime in sync. + +**Important:** Our hosted ENSNode instances currently run ENSNode v1.13. The latest published version of `enssdk` is `1.14.0+`, which contains breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. If you are querying a hosted instance from your own app, you **must** use `enssdk@1.13.1` to avoid type errors and runtime mismatches. This notice will be removed once the hosted instances are upgraded. ::: diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx index bbed365ce4..09b52ccba2 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/index.mdx @@ -24,7 +24,7 @@ Running your own ENSNode instance is helpful for those that wish to: Note that because ENSNode makes many label healing requests to ENSRainbow while indexing, it's _imperative_ that they be on the same local network to minimize request time. ::: -## Bootstrap from a snapshot (coming soon) +### Bootstrap from a snapshot (coming soon) Self-hosting today means standing up a fresh ENSNode instance from zero and waiting on an initial backfill - including the RPC bill that comes with it. **[ENSDb snapshots and `ensdb-cli`](/docs/integrate/integration-options/ensdb-cli)** will make it cheap and easy to begin working with indexed ENS data. @@ -36,6 +36,15 @@ Self-hosting today means standing up a fresh ENSNode instance from zero and wait href="/docs/integrate/integration-options/ensdb-cli" /> +### Massive scalability + + + + ### Deploying with Docker The Docker deployment option provides the easiest way to run the full ENSNode suite of services both locally and in the cloud. diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx new file mode 100644 index 0000000000..0069d77fef --- /dev/null +++ b/docs/ensnode.io/src/content/docs/docs/self-host/scalability.mdx @@ -0,0 +1,50 @@ +--- +title: ENSNode Scalability +description: Understand how ENSNode's architecture enables horizontal scaling. +sidebar: + label: Scalability + order: 3 +--- + +import { LinkCard } from '@astrojs/starlight/components'; + +ENSNode's architecture achieves effectively limitless horizontal scalability, no matter how large your query demands might be. By separating read / write workloads and making use of PostgreSQL's async replication you can scale your ENSNode deployment to handle any request volumes while continuing to index the latest ENS data without impact to indexing performance. + +## Horizontally scale ENSApi + +The ENSNode architecture naturally separates writes from reads: + +- **ENSIndexer** is the sole writer to ENSDb. It processes blockchain events and updates the database with the latest ENS state. +- **ENSApi** is a read-only service. It serves GraphQL and REST API requests by querying ENSDb, but never writes to it. + +This separation insulates ENSIndexer from high request volumes. Whether you serve 10 requests per second or 10,000, the indexing process remains unaffected because ENSApi does not compete with ENSIndexer for database write locks or indexer resources. + +## Horizontally Scale ENSDb + +ENSDb is built on PostgreSQL, which provides mature, production-proven mechanisms for horizontal scaling. The most common approach is **asynchronous replication**: + +1. **Primary ENSDb**: ENSIndexer writes to your single ENSDb primary instance. You can fully isolate this ENSDb primary instance from any incoming API requests coming through ENSApi. +2. **Replica ENSDb**: Configure the asynchronous replication of your primary ENSDb instance to one or more ENSDb read replica instances. +3. **Read scaling**: Connect your horizontally scaled ENSApi instances exclusively to your ENSDb read replica instances if you wish to fully isolate extreme levels of API request volumes from indexing. + +Because ENSApi is read-only, it can safely connect to an ENSDb replica without write-routing or write-conflict concerns. The tradeoff is that, with asynchronous replication, replica reads may briefly lag behind the primary. As your query load grows, you simply add more PostgreSQL replicas for the ENSDb primary instance and more ENSApi instances pointing to them. + +## Going Massive + +An ENSNode deployment with _massive_ horizontal scaling might look like this: + +![ENSNode Scalable Deployment Architecture](/ensnode-scalability.svg) + +- **One ENSIndexer instance** → writes to the ENSDb primary instance +- **One ENSDb primary instance** → replicates asynchronously to `M` replicas +- **Multiple ENSApi instances** → each of `N` instances connected to one of the ENSDb replicas (often load-balanced across replicas) +- **One ENSRainbow instance** → co-located with ENSIndexer instance on the same local network for fast label healing + +Only the largest ENSNode deployments will need such a complex setup. Still, it's good to know that if you need massive scalability, we have you covered! The ENSNode architecture lets you scale reads independently of writes, matching your infrastructure to your actual traffic patterns. + +## Further Reading + + + + + diff --git a/examples/enskit-react-example/README.md b/examples/enskit-react-example/README.md index b17b534ada..894c6b5efc 100644 --- a/examples/enskit-react-example/README.md +++ b/examples/enskit-react-example/README.md @@ -8,6 +8,8 @@ This app is hosted at [https://enskit-react-example.ensnode.io/](https://enskit- ## Usage (with NameHash Hosted Instance) +> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you **must** use `enskit@1.13.1` and `enssdk@1.13.1`. The latest published versions (`1.14.0+`) contain breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. This notice will be removed once the hosted instances are upgraded. + ```sh # from the ENSNode monorepo root pnpm install diff --git a/examples/enssdk-example/README.md b/examples/enssdk-example/README.md index ff75d02fd6..217f5c084f 100644 --- a/examples/enssdk-example/README.md +++ b/examples/enssdk-example/README.md @@ -6,6 +6,8 @@ Companion to the [enssdk integration guide](https://ensnode.io/docs/integrate/in ## Usage (with NameHash Hosted Instance) +> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you **must** use `enssdk@1.13.1`. The latest published version (`1.14.0+`) contains breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. This notice will be removed once the hosted instances are upgraded. + ```sh # from the ENSNode monorepo root pnpm install diff --git a/examples/omnigraph-graphql-example/README.md b/examples/omnigraph-graphql-example/README.md index 8b49e0afdc..80b4365d70 100644 --- a/examples/omnigraph-graphql-example/README.md +++ b/examples/omnigraph-graphql-example/README.md @@ -8,6 +8,8 @@ Companion to the [ENS Omnigraph GraphQL API integration guide](https://ensnode.i ## Usage (with NameHash Hosted Instance) +> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you **must** use `enssdk@1.13.1` (and `enskit@1.13.1` when using React). The latest published versions (`1.14.0+`) contain breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. This notice will be removed once the hosted instances are upgraded. + ```sh # from the ENSNode monorepo root pnpm install diff --git a/packages/enskit/README.md b/packages/enskit/README.md index 12214ac9d2..a1fa5dbdb1 100644 --- a/packages/enskit/README.md +++ b/packages/enskit/README.md @@ -1,5 +1,19 @@ # enskit +The React toolkit for ENSv2 development. Provides typed Omnigraph API hooks, providers, and utilities powered by [`urql`](https://nearform.com/open-source/urql/) and [`gql.tada`](https://gql-tada.0no.co/). + This package name is reserved for the [ENSNode](https://ensnode.io) project by [NameHash Labs](https://namehashlabs.org). For more information, visit [ensnode.io](https://ensnode.io). + +## Installation + +```bash +npm install enskit enssdk +``` + +> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you **must** use `enskit@1.13.1` and `enssdk@1.13.1`. The latest published versions (`1.14.0+`) contain breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. This notice will be removed once the hosted instances are upgraded. +> +> ```bash +> npm install enskit@1.13.1 enssdk@1.13.1 +> ``` diff --git a/packages/enssdk/README.md b/packages/enssdk/README.md index 75e840ef4e..9a35a2a72b 100644 --- a/packages/enssdk/README.md +++ b/packages/enssdk/README.md @@ -10,6 +10,12 @@ Learn more about [ENSNode](https://ensnode.io/) from [the ENSNode docs](https:// npm install enssdk ``` +> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you **must** use `enssdk@1.13.1`. The latest published version (`1.14.0+`) contains breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. This notice will be removed once the hosted instances are upgraded. +> +> ```bash +> npm install enssdk@1.13.1 +> ``` + ## Usage ### Core Client