feat(docs): introduce documentation websites

README.md

@@ -14,6 +14,14 @@ The main ENSNode indexer application enabling multichain indexing for ENS.
 ### [`apps/ensrainbow`](apps/ensrainbow)
 A sidecar service for healing ENS labels. It provides a simple API to recover labels from their hashes. This optimizes a number of ENS use cases, including indexing of ENS data. See the [ENSRainbow documentation](apps/ensrainbow/README.md) for more details.
 
+## Documentation
+
+### [`docs/ensnode`](docs/ensnode)
+Documentation website for [ENSNode application](apps/ensnode).
+
+### [`docs/ensrainbow`](docs/ensrainbow)
+Documentation website for [ENSRainbow application](apps/ensrainbow).
+
 ## Libraries
 
 ### [`packages/ensnode-utils`](packages/ensnode-utils)

biome.json

@@ -7,7 +7,7 @@
   },
   "files": {
     "ignoreUnknown": false,
-    "ignore": [".ponder/", "generated/"]
+    "ignore": [".astro", ".ponder/", "generated/"]
   },
   "formatter": {
     "enabled": true,

docs/ensnode/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/ensnode/README.md

@@ -0,0 +1,3 @@
+# ENSNode Documentation
+
+> A documentation website, powered by [Starlight](https://starlight.astro.build)

docs/ensnode/astro.config.mjs

@@ -0,0 +1,30 @@
+import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: "ENSNode Docs",
+      social: {
+        github: "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/namehash/ensnode/tree/main/apps/ensnode",
+      },
+      sidebar: [
+        {
+          label: "Guides",
+          items: [
+            // Each item here is one entry in the navigation menu.
+            {
+              label: "Querying best practices",
+              slug: "guides/querying-best-practices",
+            },
+          ],
+        },
+        {
+          label: "Reference",
+          autogenerate: { directory: "reference" },
+        },
+      ],
+    }),
+  ],
+});

docs/ensnode/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@docs/ensnode",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.31.1",
+    "astro": "^5.2.3",
+    "sharp": "^0.33.5"
+  }
+}

docs/ensnode/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

docs/querying_best_practices.md → docs/ensnode/src/content/docs/guides/querying-best-practices.md

@@ -1,4 +1,7 @@
-# ENSNode API Querying Best Practices
+---
+title: ENSNode API Querying Best Practices
+description: A guide about querying best practices
+---
 
 ## Stable Name Identification
 

docs/ensnode/src/content/docs/index.mdx

