diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx index e4405d9ae0..baf8a2b5ef 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx @@ -7,52 +7,39 @@ import { LinkCard, Aside } from "@astrojs/starlight/components"; -## The problem with ENSv1 integrations today +## Historical limitations of building on ENS -Fully supporting ENSv1 requires two separate systems working in parallel: +Full access to ENS data formerly required two separate data fetching strategies working in parallel: -1. **On-chain resolution** — RPC calls with CCIP-read support (e.g. via [viem](/docs/reference/subgraph-legacy/with-viem) or [ensjs](/docs/reference/subgraph-legacy/with-ensjs)) to resolve names to addresses and records at the current state of the chain. -2. **Indexed data** — the [ENS Subgraph](/docs/reference/subgraph-legacy/what-is-the-ens-subgraph) for historical data, registration info, reverse records, and browsing names owned by an address. +1. **ENS resolution** — RPC calls with CCIP-read support for offchain data (e.g. via a popular package such as `viem` or `wagmi`) to perform forward or reverse ENS resolution. +2. **Indexed ENS data** — the [ENS Subgraph](/docs/reference/subgraph-legacy/what-is-the-ens-subgraph) for indexed ENS data, such as discovering names owned by an address and all other ENS state outside of ENS resolutions. -Neither system alone is complete. -The Subgraph gives you queryable indexed history but can lag behind the chain and has no CCIP-read support. -On-chain resolution gives you accurate live state but no history and no way to browse names. +Neither system alone was complete. +- ENS resolution gives you resolver records, but no access to all the other state about ENS! ENS Resolutions as exposed through popular libraries such as `viem` and `wagmi` are also painfully "close to the metal", putting the burden on app developers to learn and carefully implement complex details about interpreting raw values returned by the ENS protocol. +- The Subgraph gives you queryable indexed ENS data but has critical limitations, including: + - The Subgraph is single-chain. + - The Subgraph has no support for ENSv2's fundamental data model changes. + - The Subgraph cannot perform ENS resolutions. + - The Subgraph doesn't understand key implementation details of the ENS protocol such as ENSIP-10, ENSIP-19, ENS name normalization (ENSIP-15), etc. + - The Subgraph exposes too many internal implementation detail complexities of ENS for app developers. -Most ENS integrations today live with this split — and with **ENSv2**, the complexity only increases as names spread across multiple chains. +In the past, apps building on ENS have had to live with these split fetching strategies, their limitations, and their downstream complexities. And we should note, **with ENSv2, the complexity of ENS's onchain state space meaningfully increases**. -## How ENS Omnigraph solves this +## How ENSNode solves this -The [ENS Omnigraph API](/docs/integrate/omnigraph) is ENSNode's _unified_ GraphQL API that replaces both systems with a single endpoint: +[ENSIndexer](/docs/services/ensindexer) offers the `unigraph` plugin, which builds a **unified** polymorphic indexed data model in [ENSDb](/docs/services/ensdb) of multiple ENSv1 Nametrees (the ENSv1 onchain state model found in the ENS root registry, Basenames on Base, Lineanames on Linea, 3DNS on Optimism, etc.), and the ENSv2 Namegraph (the ENSv2 onchain state model that ENSv1 domains may optionally make a dynamic upgrade to, and may contain cycles, disjoint domains, and allows domains to dynamically reposition themselves across time within the ENSv2 Namegraph). -- **Resolution data is indexed** — owner, resolver, records, expiry, and CCIP-read results are resolved and stored at index time, so you get accurate resolution data from a simple GraphQL query with no RPC calls in your app. -- **Full history and browsability** — all the indexed capabilities of the Subgraph, unified across chains. -- **Multichain by design** — a single query can span mainnet, Base, Linea, 3DNS, and any future ENSv2 registries. +The [ENS Omnigraph API](/docs/integrate/omnigraph) is delivered by the [ENSApi](/docs/services/ensapi) service which provides a highly tailored GraphQL API that builds upon and refines the "unigraph" indexed data model held in ENSDb to deliver all your ENS data access needs in a single API endpoint. The ENS Omnigraph API also understands ENS protocol implementation details including ENSIP-15 (ENS name normalization), ENSIP-10, ENSIP-19, and much more so that you can focus on building your app and not all the internal implementation complexities of the ENS protocol. -This means you write one integration instead of two, and you get more accurate data as a result. - -## ENSv2 readiness - -ENSv2 moves ENS registries from Ethereum mainnet to L2s. When it launches, names may exist across multiple chains, -and the current two-system approach becomes even harder to maintain — you would need separate resolution logic and separate Subgraph queries for each chain. - -ENSNode is already built for this world: - -- ENSNode indexes ENSv2 registries as they come online -- The ENS Omnigraph API surfaces ENSv2 names alongside ENSv1 names transparently -- The [enssdk](/docs/integrate/integration-options/enssdk) and [enskit](/docs/integrate/integration-options/enskit) client libraries abstract over chain differences entirely - -:::tip[The result] -If you integrate with **ENS Omnigraph** today to support **ENSv1**, you automatically get **ENSv2** support when it launches — your code does not need to change. -::: +- **ENS Resolution** — The ENS Omnigraph API, through ENSApi, internally implements the ENS Universal Resolver on top of the indexed ENS Unigraph datamodel in ENSDb. We refer to this idea as "ENS Protocol Acceleration". For cases where ENS Resolution requires offchain data, ENSApi internally performs the CCIP-read operations on your behalf to ensure every resolution request accurately follows all ENS protocol standards. No need for any RPC calls in your app. Your ENS resolutions may now also be faster than ever! +- **Indexed ENS data** — Access the multichain indexed "unigraph" state model all within a single unified, polymorphic API-level state model that understands ENS protocol implementation details including ENSIP-15 (ENS name normalization), ENSIP-10, ENSIP-19, and much more so that you can focus on building your app and not all the internal implementation complexities of the ENS protocol. ## What you need to do -1. **Replace your Subgraph queries** with ENS Omnigraph queries. The [Migration Guide](/docs/integrate/migrate-from-subgraph) will help you with that. -2. **Remove your RPC resolution calls** from the hot path. Omnigraph already resolves and indexes this data — you can query it directly and save on RPC calls. -3. **Use [enssdk](/docs/integrate/integration-options/enssdk)** for a fully typed TypeScript client, or query the [ENS Omnigraph GraphQL API](/docs/integrate/integration-options/omnigraph-graphql-api) directly if you prefer. - -⭐ That's it! There is no ENSv2-specific migration step later ⭐ +:::caution[Coming Soon] +We're actively working on this page right now. Check back by May 18th for full content! +::: 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 996f2d7c8f..9a9fdfe4b9 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/index.mdx @@ -10,9 +10,7 @@ import { LinkCard, CardGrid, Aside } from "@astrojs/starlight/components"; ## What is ENSv2? -ENSv2 is the next generation of the Ethereum Name Service — a protocol upgrade that moves ENS registries from Ethereum mainnet onto L2s. Names become cheaper to register, faster to update, and natively multichain. - -ENSv2 is backwards compatible with ENSv1: existing `.eth` names continue to work, and ENSv2 introduces a new registry architecture that supports names across multiple chains simultaneously. +ENSv2 is the next generation of the Ethereum Name Service — a protocol upgrade that fundamentally changes the onchain data model of ENS. :::tip[Prepare for ENSv2] The ENSv2 upgrade to the ENS protocol is coming **Summer 2026**! Your app, regardless of how it interacts with names, needs to be updated to avoid being left behind. @@ -22,22 +20,26 @@ The ENSv2 upgrade to the ENS protocol is coming **Summer 2026**! Your app, regar ::: -## What is ENS Omnigraph? +## What is the ENS Omnigraph? -ENSNode fully supports the ENSv2 upgrade via the [Omnigraph API](/docs/integrate/omnigraph), a _unified_ API over **both** ENSv1 and ENSv2. ENSNode takes the guesswork out of ENS integrations, whether you need to resolve up-to-date records, search all Domains, or see which Domains a user owns (and much, much more). +ENSNode fully supports ENSv2 via the [Omnigraph API](/docs/integrate/omnigraph), a _unified_ API over **both ENSv1 and ENSv2**. Note how when ENSv2 launches, ENSv1 continues to exist in parallel. ENSNode takes the guesswork out of building on ENS, whether you need to resolve up-to-date records, search all Domains, or see which Domains a user owns (and much, much more). ![ENS Omnigraph diagram](/ens-omnigraph-diagram.png) -ENS Omnigraph is **backwards compatible** with ENSv1, so you can integrate today and get ENSv2 support automatically when it launches! +ENS Omnigraph supports both ENSv1 and ENSv2 **concurrently**. This means you can integrate today (before ENSv2 launches) and continue with full ENSv2 support when it goes live with zero downtime! + +## ENSNode's Integration Options -ENSNode supports many different integration options, whether you're using React, any JavaScript runtime, or raw GraphQL. +ENSNode supports a full range of different integration options across the stack, whether you're using React, any JavaScript runtime, raw GraphQL, or looking to go deep and build a new and fully custom service on ENS data. -## 1. `enskit` + Omnigraph +Here's a summary of some popular integration strategies: + +### 1. `enskit` + Omnigraph 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. @@ -126,7 +128,7 @@ export function RenderDomainAndSubdomains({ name }: { name: InterpretedName }) { href="https://github.com/namehash/ensnode/tree/main/examples/enskit-react-example" /> -## 2. `enssdk` + Omnigraph +### 2. `enssdk` + Omnigraph 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. @@ -161,7 +163,7 @@ const result = await client.omnigraph.query({ query: HelloWorldQuery }); href="https://github.com/namehash/ensnode/tree/main/examples/enssdk-example" /> -## 3. ENS Omnigraph GraphQL API +### 3. ENS Omnigraph GraphQL API The ENS Omnigraph API is a GraphQL API following the Relay specification, so you get built-in support for efficient infinite pagination and idiomatic access to all of the ENS protocol within a _unified_ ENSv1 + ENSv2 datamodel. @@ -190,3 +192,9 @@ query MyDomains($address: Address!) { description='Check out our omnigraph-graphql-example for a full example app.' href="https://github.com/namehash/ensnode/tree/main/examples/omnigraph-graphql-example" /> + + diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx index c6ec0ccf2e..9777db278a 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx @@ -7,15 +7,15 @@ import { LinkCard } from "@astrojs/starlight/components"; import EnsDbSelfHostingNote from "../../../../../components/molecules/EnsDbSelfHostingNote.astro"; import EnsDbUseCases from "../../../../../components/molecules/EnsDbUseCases.astro"; -For special use cases that go beyond what the ENS Omnigraph exposes — you can query the live onchain state of **ENSv2** directly via `SQL`. +For special use cases that go beyond what the ENS Omnigraph exposes — you can query the live onchain state of both **ENSv1 and ENSv2** directly via `SQL`. -**ENSDb** is an open standard that stores the live onchain **ENSv2** state in a carefully-crafted data model within a PostgreSQL database. Because it's plain Postgres, you can use *any* language with a Postgres driver — **TypeScript**, **Python**, **Rust**, **Go**, and more. +**ENSDb** is a bi-directional integration standard for any EnsDbWriter and EnsDbReader implementations to coordinate around the live unified onchain state of ENSv1 **and ENSv2** in a carefully-crafted standardized data model within a PostgreSQL database. Because ENSDb builds on Postgres, you can use *any* language with a Postgres driver — **TypeScript**, **Python**, **Rust**, **Go**, and more. -### What you can build with ENSDb +### Inspirations for what you can build with ENSDb