Conversation
Please consider it still being work in progress. Many more refinements to be applied.
🦋 Changeset detectedLatest commit: 32f11d9 The changes in this PR will be included in the next version bump. This PR includes changesets to release 24 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
2 Skipped Deployments
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR expands ENSDb documentation: renames the overview page, adds concept/usage/integration docs and a mindmap, updates the Starlight sidebar to expose ENSDb sections, and tweaks CSS list styling. Changes
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 |
![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: 20
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/ensnode.io/mindmap.md`:
- Line 1: The file violates markdownlint MD041 because it begins with a code
fence (```mermaid) instead of an H1; add a top-level heading above the existing
mermaid block (e.g., a single line starting with "# " with an appropriate title)
so the document starts with an H1, keeping the existing ```mermaid ... mindmap
... ``` block unchanged below it.
In `@docs/ensnode.io/src/content/docs/ensdb/concepts/architecture.mdx`:
- Line 281: The link text "**[Schema
Version](/ensdb/concepts/glossary#schema-version) evolution**" points to a
non-existent anchor "#schema-version"; either update the link to the correct
anchor name used in the glossary (e.g., match the actual heading ID) or add the
corresponding "Schema Version" heading/anchor to the glossary so
"/ensdb/concepts/glossary#schema-version" resolves; locate the link in the
architecture.mdx content and fix the anchor target or glossary heading to make
the anchor valid.
In `@docs/ensnode.io/src/content/docs/ensdb/concepts/database-schemas.mdx`:
- Line 905: The doc text references the camelCase column name `labelName` but
the schema uses snake_case `label_name`; update the documentation sentence that
mentions `labelName` to use the exact `label_name` identifier so the column name
matches the table definition and avoids SQL copy/paste errors (ensure any other
occurrences of `labelName` in this file are replaced with `label_name` for
consistency with the table schema).
- Around line 1142-1146: The table rows mapping domain tables to the
registrations table are pointing to the wrong sub-schema ("registrars"); update
the two rows where From Sub-Schema is "ensv2" and Table is "v1_domains" and
"v2_domains" to set the To Sub-Schema to "ensv2" (so the To Table
"registrations" correctly belongs to the ensv2 sub-schema), leaving the rest of
the row (Relationship and Via) unchanged.
In `@docs/ensnode.io/src/content/docs/ensdb/concepts/glossary.mdx`:
- Around line 146-158: The glossary currently lists a non-existent key
`indexing_metadata_context`; update the table and section to match the actual
implementation in the EnsNodeMetadataKeys enum by replacing that single row with
three rows for the real keys: `ensdb_version`, `ensindexer_public_config`, and
`ensindexer_indexing_status`. Adjust the "Indexing Metadata Context" section
(rename if appropriate) to document each of those three keys individually,
describing their JSON/value shape and how they map to the ENSNode stack (e.g.,
`ensdb_version` = version string for the metadata structure,
`ensindexer_public_config` = public config for the ENSIndexer instance,
`ensindexer_indexing_status` = current indexing status object), and ensure
references to ENSIndexer/ENSDb/ENSRainbow match the writer docs and the
EnsNodeMetadataKeys enum in packages/ensdb-sdk/src/client/ensnode-metadata.ts.
In `@docs/ensnode.io/src/content/docs/ensdb/index.mdx`:
- Around line 41-43: The Mermaid graph incorrectly labels the mainnet API node;
update the label for the ENSApiMainnet node (adjacent to ENSIndexerMainnet) from
"ENSApi Sepolia instances" to a mainnet-appropriate label such as "ENSApi
Mainnet instances" so the node context matches the surrounding mainnet entries.
- Around line 209-215: The SDK snippet has a duplicated .limit(10) call and uses
the wrong schema member name; update the query built from EnsDbReader so it
calls .from(ensDbReader.ensIndexerSchema.v1_domains) (not v1Domain) and remove
the extra .limit(10) so the chain ends with a single .limit(10); ensure the call
chain on ensDbReader.ensDb.select().from(...).limit(10) is syntactically valid
with proper semicolons and line breaks.
In `@docs/ensnode.io/src/content/docs/ensdb/integrations/index.mdx`:
- Line 155: The label ENSDb["ENSDb<br/>(SQLite)"] is inconsistent with the
PostgreSQL model used elsewhere; update the label to match the PostgreSQL
variant (e.g., ENSDb["ENSDb<br/>(PostgreSQL)"] or simply ENSDb["ENSDb"]) so it
aligns with surrounding docs and avoids confusion—locate and edit the
ENSDb["ENSDb<br/>(SQLite)"] entry to the correct PostgreSQL label in the
integrations content.
- Around line 191-197: The diagram currently has Writer pointing to
ReaderGraphQL/ReaderAnalytics/ReaderCLI; change the flow so Writer writes to
ENSDb and each reader queries ENSDb. Replace the three lines "Writer -->
ReaderGraphQL/ReaderAnalytics/ReaderCLI" with a single or three lines "Writer
--> ENSDb" and ensure the reader edges remain or are expressed as "ReaderGraphQL
--> ENSDb", "ReaderAnalytics --> ENSDb", "ReaderCLI --> ENSDb" so the Writer ->
ENSDb and Reader* -> ENSDb directions are correct.
In `@docs/ensnode.io/src/content/docs/ensdb/integrations/reader.mdx`:
- Around line 320-327: The SQL example ends the triple-quoted string incorrectly
with two quotes; update the cursor.execute call (cursor.execute) so the SQL TEXT
block is properly closed with triple quotes (""") and keep the parameters tuple
unchanged; ensure the block reads SELECT ... LIMIT 100 inside a properly started
and terminated triple-quoted string to produce valid Python.
In `@docs/ensnode.io/src/content/docs/ensdb/integrations/writer.mdx`:
- Around line 337-340: The SQL snippet creates an index non-idempotently: change
the CREATE INDEX v1_domains_by_owner ON
ensindexer_mycustom.v1_domains(owner_id); statement to use the idempotent form
supported by PostgreSQL by adding IF NOT EXISTS so repeated runs don’t error;
update the example that references the index name v1_domains_by_owner and the
table ensindexer_mycustom.v1_domains accordingly in the writer.mdx docs.
- Around line 202-237: The three INSERT statements into the ensnode.metadata
table (the ones inserting keys 'ensdb_version', 'ensindexer_public_config', and
'ensindexer_indexing_status') must be made idempotent by adding an ON CONFLICT
clause on the composite primary key (ens_indexer_schema_name, key); update the
statements for the INSERTs that create these rows so they include ON CONFLICT
(ens_indexer_schema_name, key) DO UPDATE SET value = EXCLUDED.value,
value_version = EXCLUDED.value_version (or DO NOTHING if you prefer to keep
existing values), and apply the same pattern to the other two INSERTs so
rerunning the script won’t error on duplicate key violations.
- Around line 246-285: The snippet in Step 6 uses pool.query(...) but doesn't
define pool locally, so make the snippet self-contained by adding a pool
definition (e.g., create a new PG client Pool instance and import it) before its
use; ensure you import Pool from 'pg' (or reference the same pool variable you
defined earlier) and initialize it with the connection env var (e.g.,
process.env.PG_CONNECTION_STRING) so that pool.query in the loop works when the
snippet is copied in isolation.
In `@docs/ensnode.io/src/content/docs/ensdb/operations/index.mdx`:
- Around line 240-243: The metric's SQL uses an invalid call
pg_total_relation_size('ponder_sync.*'); replace it with a query that sums
pg_total_relation_size over all tables in the ponder_sync schema (e.g., select
sum of pg_total_relation_size(...) for tables where schemaname = 'ponder_sync'),
casting each table identifier to regclass (use format('%I.%I', schemaname,
tablename)::regclass) so pg_total_relation_size can accept each table; update
the Ponder Schema size metric to use this aggregated query and present the total
size (optionally formatted with pg_size_pretty) instead of the wildcard
argument.
- Around line 314-323: The Card components inside CardGrid (the entries titled
"Database Schemas", "Architecture", and "ENS Namespaces") are non-navigable and
should be replaced with Starlight's LinkCard so they become actionable; update
the JSX to use LinkCard for those three items (e.g., replace Card elements
referencing the titles "Database Schemas", "Architecture", "ENS Namespaces" with
LinkCard) and add the import for LinkCard from '@astrojs/starlight/components'
at the top of the file, and for the "ENS Namespaces" LinkCard either point it to
an existing documentation path or remove that LinkCard/create the missing doc if
no path exists.
In `@docs/ensnode.io/src/content/docs/ensdb/usage/index.mdx`:
- Line 27: Update the description string that currently reads
description="TypeScript utilities for typing-safe ENSDb access" to use the
correct phrase "type-safe" instead of "typing-safe"; locate the description
attribute in the frontmatter or metadata block and replace "typing-safe" with
"type-safe" so it reads description="TypeScript utilities for type-safe ENSDb
access".
- Around line 66-87: The example mixes CommonJS require('pg') with top-level
await (pool.query), which is invalid; fix by either converting the module to an
ES module (use import { Pool } from 'pg' and ensure the file is an ESM so
top-level await is allowed) or keep CommonJS and wrap the awaits in an async
IIFE (e.g., create an async function that creates const pool = new Pool(...) and
calls await pool.query(...)); update references to Pool, pool, and pool.query
accordingly so the example is syntactically correct for the chosen module
system.
In `@docs/ensnode.io/src/content/docs/ensdb/usage/querying.mdx`:
- Around line 155-159: The SQL example uses a malformed hex literal in the WHERE
clause; update the literal in the query that selects from
ensindexer_mainnet.labels (columns label_hash, interpreted) by removing the
underscore after the \x escape so the hex literal becomes '\xaf2caa...03cc'
instead of '\x_af2caa...03cc'.
In `@docs/ensnode.io/src/content/docs/ensdb/use-cases/index.mdx`:
- Line 73: The WHERE clause uses an invalid bytea literal '\x0x...'; replace it
with valid PostgreSQL bytea syntax such as the hex format '\\x0x...'
(double-escaped backslash in source) or use decode('0x...', 'hex') for
comparisons; update the selector comparison in the query (the WHERE e.selector =
'...') to use either e.selector = '\\x0x...' or e.selector = decode('0x...',
'hex') so PostgreSQL accepts the bytea literal.
- Around line 305-307: The snippet incorrectly treats asyncpg.add_listener as an
async context manager; replace that pattern by registering a callback via
conn.add_listener(channel, callback) where callback(connection, pid, channel,
payload) handles the event (or enqueues it into an asyncio.Queue if you need an
async consumer), and unregister with conn.remove_listener(channel, callback)
when done; update any code that assumed "async with
conn.add_listener('ens_events') as queue" to define a listener function and call
conn.add_listener('ens_events', listener) instead.
🪄 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: 267b8045-48ef-43d5-941e-841f36cdd703
📒 Files selected for processing (19)
docs/ensnode.io/config/integrations/starlight.tsdocs/ensnode.io/mindmap.mddocs/ensnode.io/src/content/docs/ensdb/concepts/architecture.mdxdocs/ensnode.io/src/content/docs/ensdb/concepts/database-schemas.mdxdocs/ensnode.io/src/content/docs/ensdb/concepts/glossary.mdxdocs/ensnode.io/src/content/docs/ensdb/concepts/index.mdxdocs/ensnode.io/src/content/docs/ensdb/concepts/indexing-lifecycle.mdxdocs/ensnode.io/src/content/docs/ensdb/index.mdxdocs/ensnode.io/src/content/docs/ensdb/integrations/index.mdxdocs/ensnode.io/src/content/docs/ensdb/integrations/reader.mdxdocs/ensnode.io/src/content/docs/ensdb/integrations/writer.mdxdocs/ensnode.io/src/content/docs/ensdb/operations/index.mdxdocs/ensnode.io/src/content/docs/ensdb/usage/ensdb-sdk/index.mdxdocs/ensnode.io/src/content/docs/ensdb/usage/ensdb-sdk/reader.mdxdocs/ensnode.io/src/content/docs/ensdb/usage/ensdb-sdk/writer.mdxdocs/ensnode.io/src/content/docs/ensdb/usage/index.mdxdocs/ensnode.io/src/content/docs/ensdb/usage/querying.mdxdocs/ensnode.io/src/content/docs/ensdb/use-cases/index.mdxdocs/ensnode.io/src/styles/starlight.css
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an initial ENSDb documentation section to the ensnode.io docs site, including conceptual overviews and practical guides, and wires it into the Starlight sidebar.
Changes:
- Introduces new ENSDb docs pages (Concepts, Usage, Integrations, Use Cases, Operations).
- Updates the ENSDb landing page from “WIP/Coming soon” to a full “Getting started” overview.
- Tweaks Starlight CSS for markdown list rendering and sidebar/pagination selector formatting.
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/ensnode.io/src/styles/starlight.css | Adjusts markdown list styling and cleans up selector formatting/spacing. |
| docs/ensnode.io/src/content/docs/ensdb/index.mdx | Replaces the ENSDb placeholder with a full getting-started overview and examples. |
| docs/ensnode.io/src/content/docs/ensdb/concepts/index.mdx | Adds Concepts landing page with links to core conceptual docs. |
| docs/ensnode.io/src/content/docs/ensdb/concepts/architecture.mdx | Documents ENSDb architecture (writer/reader pattern, schemas, server vs instance). |
| docs/ensnode.io/src/content/docs/ensdb/concepts/database-schemas.mdx | Adds comprehensive schema reference and diagrams for ENSDb. |
| docs/ensnode.io/src/content/docs/ensdb/concepts/glossary.mdx | Adds glossary of ENSDb and PostgreSQL terminology. |
| docs/ensnode.io/src/content/docs/ensdb/concepts/indexing-lifecycle.mdx | Documents backfill/following lifecycle and index behavior. |
| docs/ensnode.io/src/content/docs/ensdb/usage/index.mdx | Adds Usage landing page with language examples and links to querying/SDK docs. |
| docs/ensnode.io/src/content/docs/ensdb/usage/querying.mdx | Adds SQL querying guide (schema discovery, status checks, query patterns). |
| docs/ensnode.io/src/content/docs/ensdb/usage/ensdb-sdk/index.mdx | Adds ENSDb SDK overview page with structure and links. |
| docs/ensnode.io/src/content/docs/ensdb/usage/ensdb-sdk/reader.mdx | Adds ENSDb Reader SDK reference and usage examples. |
| docs/ensnode.io/src/content/docs/ensdb/usage/ensdb-sdk/writer.mdx | Adds ENSDb Writer SDK reference (migrations + metadata upserts). |
| docs/ensnode.io/src/content/docs/ensdb/integrations/index.mdx | Adds integrations overview (writer/reader pattern, compliance checklist). |
| docs/ensnode.io/src/content/docs/ensdb/integrations/reader.mdx | Adds “Build a Custom Reader” guide with multi-language examples. |
| docs/ensnode.io/src/content/docs/ensdb/integrations/writer.mdx | Adds “Build a Custom Writer” guide with lifecycle + schema requirements. |
| docs/ensnode.io/src/content/docs/ensdb/use-cases/index.mdx | Adds ENSDb use-cases page with example queries and patterns. |
| docs/ensnode.io/src/content/docs/ensdb/operations/index.mdx | Adds operational guidance (multitenancy, namespace isolation, backups). |
| docs/ensnode.io/mindmap.md | Adds a Mermaid mindmap capturing ENSDb conceptual structure. |
| docs/ensnode.io/config/integrations/starlight.ts | Updates sidebar nav to include ENSDb Concepts/Usage/Use Cases/Integrations/Operations sections. |
💡 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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
♻️ Duplicate comments (1)
docs/ensnode.io/src/content/docs/ensdb/index.mdx (1)
207-222:⚠️ Potential issue | 🟠 Major
EnsDbReaderconstructor signature doesn't match the actual SDK API.Per
packages/ensdb-sdk/src/client/ensdb-reader.ts, the constructor isnew EnsDbReader(config: EnsDbConfig, abstractEnsIndexerSchema)— it takes two objects ({ connectionString }and an abstract schema), not two bare strings. Users copying this snippet will get type errors. The JSDoc@examplein the SDK source is the authoritative shape.Also,
ensDbReader.ensIndexerSchema.v1Domainshould bev1_domainsto match the schema member used in the SQL examples on line 193 (this was flagged previously and is still present).🛠️ Proposed fix
import { EnsDbReader } from '@ensnode/ensdb-sdk'; +import { EnsIndexerSchema } from '@ensnode/ensdb-sdk/ensindexer-abstract'; // Connect to a specific ENSDb instance by providing its connection string and // the ENSIndexer Schema Name you want to query -const ensDbReader = new EnsDbReader(ensDbConnectionString, ensIndexerSchemaName); +const ensDbReader = new EnsDbReader( + { connectionString: ensDbConnectionString }, + { schemaName: ensIndexerSchemaName }, +); -// Get domains from the ENSIndexer Schema -const v1Domains = await - ensDbReader.ensDb.select() - .from(ensDbReader.ensIndexerSchema.v1Domain) - .limit(10); +// Get domains from the ENSIndexer Schema +const v1Domains = await ensDbReader.ensDb + .select() + .from(ensDbReader.ensIndexerSchema.v1_domains) + .limit(10); // Get indexing status -const indexingStatus = await ensDbReader.getIndexingStatusSnapshot() +const indexingStatus = await ensDbReader.getIndexingStatusSnapshot();#!/bin/bash # Confirm the actual EnsDbReader constructor signature and the schema member name used by EnsIndexer's abstract schema. fd -t f 'ensdb-reader.ts' | xargs -I{} sh -c 'echo "=== {} ==="; sed -n "1,160p" "{}"' echo "---- searching schema member names ----" rg -nP '\b(v1_domains|v1Domain)\b' --type=ts -C1🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ensnode.io/src/content/docs/ensdb/index.mdx` around lines 207 - 222, The example uses the wrong EnsDbReader signature and schema member names: replace the two-string constructor call with the correct objects (pass an EnsDbConfig-like object, e.g., { connectionString: ... }, as the first argument and the abstractEnsIndexerSchema as the second) and update any schema access from ensDbReader.ensIndexerSchema.v1Domain to ensDbReader.ensIndexerSchema.v1_domains so it matches the actual SDK symbols (refer to EnsDbReader, EnsDbConfig, and abstractEnsIndexerSchema in packages/ensdb-sdk/src/client/ensdb-reader.ts).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.letta/settings.json:
- Line 11: Remove or restrict the overly broad permission rule
"Edit(//Users/tko/dev/github/namehash/**)"; either delete this entry entirely or
replace it with a scoped pattern that only allows edits to the intended
documentation directories (e.g., specific doc paths already listed) so the rule
no longer grants write access to the entire namehash tree.
- Around line 4-6: The three Bash(...) entries containing absolute user-specific
paths should be changed to relative paths or project-root variables so they work
on any machine; update the Bash strings (e.g., the entries starting with
"Bash(mkdir -p /Users/tko/dev/github/namehash/ensnode/...") to use relative
equivalents like "Bash(mkdir -p
./docs/ensnode.io/src/content/docs/ensdb/concepts)" or use a
placeholder/project-root variable (e.g., ${PROJECT_ROOT}) consistently for each
of the three lines so they no longer reference a specific home directory.
In @.letta/settings.local.json:
- Around line 1-13: This file (.letta/settings.local.json) contains local user
session state ("lastAgent", "sessionsByServer", "lastSession") and must not be
committed; remove it from version control with git rm --cached
.letta/settings.local.json, add the pattern .letta/settings.local.json (or
.letta/) to .gitignore so it is ignored going forward, and optionally add a
template like .letta/settings.local.json.example containing placeholder keys
("lastAgent", "sessionsByServer", "lastSession") to document the schema for
other developers.
In `@docs/ensnode.io/src/content/docs/ensdb/index.mdx`:
- Around line 95-110: The prose under "Example: Multi-Instance Server" and the
Mermaid diagram use inconsistent environment names (e.g., "sepolia"/"ENSDb
Sepolia instance" and "ens-test-env"/"ENSDb ENS Test Env instance") versus the
Quick Start variable names (`ensdb_mainnet`, `ensdb_testnet`, `ensdb_devnet`);
pick one naming convention (for example: mainnet/sepolia/devnet or
mainnet/testnet/devnet) and make them consistent by updating the paragraph text,
the Mermaid node labels (e.g., change "ENSDb Sepolia instance" and "ENSDb ENS
Test Env instance"), and any Quick Start references (`ensdb_mainnet`,
`ensdb_testnet`, `ensdb_devnet`) so the same names appear everywhere. Ensure the
chosen names are applied to the heading "Example: Multi-Instance Server", the
bulleted examples, and the Mermaid nodes so readers can unambiguously map each
environment to its database instance.
- Line 165: The sentence contains a stray word "you" ("assume you that ENSDb
instances are served") which breaks grammar; remove "you" and change the phrase
to "assume that ENSDb instances are served" so the sentence reads cleanly and
grammatically correct in the ENSDb docs example.
---
Duplicate comments:
In `@docs/ensnode.io/src/content/docs/ensdb/index.mdx`:
- Around line 207-222: The example uses the wrong EnsDbReader signature and
schema member names: replace the two-string constructor call with the correct
objects (pass an EnsDbConfig-like object, e.g., { connectionString: ... }, as
the first argument and the abstractEnsIndexerSchema as the second) and update
any schema access from ensDbReader.ensIndexerSchema.v1Domain to
ensDbReader.ensIndexerSchema.v1_domains so it matches the actual SDK symbols
(refer to EnsDbReader, EnsDbConfig, and abstractEnsIndexerSchema in
packages/ensdb-sdk/src/client/ensdb-reader.ts).
🪄 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: 8e7c0404-9c96-4c9d-9365-6e9a52492543
📒 Files selected for processing (4)
.letta/.lettaignore.letta/settings.json.letta/settings.local.jsondocs/ensnode.io/src/content/docs/ensdb/index.mdx
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated 8 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
260
to
265
| #starlight__sidebar>div>ul>li:not(:first-child):not(:last-child)::before { | ||
| content: ""; | ||
| position: absolute; | ||
| left: 8px; /* X-position of the vertical line */ | ||
| left: 8px; | ||
| /* X-position of the vertical line */ | ||
| top: 0; |
There was a problem hiding this comment.
The same selector #starlight__sidebar>div>ul>li:not(:first-child):not(:last-child)::before is defined twice (here and again a few lines below) just to override height. Consider merging into a single rule to avoid duplication and make future edits less error-prone.
![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
Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
lightwalker-eth
approved these changes
Apr 29, 2026
Member
lightwalker-eth
left a comment
lightwalker-eth
left a comment
There was a problem hiding this comment.
@tk-o Love it 🚀 A few small suggestions happy to go live with this 🙌
Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com>
Comment on lines
+152
to
+182
| #### `events` | ||
|
|
||
| | Column | Type | Nullable | Description | | ||
| |--------|------|----------|-------------| | ||
| | `id` | `text` | no | Ponder's event ID. Primary key. | | ||
| | `chainId` | `integer` | no | Chain the event was emitted on. | | ||
| | `blockNumber` | `numeric(78)` | no | Block number. | | ||
| | `blockHash` | `text` | no | Block hash. | | ||
| | `timestamp` | `numeric(78)` | no | Block timestamp. | | ||
| | `transactionHash` | `text` | no | Transaction hash. | | ||
| | `transactionIndex` | `integer` | no | Index of the transaction within the block. | | ||
| | `from` | `text` | no | Transaction sender address. | | ||
| | `to` | `text` | yes | Transaction recipient address. A `null` value means this was a contract-deployment transaction. | | ||
| | `address` | `text` | no | Address of the contract that emitted the log. | | ||
| | `logIndex` | `integer` | no | Index of the log within the transaction. | | ||
| | `selector` | `text` | no | Event topic[0] (the event signature hash). | | ||
| | `topics` | `text[]` | no | All log topics. | | ||
| | `data` | `text` | no | Log data. | | ||
|
|
||
| **Indexes:** `selector`, `from`, `timestamp`. | ||
|
|
||
| #### `domain_events` | ||
|
|
||
| Join table linking a `domain` to its associated `events`. | ||
|
|
||
| | Column | Type | Nullable | | ||
| |--------|------|----------| | ||
| | `domainId` | `text` | no | | ||
| | `eventId` | `text` | no | | ||
|
|
||
| **Primary key:** `(domainId, eventId)`. |
Contributor
There was a problem hiding this comment.
In Ponder v0.9+, JavaScript property names like domainId, eventId, chainId, blockNumber, transactionHash, etc. are automatically converted to snake_case when stored in PostgreSQL (domain_id, event_id, chain_id, block_number, transaction_hash). The column name tables throughout this page use the TypeScript property names, which means any developer who writes a raw SQL query using the documented names will get column does not exist errors.
For example:
-- This will FAIL
SELECT chainId, blockNumber FROM ensindexer_mainnet.events LIMIT 10;
-- Correct SQL (snake_case column names)
SELECT chain_id, block_number FROM ensindexer_mainnet.events LIMIT 10;This affects every camelCase column in the events, domain_events, resolver_events, domains, registrations, renewals, registries, and other ENSIndexer Schema tables. Consider documenting the actual PostgreSQL column names (snake_case) in all column reference tables on this page, or adding a note at the top clarifying that Ponder maps TypeScript camelCase property names to snake_case SQL column names.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,41 @@ | |||
| --- | |||
| title: Reference Implementations | |||
| description: A directory of reference implementation of the ENSDb standard. | |||
There was a problem hiding this comment.
The page description has a grammar issue: “A directory of reference implementation …” should be plural (“implementations”) or rephrased (“a reference implementation directory …”).
Suggested change
| description: A directory of reference implementation of the ENSDb standard. | |
| description: A directory of reference implementations of the ENSDb standard. |
Comment on lines
+53
to
+56
| SELECT value -> 'indexingStatus' FROM "ensnode"."metadata" | ||
| WHERE ens_indexer_schema_name = 'ensindexer_mainnet' | ||
| AND key = 'indexing_metadata_context' | ||
| AND value -> 'indexingStatus' -> 'omnichainSnapshot' ->> 'omnichainStatus' = 'omnichain-backfill'; |
There was a problem hiding this comment.
The query filters on key = 'indexing_metadata_context', but the current ENSDb SDK / ENSNode schema in this repo defines metadata keys like ensdb_version, ensindexer_public_config, and ensindexer_indexing_status (see packages/ensdb-sdk/src/client/ensnode-metadata.ts). Either update this example to match the currently supported keys, or add an explicit note that this query only applies after the metadata-key refactor (and reference the minimum version/PR).
Suggested change
| SELECT value -> 'indexingStatus' FROM "ensnode"."metadata" | |
| WHERE ens_indexer_schema_name = 'ensindexer_mainnet' | |
| AND key = 'indexing_metadata_context' | |
| AND value -> 'indexingStatus' -> 'omnichainSnapshot' ->> 'omnichainStatus' = 'omnichain-backfill'; | |
| SELECT value FROM "ensnode"."metadata" | |
| WHERE ens_indexer_schema_name = 'ensindexer_mainnet' | |
| AND key = 'ensindexer_indexing_status' | |
| AND value -> 'omnichainSnapshot' ->> 'omnichainStatus' = 'omnichain-backfill'; |
Comment on lines
+27
to
+50
| import { EnsDbReader, IndexingMetadataContextStatusCodes } from '@ensnode/ensdb-sdk'; | ||
| import { eq } from 'drizzle-orm'; | ||
|
|
||
| // Connect to a specific ENSDb instance by providing its connection string and | ||
| // the ENSIndexer Schema Name you want to query | ||
| const ensDbReader = new EnsDbReader(ensDbConnectionString, ensIndexerSchemaName); | ||
| const { ensDb, ensIndexerSchema } = ensDbReader; | ||
|
|
||
| // Get ENS V1 domains from the ENSIndexer Schema | ||
| const v1Domains = await ensDb | ||
| .select() | ||
| .from(ensIndexerSchema.domain) | ||
| .where(eq(ensIndexerSchema.domain.type, "ENSv1Domain")); | ||
|
|
||
| // Get ENS V2 domains from the ENSIndexer Schema | ||
| const v2Domains = await ensDb | ||
| .select() | ||
| .from(ensIndexerSchema.domain) | ||
| .where(eq(ensIndexerSchema.domain.type, "ENSv2Domain")); | ||
|
|
||
|
|
||
| // Get indexing status snapshot | ||
| const indexingMetadataContext = await ensDbReader.getIndexingMetadataContext(); | ||
| if (indexingMetadataContext.statusCode === IndexingMetadataContextStatusCodes.Initialized) { |
There was a problem hiding this comment.
IndexingMetadataContextStatusCodes does not appear to be exported by @ensnode/ensdb-sdk in this repo (the package exports are ensdb-config, ensdb-reader, ensdb-writer, ensnode-metadata, etc.). This example won’t compile as written unless the SDK API has changed; update the import / API usage to match the published exports, or gate the snippet behind an explicit “requires version X / PR Y” note.
Suggested change
| import { EnsDbReader, IndexingMetadataContextStatusCodes } from '@ensnode/ensdb-sdk'; | |
| import { eq } from 'drizzle-orm'; | |
| // Connect to a specific ENSDb instance by providing its connection string and | |
| // the ENSIndexer Schema Name you want to query | |
| const ensDbReader = new EnsDbReader(ensDbConnectionString, ensIndexerSchemaName); | |
| const { ensDb, ensIndexerSchema } = ensDbReader; | |
| // Get ENS V1 domains from the ENSIndexer Schema | |
| const v1Domains = await ensDb | |
| .select() | |
| .from(ensIndexerSchema.domain) | |
| .where(eq(ensIndexerSchema.domain.type, "ENSv1Domain")); | |
| // Get ENS V2 domains from the ENSIndexer Schema | |
| const v2Domains = await ensDb | |
| .select() | |
| .from(ensIndexerSchema.domain) | |
| .where(eq(ensIndexerSchema.domain.type, "ENSv2Domain")); | |
| // Get indexing status snapshot | |
| const indexingMetadataContext = await ensDbReader.getIndexingMetadataContext(); | |
| if (indexingMetadataContext.statusCode === IndexingMetadataContextStatusCodes.Initialized) { | |
| import { EnsDbReader } from '@ensnode/ensdb-sdk/ensdb-reader'; | |
| import { eq } from 'drizzle-orm'; | |
| // Connect to a specific ENSDb instance by providing its connection string and | |
| // the ENSIndexer Schema Name you want to query | |
| const ensDbReader = new EnsDbReader(ensDbConnectionString, ensIndexerSchemaName); | |
| const { ensDb, ensIndexerSchema } = ensDbReader; | |
| // Get ENS V1 domains from the ENSIndexer Schema | |
| const v1Domains = await ensDb | |
| .select() | |
| .from(ensIndexerSchema.domain) | |
| .where(eq(ensIndexerSchema.domain.type, "ENSv1Domain")); | |
| // Get ENS V2 domains from the ENSIndexer Schema | |
| const v2Domains = await ensDb | |
| .select() | |
| .from(ensIndexerSchema.domain) | |
| .where(eq(ensIndexerSchema.domain.type, "ENSv2Domain")); | |
| // Get indexing status snapshot when available | |
| const indexingMetadataContext = await ensDbReader.getIndexingMetadataContext(); | |
| if (indexingMetadataContext.indexingStatus) { |
Comment on lines
+140
to
+152
| The `value` column stores a JSON object which structure may evolve over time. To track this, the JSON object is guaranteed to always include a `version` field indicating the version of the structure. This allows for future-proofing as the metadata needs evolve. | ||
|
|
||
| ### Metadata Keys | ||
|
|
||
| The `key` column identifies the type of metadata: | ||
|
|
||
| | Key | Description | | ||
| |-----|-------------| | ||
| | `indexing_metadata_context` | [Indexing metadata context](#indexing-metadata-context) of the [ENSIndexer instance](#ensindexer-instance) | | ||
|
|
||
| #### 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: |
There was a problem hiding this comment.
This glossary section lists only indexing_metadata_context as a metadata key and states the JSON value is always guaranteed to include a version field. That’s not true for the current metadata model in this repo (e.g. ensdb_version is a plain string, and other keys exist). Please either document the full current key set/shape, or add an explicit “applies after metadata context refactor” note so readers don’t copy queries/snippets that won’t work on current ENSDb instances.
Suggested change
| The `value` column stores a JSON object which structure may evolve over time. To track this, the JSON object is guaranteed to always include a `version` field indicating the version of the structure. This allows for future-proofing as the metadata needs evolve. | |
| ### Metadata Keys | |
| The `key` column identifies the type of metadata: | |
| | Key | Description | | |
| |-----|-------------| | |
| | `indexing_metadata_context` | [Indexing metadata context](#indexing-metadata-context) of the [ENSIndexer instance](#ensindexer-instance) | | |
| #### 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: | |
| The `value` column stores metadata for the given `key`. Its shape is key-specific and may be a scalar value (for example, a plain string such as `ensdb_version`) or a structured value such as a JSON object. Do not assume every metadata value is a JSON object or that every value includes a `version` field. | |
| ### Metadata Keys | |
| The `key` column identifies the type of metadata. `indexing_metadata_context` is one current key, but it is not the only one; other keys also exist (for example, `ensdb_version`). | |
| | Key | Description | | |
| |-----|-------------| | |
| | `indexing_metadata_context` | [Indexing metadata context](#indexing-metadata-context) of the [ENSIndexer instance](#ensindexer-instance) | | |
| | `ensdb_version` | ENSDb version metadata; currently stored as a plain string value rather than a versioned JSON object | | |
| | Other keys | Additional metadata entries may exist; always inspect the current schema/data model before relying on a specific shape | | |
| #### Indexing Metadata Context | |
| This subsection describes the structured value stored for the `indexing_metadata_context` key. It does **not** apply to every metadata row in the current model. If a metadata-context refactor standardizes more keys onto this shape in the future, update this glossary accordingly. | |
| A JSON object that provides indexing metadata context. The actual context data may evolve over time as the needs of the ENSNode stack evolve. The object may include fields such as: |
2 tasks
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.
Lite PR
Tip: Review docs on the ENSNode PR process
Summary
Why
Testing
Notes for Reviewer (Optional)
mainbranch as is.Pre-Review Checklist (Blocking)