@@ -0,0 +1,34 @@
+---
+title: Welcome to ENSNode documentation
+description: Get started building ENS applications with your own ENSNode.
+template: splash
+hero:
+  tagline: Start indexing ENS names for your project!
+  actions:
+    - text: Try it now
+      link: https://alpha.ensnode.io
+      icon: external
+    - text: Read Guides
+      link: /guides/querying-best-practices/
+      icon: right-arrow
+      variant: minimal
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## Next steps
+
+<CardGrid stagger>
+	<Card title="Update content" icon="pencil">
+		Edit `src/content/docs/index.mdx` to see this page change.
+	</Card>
+	<Card title="Add new content" icon="add-document">
+		Add Markdown or MDX files to `src/content/docs` to create new pages.
+	</Card>
+	<Card title="Configure your site" icon="setting">
+		Edit your `sidebar` and other config in `astro.config.mjs`.
+	</Card>
+	<Card title="Read the docs" icon="open-book">
+		Learn more in [the Starlight Docs](https://starlight.astro.build/).
+	</Card>
+</CardGrid>

docs/ensnode/src/content/docs/reference/ens-subgraph.md

@@ -0,0 +1,40 @@
+---
+title: ENS Subgraph
+---
+
+# Graph Node
+
+[The Graph](https://thegraph.com/) leads development of [Graph Node](https://thegraph.com/docs/en/indexing/tooling/graph-node/), an [open source software application](https://github.com/graphprotocol/graph-node) for indexing blockchain data.
+
+# Subgraphs
+
+Each Graph Node server can run any number of "subgraphs". Each subgraph is essentially a plugin describing:
+1. A strategy for how the Graph Node should index blockchain data.
+2. A schema for a GraphQL API providing access to the indexed data.
+
+# ENS Subgraph
+
+[ENS Labs](https://www.enslabs.org/) has led development of the [ENS Subgraph](https://github.com/ensdomains/ens-subgraph). So far this has been the "official" strategy for indexing ENS data. Additional background info is available in [official ENS docs](https://docs.ens.domains/web/subgraph).
+
+# Graph Network
+
+Operating your own Graph Node server instance can be complex, expensive, and time consuming. An alternative is to use The Graph's semi-decentralized network of indexers operating Graph Node instances.
+
+This network provides access to a [semi-decentralized ENS Subgraph](https://thegraph.com/explorer/subgraphs/5XqPmWe6gjyrJtFn9cLy237i4cWw2j9HcUJEXsP5qGtH?view=Query&chain=arbitrum-one). Developers are welcome to use this rate limited API endpoint above for testing, but are highly encouraged to sign up for an account with The Graph to get their own (paid) API key.
+
+# NameHash Labs Hosted Graph Node Instance
+
+As an alternative to the Graph Network, [NameHash Labs](https://namehashlabs.org/) operates an independent Graph Node instance. This is currently being freely offered to the ENS community without need for API keys or rate limiting. It can be found at https://graphnode.namehashlabs.org:8030. An [interactive GraphQL Playground](https://graphnode.namehashlabs.org:8030/graphql/playground) is also available.
+
+This server is running [Graph Node version 0.33.0](https://github.com/graphprotocol/graph-node/releases/tag/v0.33.0). The latest Graph Node release (as of this writing) is [version 0.36.0](https://github.com/graphprotocol/graph-node/releases), however it is understood that this version update has no impact on the data being indexed.
+
+# NameHash Labs Hosted ENS Subgraphs
+
+Our Graph Node instance indexes the ENS Subgraph. The live status can be monitored with [the indexing status API endpoint](https://graphnode.namehashlabs.org:8030/graphql/playground?query=%7B%0A%20%20indexingStatuses%20%7B%0A%20%20%20%20subgraph%0A%20%20%20%20health%0A%20%20%20%20historyBlocks%0A%20%20%20%20paused%0A%20%20%20%20synced%0A%20%20%20%20chains%20%7B%0A%20%20%20%20%20%20network%0A%20%20%20%20%20%20chainHeadBlock%20%7B%0A%20%20%20%20%20%20%20%20number%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20latestBlock%20%7B%0A%20%20%20%20%20%20%20%20number%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D).
+Subgraph Id: QmVsj1tYQ84DZH3NHAbZKjQ5agQ5Gt6VusUBf67CU32FWP
+   * As of the time of writing this wiki page:
+     * This is the latest version of the ENS Subgraph, published [Feb 15, 2024](https://github.com/graphprotocol/ens-subgraph/commit/c8447914e8743671fb4b20cffe5a0a97020b3cee).
+   * The subgraph is fully synced with the latest block on mainnet.
+   * [Interactive GraphiQL Explorer](https://graphnode.namehashlabs.org:8000/subgraphs/name/namehash/ens-subgraph-2/graphql)
+
+This Subgraph Id is understood to be distinct from the "official" hosted ENS subgraph because it is associated with our own hosted Graph Node instance that is not participating in The Graph's distributed network of indexers.

docs/ensnode/src/content/docs/reference/indexing-ens-compabile-onchain-names.md

@@ -0,0 +1,38 @@
+---
+title: Indexing ENS‐compatible on‐chain names
+---
+
+# Accessing on-chain data
+
+Fetching data about on-chain activity can be either done via direct RPC calls to a blockchain node, or via an API service that has previously indexed the on-chain data. The first approach is about loading data directly from a source of truth, but it's also more complex and require the client to know how to use the data. Using the API service is more flexible, because it abstracts away the data transformation process, and allows the clients to query a set of prepared aggregates.
+
+# ENS and the `eth` top-level domain
+
+## Indexing on-chain data
+
+The ENS community has adopted the Graph Protocol and built [the ENS Subgraph](https://github.com/ensdomains/ens-subgraph) to index on-chain data about ENS and the `eth` subnames. The indexing engine sources data from an RPC node, and aggregates it into a set of collections. The main collections describe following data entities:
+- Account
+- Domain
+- Registration
+- Resolver
+- WrappedDomain
+
+## Serving aggregate data
+
+Web Clients which want to access the ENS Subgraph can easily do it with [the ensjs client library](https://github.com/ensdomains/ensjs). The ensjs lib queries data from [the ENS Subgraph deployment](https://api.thegraph.com/subgraphs/name/ensdomains/ens). This deployment has [a GraphiQL interface](https://api.thegraph.com/subgraphs/name/ensdomains/ens/graphql?query=%7B%0A++account%28id%3A+%220xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401%22%29+%7B%0A++++domains%28orderBy%3A+createdAt%2C+orderDirection%3A+desc%2C+first%3A+3%29+%7B%0A++++++name%0A++++++createdAt%0A++++++resolver+%7B%0A++++++++addr+%7B%0A++++++++++id%0A++++++++%7D%0A++++++++contentHash%0A++++++++texts%0A++++++%7D%0A++++%7D%0A++%7D%0A++registrations%28orderBy%3A+registrationDate%2C+orderDirection%3A+desc%2C+first%3A+3%29+%7B%0A++++registrationDate%0A++++domain+%7B%0A++++++name%0A++++%7D%0A++++registrant+%7B%0A++++++id%0A++++%7D%0A++%7D%0A%7D) if you'd like to interact with it and check out the data model it offers.
+
+# Other ENS-compatible protocols
+
+The canonical ENS protocol has been originally deployed on the Ethereum Mainnet. [There are plans](https://x.com/ensdomains/status/1869020192388616497) to scale the protocol with its own layer-2 chain, called Namechain.
+
+Some members of the ENS community have started building their own [ENS subname systems on top of the CCIP-read protocol](https://docs.ens.domains/learn/ccip-read), for example:
+- [Basenames](https://www.base.org/names) from coinbase.com ([source](https://github.com/base-org/basenames))
+- [Linea ENS](https://names.linea.build/) from consensys.io ([source](https://github.com/Consensys/linea-ens))
+
+These L2 systems run their own copy of ENS-compatible contracts. And that's where the NameHash ENS Multi-chain Indexer wants to fill a gap.
+
+## Indexing L2 subnames
+
+TBD
+
+

docs/ensnode/src/content/docs/reference/terminology.md

@@ -0,0 +1,42 @@
+---
+title: Terminology
+---
+
+New terminology (beyond the [official ENS glossary](https://docs.ens.domains/terminology)) has been needed in the course of building the ENS Multichain Indexer. The following should be understood as a draft that is open to community feedback. Each definition below aims to maximize alignment with the official ENS glossary where possible.
+
+# Subregistry
+
+Any data structure outside of the [Registry](https://docs.ens.domains/terminology#registry) that manages supplemental state for a set of [subnames](https://docs.ens.domains/terminology#subname-subdomain). Each [name](https://docs.ens.domains/terminology#name) is associated with at least 1 subregistry (through the [Name Wrapper](https://docs.ens.domains/terminology#name-wrapper)) and may optionally be associated with multiple subregistries. When a name is associated with multiple subregistries, this means that the full state of a name must be combined across the Registry and each associated subregistry. For example, the state of all direct subnames of .eth is distributed across the Registry and two subregistries: the BaseRegistrar and the Name Wrapper. The ENS protocol does not currently define standards for subregistries. Subregistries currently exist outside the scope of the ENS protocol. For example, subregistries could live on L1, on L2s, or offchain (in a database or even in a Google Sheet). The ENS protocol currently provides no standardized mechanism to discover subregistries or to interact with subregistries.
+
+Some specific implementations of subregistries include:
+
+* The [BaseRegistrar](https://github.com/ensdomains/ens-contracts/blob/staging/contracts/ethregistrar/BaseRegistrarImplementation.sol) that holds supplemental state for direct subnames of .eth. This includes state for ERC721 NFTs and expiry times.
+* The [NameWrapper](https://docs.ens.domains/terminology#name-wrapper), which serves as a subregistry for the entire ENS root (all ENS names).  This includes state for ERC1155 NFTs, expiry times, and fuses.
+  * Note how direct subnames of .eth are an example of multiple subregistries potentially holding supplemental state for a name outside the Registry.
+* The contracts on Base that manage supplemental state for direct subnames of [base.eth](https://www.base.org/names).
+* The contracts on Linea that manage supplemental state for direct subnames of [linea.eth](https://names.linea.build/).
+* The contracts on Base / Optimism that manage supplemental state for DNS names managed by [3DNS](https://3dns.box/).
+* The offchain databases that manage supplemental state for direct subnames of [uni.eth](https://blog.uniswap.org/introducing-uni-eth-your-unique-web3-username).
+* The offchain databases that manage supplemental state for direct subnames of [cb.id](https://help.coinbase.com/en/wallet/managing-account/coinbase-ens-support).
+* DNS nameservers for (essentially) all DNS names. Since ENS is a superset of DNS, (essentially) any DNS name is an ENS name. Therefore, whenever supplemental state associated with a DNS name is updated in a DNS nameserver, a subregistry is being updated.
+
+# Subregistrar
+
+Any system that is a [Registrar](https://docs.ens.domains/terminology#registrar) or that writes to a subregistry.
+
+This definition expands the definition of Registrar to include cases such as:
+
+* The [ETHRegistrarController](https://github.com/ensdomains/ens-contracts/blob/staging/contracts/ethregistrar/ETHRegistrarController.sol) that writes to BaseRegistrar (the owner of the "eth" TLD). Note how the definition of "Registrar" in the official ENS glossary only includes contracts that are pointed to by the owner field of the Registry. Therefore, the BaseRegistrar is a Registrar (and a Subregistry), while the ETHRegistrarController is a Subregistrar.
+* The contracts on Base that write to the Subregistry for direct subnames of base.eth. These contracts live on Base, therefore they cannot meet the definition of Registrar because they can't be set as the owner in the Registry on Ethereum mainnet.
+* The offchain systems that write to the offchain databases associated with direct subnames of uni.eth and cb.id.
+* Any NFT marketplace that supports the exchange of an NFT representing ownership of an ENS name. Each time a NFT is exchanged, state about that NFT must be updated within a related subregistry. Therefore the marketplace enabling that trade is a Subregistrar.
+* Any DNS registrar, as ENS is a superset of DNS.
+
+# Shadow Registry
+
+A Subregistry meeting ALL of the following constraints:
+1. Not the Registry;
+2. Implemented as a smart contract exposing the same interface as the Registry;
+3. Used as part of the source of truth for a CCIP-Read Gateway Server for ENSIP-10 (wildcard resolution) powered subnames.
+
+A specific implementation of a Shadow Registry can be found in [this contract](https://github.com/base-org/basenames/blob/v1.0.4/src/L2/Registry.sol) storing a subset of the state of base.eth subnames on Base.

docs/ensnode/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

docs/ensrainbow/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/ensrainbow/README.md

@@ -0,0 +1,3 @@
+# ENSRainbow Documentation
+
+> A documentation website, powered by [Starlight](https://starlight.astro.build)

docs/ensrainbow/astro.config.mjs

@@ -0,0 +1,30 @@
+import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: "ENSRainbow Docs",
+      social: {
+        github: "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/namehash/ensnode/tree/main/apps/ensrainbow",
+      },
+      sidebar: [
+        {
+          label: "Guides",
+          items: [
+            // Each item here is one entry in the navigation menu.
+            {
+              label: "Quick start",
+              slug: "guides/quick-start",
+            },
+          ],
+        },
+        {
+          label: "Reference",
+          autogenerate: { directory: "reference" },
+        },
+      ],
+    }),
+  ],
+});

docs/ensrainbow/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@docs/ensrainbow",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.31.1",
+    "astro": "^5.2.3",
+    "sharp": "^0.33.5"
+  }
+}

docs/ensrainbow/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};