Docs: improve docs narrative around "ENSNode Plugins", "ENSDb Writers", and "ENSDb Readers".#2227
Open
tk-o wants to merge 18 commits into
Open
Docs: improve docs narrative around "ENSNode Plugins", "ENSDb Writers", and "ENSDb Readers".#2227tk-o wants to merge 18 commits into
tk-o wants to merge 18 commits into
Conversation
…-examples-content
New pages for ENSDb Writers, ENSDb Readers, and ENSNode Plugins. Update relevant links.
…iter-reader-ensnode-plugins
|
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
2 Skipped Deployments
|
Contributor
📝 WalkthroughWalkthroughAdds three integration concepts—ENSDb Writers, ENSDb Readers, ENSNode Plugins—by creating dedicated docs pages, updating the Integration Options index and Starlight sidebar, repositioning ENSIndexer as an ENSDb Writer reference implementation, and aligning cross-document links and glossary terms. ChangesENSDb & ENSNode Plugins Architecture
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis PR improves the documentation narrative around three related concepts — ENSNode Plugins, ENSDb Writers, and ENSDb Readers — by adding dedicated pages for each and updating cross-references throughout the existing docs.
Confidence Score: 5/5Documentation-only changes that reorganise and clarify existing concepts; no runtime code is affected. All changes are markdown/MDX documentation and sidebar configuration. The new pages are well-structured, internal links resolve to existing files, and the previously flagged issues (missing href, relative glossary URL, inconsistent terminology) are addressed. The remaining findings are minor prose and punctuation nits. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["ENSNode Plugin\n(abstract specification)"] -->|implemented by| B["ENSDb Writer\n(e.g. ENSIndexer, Envio, Amp)"]
A -->|read by| C["ENSDb Reader\n(e.g. ENSApi, ensdb-cli, ENSEngine)"]
B -->|writes indexed data| D[("ENSDb Instance\n(PostgreSQL)")]
B -->|writes metadata via| E["ENSDb Metadata Writer"]
E -->|stores in| D
C -->|reads from| D
D -->|follows| F["ENSDb Standard"]
Reviews (7): Last reviewed commit: "Apply PR feedback" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refines the documentation narrative around ENSNode Plugins, ENSDb Writers, and ENSDb Readers, positioning ENSIndexer/ENSApi explicitly as reference implementations and adding dedicated integration-option pages to explain the architecture and interoperability model.
Changes:
- Reframes ENSIndexer docs to describe it as an ENSDb Writer reference implementation and clarifies how it implements ENSNode Plugins.
- Expands the ENSDb glossary with definitions for ENSNode Plugin and ENSDb Metadata Writer, and updates related metadata terminology.
- Adds new integration-option pages for ENSDb Writers, ENSDb Readers, and ENSNode Plugins, and links them from the integration options index + sidebar.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/ensnode.io/src/content/docs/docs/services/ensindexer/index.mdx | Repositions ENSIndexer as a reference ENSDb Writer and links to glossary terminology. |
| docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx | Renames/reframes the page to explain ENSNode Plugins and ENSIndexer’s plugin implementation structure. |
| docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx | Updates “What you can build” section to point readers to integration inspirations. |
| docs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdx | Adds/updates key definitions (ENSNode Plugin, ENSDb Writer/Reader, Metadata Writer) and metadata terminology. |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/schema-reference.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdx | Adds new top-level integration options for Writers/Readers/Plugins and renumbers subsequent sections. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdx | New page describing the ENSNode Plugin specification and listing core/community plugins. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx | Adds paragraph explaining ENSDb’s metadata spec and links to Writers/Readers pages. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdx | New page describing the ENSDb Writer spec and reference/partner implementations. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdx | New page describing the ENSDb Reader spec and reference reader apps. |
| docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/config/integrations/starlight/sidebar-topics/services.ts | Renames the ENSIndexer contributing sidebar item to “ENSNode Plugins”. |
| docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.ts | Adds sidebar entries for Writers/Readers/Plugins integration-option pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdx`:
- Around line 44-47: The LinkCard for "Learn more about ENSAnalytics (coming
soon)" is missing the required href prop; update the LinkCard component in
ensdb-readers.mdx to include an href (e.g., a placeholder route like
"/ensanalytics" or a temporary external URL) so the
`@astrojs/starlight/components` LinkCard receives a valid href, keeping the title
"ENSAnalytics" and description unchanged; ensure the href is a string literal
and points to the placeholder until the real route exists.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdx`:
- Line 11: The bullet under "writer responsibilities" contains a malformed
fragment "How to process onchain data into (including transforming raw onchain
data into a desired internal data model)"; replace it with a complete,
grammatical sentence such as "How to process on‑chain data, including
transforming raw on‑chain data into a desired internal data model" so the
responsibility reads clearly—update the writer responsibilities bullet in the
ENSDB writers section to use that full sentence.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx`:
- Line 14: Update the interoperability phrasing in the sentence referencing the
"ENSDb standard" so that it reads "...supports decoupling and interop with any
EnsDbReader implementation." Locate the sentence that mentions "EnsDbWriters",
"ENSDb instance" and "EnsDbReaders" and replace the fragment "interop with any
of EnsDbReaders" with "interop with any EnsDbReader implementation" to tighten
grammar and clarity.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdx`:
- Line 23: In the paragraph starting with "ENSNode Plugins are the key
architectural piece..." replace both occurrences of the phrase "standards
compliant" with the hyphenated form "standards-compliant" to make the compound
adjective consistent and improve readability; update the two instances that
describe an ENSDb Writer producing a "standards-compliant ENSDb" and an ENSDb
Reader being "standards-compliant" so both are hyphenated.
In `@docs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdx`:
- Line 70: Update the glossary sentence for ENSDb Reader to avoid "sole ENSDb
Writer" — in the ENSDb Reader definition replace "the sole [ENSDb
Writer](`#ensdb-writer`)" with either "an [ENSDb Writer](`#ensdb-writer`)" or "the
configured [ENSDb Writer](`#ensdb-writer`) for the reader context" so it aligns
with the multi-tenant model; edit the sentence in the ENSDb Reader paragraph in
glossary.mdx (the line containing "Any application that reads ENS data...")
accordingly.
- Around line 64-65: Update the broken self-link and grammar in the ENSDb
glossary sentence: change the relative link
"docs/services/ensdb/concepts/glossary#ensnode-metadata-table" to an absolute
path by adding a leading "/" (i.e.
"/docs/services/ensdb/concepts/glossary#ensnode-metadata-table") and fix the
agreement typo by replacing "instance that have" with "instance that has" in the
same paragraph referring to ENSIndexer and the ENSNode Metadata Table.
In
`@docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx`:
- Around line 11-13: Replace the inconsistent glossary terms in this document:
change occurrences of `EnsDbWriter`, `EnsDbWriters`, and `EnsDbReaders` to the
canonical capitalized forms `ENSDb Writer`, `ENSDb Writers`, and `ENSDb Readers`
respectively so they match the rest of the docs; update both the inline mentions
and any link text (e.g., the two instances in the second paragraph and the first
sentence) while preserving existing links/URLs and surrounding punctuation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 17b3bbe3-d245-47a9-85d0-e73061144aee
📒 Files selected for processing (14)
docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.tsdocs/ensnode.io/config/integrations/starlight/sidebar-topics/services.tsdocs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/schema-reference.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/index.mdx
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com>
…iter-reader-ensnode-plugins
Comment on lines
+40
to
+44
| <LinkCard | ||
| title="Learn more about ENSAnalytics (coming soon)" | ||
| description="A web service that provides analytics and insights on ENS data." | ||
| href="/docs/services" | ||
| /> |
| ## 5. enscli | ||
| ## 5. ENSDb Writers | ||
|
|
||
| Build your own indexer for ENSDb by implementing the [ENSNode Plugin](/docs/integrate/integration-options/ensnode-plugins) specifications you're interested to index. ENSDb Writers index onchain data and write it into an ENSDb instance according to the standards set by relevant ENSNode Plugins. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdx`:
- Line 3: The frontmatter description contains a typo: "How to build custom APIs
and under services on top of ENSDb, using the ENSDb Reader standard."; update
the description string in the document's frontmatter to read "How to build
custom APIs and other services on top of ENSDb, using the ENSDb Reader
standard." so the phrase "under services" is replaced with "other services"
(edit the description field in the frontmatter).
- Line 16: In the ENSDb readers doc sentence that currently reads "APIs for
various queries related to the the metadata stored in ENSDb..." remove the
duplicated article so it reads "related to the metadata stored in ENSDb"; update
the string in the ENSDb readers content (look for the exact sentence "APIs for
various queries related to the the metadata stored in ENSDb") to fix the typo
and keep the rest of the paragraph unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: e5927c44-904c-4d03-bfb5-07a2a068ac45
📒 Files selected for processing (10)
docs/ensnode.io/config/integrations/starlight/sidebar-topics/services.tsdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx
💤 Files with no reviewable changes (1)
- docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx
|
|
||
| ## Plugin implementation structure | ||
|
|
||
| Each ENSNode Plugin implemented in ENSIndexer is a standalone TypeScript module that can be developed, and tested independently, while all ENSNode Plugins are deployed together as part of the single ENSIndexer service and activated via the `PLUGINS` environment variable.. The ENSNode Plugin can define its own indexed data models and indexing logic. It must include two main files: |
| ### ENSDb Writer | ||
|
|
||
| Any application that writes ENS data into an [ENSDb instance](#ensdb-instance) following the [ENSDb Standard](#ensdb-standard). For example, [ENSIndexer](#ensindexer) is a reference implementation of an ENSDb Writer. Other implementations of ENSDb Writers can be built in any language, and can use different indexing frameworks (i.e. [Ponder](https://ponder.sh/), [rindexer](https://rindexer.xyz/)), as long as they follow the ENSDb Standard. | ||
| Any application that implements one or more standard-compliant [ENSNode Plugins](#ensnode-plugin) and includes an [ENSDb Metadata Writer](#ensdb-metadata-writer), writing ENS data into an [ENSDb instance](#ensdb-instance) following the [ENSDb Standard](#ensdb-standard). For example, [ENSIndexer](#ensindexer) is a reference implementation of an ENSDb Writer. Other implementations of ENSDb Writers can be built in any language, and can use different indexing frameworks (i.e. [Ponder](https://ponder.sh/), [Envio](https://envio.dev/), [rindexer](https://rindexer.xyz/)), [Amp](https://ampup.sh/) from Edge & Node, etc as long as they follow the ENSDb Standard. |
| #### Indexing Metadata Context | ||
|
|
||
| A JSON object that provides indexing metadata context. The actual context data, whose structure may evolve over time as the needs of the ENSNode stack evolve. The object may include fields such as: | ||
| A data model that describes indexing metadata context. The actual context data, whose structure may evolve over time as the needs of the ENSNode stack evolve. The data model may include fields such as: |
| ## 5. enscli | ||
| ## 5. ENSDb Writers | ||
|
|
||
| Build your own indexer for ENSDb by implementing the [ENSNode Plugin](/docs/integrate/integration-options/ensnode-plugins) specifications you're interested to index. ENSDb Writers index onchain data and write it into an ENSDb instance according to the standards set by relevant ENSNode Plugins. |
| /> | ||
|
|
||
| :::note[Build your own ENSDb Reader] | ||
| Creating your own ENSDb Reader service enables you to build your own completely custom APIs and data pipeline services. See related inspiration on the [ENSDb integration options page](/docs/integrate/integration-options/ensdb). Use any programming language or framework you wish! If you'd like any help or guidance feel welcome to reach out to the NameHash team on [Telegram](https://t.me/ensnode). |
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx (1)
29-29:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix punctuation and sentence flow in Line 29.
There is an extra period after “environment variable” and an unnecessary comma in “developed, and tested”.
Proposed fix
-Each ENSNode Plugin implemented in ENSIndexer is a standalone TypeScript module that can be developed, and tested independently, while all ENSNode Plugins are deployed together as part of the single ENSIndexer service and activated via the `PLUGINS` environment variable.. The ENSNode Plugin can define its own indexed data models and indexing logic. It must include two main files: +Each ENSNode Plugin implemented in ENSIndexer is a standalone TypeScript module that can be developed and tested independently, while all ENSNode Plugins are deployed together as part of the single ENSIndexer service and activated via the `PLUGINS` environment variable. The ENSNode Plugin can define its own indexed data models and indexing logic. It must include two main files:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx` at line 29, Fix the punctuation and flow in the sentence that mentions the PLUGINS environment variable: remove the extra period after "environment variable", delete the unnecessary comma in "developed, and tested" (change to "developed and tested"), and adjust spacing so the sentence reads smoothly (e.g., end with a single period). Locate the sentence that references the "PLUGINS" environment variable and update it accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In
`@docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx`:
- Line 29: Fix the punctuation and flow in the sentence that mentions the
PLUGINS environment variable: remove the extra period after "environment
variable", delete the unnecessary comma in "developed, and tested" (change to
"developed and tested"), and adjust spacing so the sentence reads smoothly
(e.g., end with a single period). Locate the sentence that references the
"PLUGINS" environment variable and update it accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8682a2e3-0fae-475e-b6cc-606695071e94
📒 Files selected for processing (9)
docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is a followup to PR #2199, and PR #2202, and addresses the "Big Feedback" (point 11. and 17.) section the doc discussed in this thread, as well as the feedback shared in this thread.