Add scalability story to ENSNode self-hosting module

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",
+    },
   ],
 };

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
+  ? "<code>enskit@1.13.1</code> and <code>enssdk@1.13.1</code>"
+  : isBoth
+    ? "<code>enssdk@1.13.1</code> (and <code>enskit@1.13.1</code> when using React)"
+    : "<code>enssdk@1.13.1</code>";
+---
+
+<Aside type="caution" title="Version compatibility with hosted instances">
+  Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you <strong>must</strong> use <span set:html={sdkList} />. The latest published versions (<code>1.14.0+</code>) contain breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. Use these exact install commands:
+
+  {isBoth ? (
+    <pre>npm install enssdk@1.13.1
+# or, for React apps:
+npm install enskit@1.13.1 enssdk@1.13.1</pre>
+  ) : isEnskit ? (
+    <pre>npm install enskit@1.13.1 enssdk@1.13.1</pre>
+  ) : (
+    <pre>npm install enssdk@1.13.1</pre>
+  )}
+
+  This notice will be removed once the hosted instances are upgraded.
+</Aside>

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;
 ---
 
 <Aside type="tip" title="No backend required">
 You don't need to run your own ENSNode to follow this guide — the steps below default to a NameHash-hosted instance. Browse the available deployments below.
 </Aside>
+<HostedInstanceSdkVersionWarning for={target} />
 <LinkCard
   title="Hosted ENSNode Instances"
   href="/docs/hosted-instances"
 />
-
-

docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx

@@ -7,13 +7,16 @@ sidebar:
 
 import { LinkCard } from "@astrojs/starlight/components";
 import HostedEnsNodeInstances from "@components/molecules/HostedEnsNodeInstances.astro";
+import HostedInstanceSdkVersionWarning from "@components/molecules/HostedInstanceSdkVersionWarning.astro";
 
 ## Hosted Instances
 
 NameHash Labs provides freely available hosted instances for ENS developers looking to get started quickly.
 
 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.
 
+<HostedInstanceSdkVersionWarning for="both" />
+
 ### 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.

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.
 
+<HostedInstanceSdkVersionWarning for="enskit" />
+
+
 ```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.
 
+<HostedInstanceSdkVersionWarning for="enssdk" />
+
+
 ```ts
 // create and extend an EnsNodeClient with Omnigraph API support
 const client = createEnsNodeClient({ url: process.env.ENSNODE_URL! }).extend(omnigraph);

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.
+<HostedInstanceSdkVersionWarning for="enskit" />
+
+:::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.

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.
 
-<IntegrateHostedEnsNodeTip />
+<IntegrateHostedEnsNodeTip for="enskit" />
 
 
 ## 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

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).
 
+<HostedInstanceSdkVersionWarning for="enssdk" />
+
 :::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.
 :::

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).
 
-<IntegrateHostedEnsNodeTip />
+<IntegrateHostedEnsNodeTip for="enssdk" />
 
 ## 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.
 :::
 
 

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
+
+<LinkCard
+  title="Learn about ENSNode scalability"
+  description="Architecture overview of how to scale ENSNode to handle a massive volume of requests."
+  href="/docs/self-host/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.

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
+
+<LinkCard title="ENSApi Overview" href="/docs/services/ensapi" />
+<LinkCard title="ENSDb Overview" href="/docs/services/ensdb" />
+<LinkCard title="ENSIndexer Overview" href="/docs/services/ensindexer" />
+<LinkCard title="ENSRainbow Overview" href="/docs/services/ensrainbow" />

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

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

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

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
+> ```

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