perf(ensindexer): unblock Ponder prefetch on hot tables

[shrugs]

Reviewer Focus (Read This First)

1. packages/enssdk/src/lib/ids.ts — every id constructor switches from CAIP-style mixed : / / delimiters to dash-joined tuples. This is a wire-format change for every public id type. External consumers that string-parse or pattern-match against ids will see different shapes; the in-tree code treats them as opaque strings.
2. apps/ensindexer/src/lib/protocol-acceleration/migrated-node-db-helpers.ts block comment + the two-table layout
3. Schema split — pulling the migration-status tables into their own migrated-nodes.schema.ts is mechanical, but perhaps should still live in protocol acceleration because that's the plugin that manages the tables?

Problem & Motivation

• Ponder's indexing-cache prefetch path predicts hot-table reads ahead of each event by deriving the lookup key from event args. Its profile-pattern matcher only does direct equality and single-level string-delimiter splits — it can't match across mixed delimiters and can't invert keccak.
• CAIP-style ids use both : and /, which the matcher won't decompose, so every prefetch attempt on Domain / Registry / Resolver / etc. silently failed.
• Separately, migrated_nodes was keyed by post-namehash node, which the matcher also can't recover from event args. Run D measured 0% prefetch share on the table even though every ENSv1RegistryOld read consults it.
• Net effect: reads on the busiest tables in the indexer were paying full DB round-trip cost instead of riding the in-memory cache that Ponder is supposed to populate ahead of each event batch.

What Changed (Concrete)

1. enssdk/src/lib/ids.ts: every id constructor now joins its components with - via _stringifyAccountId
2. migrated_nodes table renamed to migrated_nodes_by_parent and re-keyed from (node) to composite (parentNode, labelHash).
3. New sibling table migrated_nodes_by_node keyed by node for the four ENSv1RegistryOld handlers (Transfer / NewTTL / NewResolver) that emit node only.
4. migrateNode helper writes both tables at once; nodeIsMigratedByParentAndLabel and nodeIsMigrated read from whichever table matches the calling handler's event payload.
5. Schema split: migratedNodeByParent + migratedNodeByNode moved into packages/ensdb-sdk/src/ensindexer-abstract/migrated-nodes.schema.ts, re-exported from ensindexer-abstract/index.ts. Removed from protocol-acceleration.schema.ts.

Design & Planning

The id format change came out of investigating Ponder's prefetch path in ponder/dist/esm/indexing-store/profile.js — specifically the delimiter splitter that only splits on a single delimiter character per call. Confirmed empirically in Run D (2026-04-27): dash-delimited ids pushed hot tables to 80–100% prefetch share, up from 0% under CAIP. The migration table re-key followed once the dominant migrated_nodes outlier was identified in Run D's per-table breakdown.

Alternatives considered for migrated_nodes:

• Keep single-table keyed by node → 0% prefetch on the hot read path.
• Single-table keyed by (parentNode, labelHash) → flips the floor but breaks the four node-only read sites.
• Two-table layout with paired writes → chosen. Cost is one extra INSERT ON CONFLICT DO NOTHING per migration write; storage roughly doubles for this table (~1GB → ~2GB on mainnet today).

Self-Review

• Bugs caught: none
• Logic simplified: none
• Naming / terminology improved: nodeIsMigrated(node) vs nodeIsMigratedByParentAndLabel(parentNode, labelHash) — names match what the call site actually passes; tables follow migrated_nodes_by_* pattern
• Dead or unnecessary code removed: none

Cross-Codebase Alignment

• Deferred alignment: re-keying domain_events child writes — flagged in debug ensv2 indexing slowness #1982 as suspected-but-likely-not-worth.

Downstream & Consumer Impact

• Public APIs affected: every id type's wire format is different. External consumers of the GraphQL/REST API that compare ids across deploys, persist them, or pattern-match on the CAIP shape will need to update.
• Docs updated: block comment in migrated-node-db-helpers.ts is the canonical reference for the two-table design; ids.ts will carry a block comment explaining the prefetch trade-off.
• Naming decisions worth calling out: migratedNodeByParent / migratedNodeByNode — symmetric naming makes the keyed-by intent explicit.

Testing Evidence

• Typecheck clean across ensindexer, ensdb-sdk, enssdk, ensapi. pnpm lint clean.
• manual testing runs
• Known gaps: no unit tests for the two-table consistency invariant. Relying on the block comment
• What reviewers have to reason about manually: that no in-tree caller depends on the CAIP-shaped id format.

Scope Reductions

• Did not re-key domain_events / resolver_events, flagged in debug ensv2 indexing slowness #1982 as marginal headroom vs. material code complexity.

Risk Analysis

• Storage cost. Migration-status footprint roughly doubles on mainnet (~1GB → ~2GB). Acceptable for the prefetch win.

• External id consumers. Callers outside this monorepo that pattern-match against the CAIP id shape will see a different format. None known.

• Mitigations or rollback options: the change is a single commit so revert is mechanical

• Named owner if this causes problems: @shrugs

Pre-Review Checklist (Blocking)

• I reviewed every line of this diff and understand it end-to-end
• I'm prepared to defend this PR line-by-line in review
• I'm comfortable being the on-call owner for this change
• Relevant changesets are included (or explicitly not required)

[changeset-bot]

🦋 Changeset detected

Latest commit: 01f2fa3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 24 packages

Name	Type
@ensnode/ensdb-sdk	Major
enssdk	Major
ensapi	Major
ensindexer	Major
@ensnode/integration-test-env	Major
ensadmin	Major
ensrainbow	Major
@ensnode/enskit-react-example	Patch
@namehash/ens-referrals	Major
enskit	Major
@ensnode/ensnode-react	Major
@ensnode/ensnode-sdk	Major
@ensnode/ensrainbow-sdk	Major
@namehash/namehash-ui	Major
fallback-ensapi	Major
@docs/ensnode	Major
@docs/ensrainbow	Major
enscli	Major
ensskills	Major
@ensnode/datasources	Major
@ensnode/ponder-sdk	Major
@ensnode/ponder-subgraph	Major
@ensnode/shared-configs	Major
@ensnode/ensindexer-perf-testing	Major

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
admin.ensnode.io	Ready	Preview, Comment	Apr 30, 2026 4:30pm
ensnode.io	Ready	Preview, Comment	Apr 30, 2026 4:30pm
ensrainbow.io	Ready	Preview, Comment	Apr 30, 2026 4:30pm

[coderabbitai]

Warning

Rate limit exceeded

@shrugs has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 51 minutes and 46 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: d28c9b3c-3459-493b-a663-f29a21d2e2d7

📥 Commits

Reviewing files that changed from the base of the PR and between ab4a94e and 01f2fa3.

📒 Files selected for processing (8)

• apps/ensindexer/src/lib/get-this-account-id.ts
• apps/ensindexer/src/plugins/ensv2/handlers/ensv2/ETHRegistrar.ts
• docker/docker-compose.orchestrator.yml
• docs/ensnode.io/src/content/docs/ensdb/concepts/database-schemas.mdx
• packages/ensdb-sdk/src/ensindexer-abstract/migrated-nodes.schema.ts
• packages/enssdk/src/lib/ids.ts
• packages/enssdk/src/lib/types/ensv2.ts
• packages/integration-test-env/src/orchestrator.ts

📝 Walkthrough

Walkthrough

Split ENS migration tracking into two onchain tables keyed by (parentNode,labelHash) and node; add helpers to read/write both tables; remove legacy registry-migration-status; update ENSv1 handlers to use parent+label lookups; change composite ID constructors to dash-delimited format.

Changes

Cohort / File(s)	Summary
Changesets /.changeset/ensdb-sdk-migrated-nodes-split.md, /.changeset/enssdk-dash-delimited-ids.md	Add metadata documenting the migrated-nodes schema split and the breaking switch to dash-delimited composite IDs.
Schema: migrated nodes packages/ensdb-sdk/src/ensindexer-abstract/migrated-nodes.schema.ts, packages/ensdb-sdk/src/ensindexer-abstract/index.ts	Add two onchain tables: migrated_nodes_by_parent (composite pk: parentNode+labelHash) and migrated_nodes_by_node (pk: node); re-export new schema.
Remove legacy schema packages/ensdb-sdk/src/ensindexer-abstract/protocol-acceleration.schema.ts	Delete the previous migrated_nodes table definition.
Migration helpers apps/ensindexer/src/lib/protocol-acceleration/migrated-node-db-helpers.ts, apps/ensindexer/src/lib/protocol-acceleration/registry-migration-status.ts	Add helpers: nodeIsMigratedByParentAndLabel, nodeIsMigrated, migrateNode (writes both tables idempotently, enforces root-chain); remove old registry-migration-status module.
Handler updates apps/ensindexer/src/plugins/ensv1/handlers/ensv1/ENSv1Registry.ts, apps/ensindexer/src/plugins/protocol-acceleration/handlers/ENSv1Registry.ts	Update handlers to call nodeIsMigratedByParentAndLabel(context, parentNode, labelHash) and adjust imports to new helpers (no subdomain derivation in NewOwner).
ID format changes packages/enssdk/src/lib/ids.ts	Refactor ID utilities to emit dash-delimited composite IDs, remove CAIP stringifiers, rename makeStorageId parameter.
Dev/test infra packages/integration-test-env/package.json, packages/integration-test-env/src/orchestrator.ts, docker/docker-compose.orchestrator.yml	Add viem dep, update orchestrator to aggressively tear down volumes and include an initial down -v phase; inline/adjust Postgres service and healthcheck in compose file.

Sequence Diagram(s)

sequenceDiagram
  participant Event as ENSv1RegistryOld Event
  participant Handler as ENS Indexer Handler
  participant Helper as MigratedNode DB Helper
  participant DB as ENSIndexer Onchain Tables

  Event->>Handler: NewOwner(parentNode, labelHash, ...)
  Handler->>Helper: nodeIsMigratedByParentAndLabel(context,parentNode,labelHash)
  Helper->>DB: SELECT FROM migrated_nodes_by_parent WHERE (parentNode,labelHash)
  alt found
    DB-->>Helper: exists
    Helper-->>Handler: true
    Handler-->>Event: return (ignore event)
  else not found
    DB-->>Helper: not found
    Helper-->>Handler: false
    Handler->>Handler: proceed -> handleNewOwner(...)
    Handler->>Helper: migrateNode(context,parentNode,labelHash) [when migration recorded]
    Helper->>DB: INSERT into migrated_nodes_by_parent & migrated_nodes_by_node (onConflictDoNothing)
    DB-->>Helper: ack
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• perf(ensv2): address label-heal and DB-lookup hotspots #1989 — Related changes to registry migration-status and nodeIsMigrated behaviors; overlaps migration-status replacement.
• ENSDb SDK: group database schema objects #1778 — Adjusts/enhances ENSIndexer export surface; adding and re-exporting migrated-nodes.schema intersects this export consolidation.
• Omnigraph Refactor (cont) #1857 — Changes to ENS ID utilities; closely related to the dash-delimited ID refactor in packages/enssdk/src/lib/ids.ts.

Poem

🐰 I hopped where nodes were once a single row,
split by parent and label so lookups flow.
Dashes stitch IDs in a neat little line,
helpers write both, so reads stay fine. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly summarizes the main performance objective: unblocking Ponder's prefetch mechanism on hot database tables.
Description check	✅ Passed	Description includes all required sections (Summary, Why, Testing, Notes for Reviewer) with detailed context. However, the PR template requires a Pre-Review Checklist with blocking items, which is completed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/delimited-ids

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 51 minutes and 46 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR addresses two independent Ponder prefetch failures: (1) all composite ids switch from CAIP-style mixed : / / delimiters to uniform dash-delimited tuples, which is the only shape Ponder's profile-pattern matcher can decompose; (2) migrated_nodes is split into two tables keyed by (parentNode, labelHash) and by node respectively, allowing each of the four ENSv1RegistryOld handler types to address whichever table key matches its event payload. Additional changes fix an address-normalization gap in ETHRegistrar and harden the integration test environment with ephemeral postgres ports and volume cleanup between runs. The id format change is a documented, intentional temporary trade-off tracked in issue #2034.

Confidence Score: 5/5

Safe to merge — no P0 or P1 issues found; all logic is correct and well-documented.

The implementation correctly solves both prefetch problems: dash-delimited ids remove the CAIP delimiter ambiguity, and the two-table migration layout gives each event handler an addressable key. The two-table write is idempotent and consistent within Ponder's transactional flush model. The ETHRegistrar address-normalization fix is correct. The only finding is a P2 suggestion to align the testcontainers wait strategy with the newly-added healthcheck.

packages/integration-test-env/src/orchestrator.ts — minor: wait strategy could leverage the new healthcheck.

Important Files Changed

Filename	Overview
packages/enssdk/src/lib/ids.ts	Replaces CAIP-style mixed-delimiter ids with uniform dash-delimited tuples; change is intentional, well-documented, and safe because no component (chainId, address, node, labelHash, storageId, numeric indexes) ever contains a dash.
apps/ensindexer/src/lib/protocol-acceleration/migrated-node-db-helpers.ts	New two-table migration-status helper; write path correctly computes node via makeSubdomainNode before inserting into both tables; read paths each target the table whose key matches their calling event's args; idempotent via onConflictDoNothing.
packages/ensdb-sdk/src/ensindexer-abstract/migrated-nodes.schema.ts	New schema file defining migratedNodeByParent (composite PK on parentNode+labelHash) and migratedNodeByNode (PK on node); correctly extracted from protocol-acceleration.schema.ts and re-exported from the index.
apps/ensindexer/src/plugins/ensv2/handlers/ensv2/ETHRegistrar.ts	Correctly wraps the readContract result in toNormalizedAddress; viem returns checksummed addresses that would otherwise mismatch the NormalizedAddress constraint.
docker/docker-compose.orchestrator.yml	Inlines ensdb service with ephemeral port 0:5432 to avoid collisions with host postgres; adds pg_isready healthcheck; removes container_name so testcontainers assigns a unique name.
packages/integration-test-env/src/orchestrator.ts	Updates container reference from ensdb to ensdb-1, adds volume cleanup on teardown, and sets devnet chain ID via anvil_setChainId; wait strategy for ensdb-1 still uses forListeningPorts rather than the now-available forHealthCheck.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["ENSv1Registry(Old)#NewOwner\n(parentNode, labelHash)"] -->|"migrateNode(parentNode, labelHash)"| B["migratedNodeByParent\nPK: (parentNode, labelHash)"]
    A -->|"makeSubdomainNode → node\nmigrateNode writes both"| C["migratedNodeByNode\nPK: node"]

    D["ENSv1RegistryOld#NewOwner\n(parentNode, labelHash)"] -->|"nodeIsMigratedByParentAndLabel"| B
    E["ENSv1RegistryOld#Transfer\n(node)"] -->|"nodeIsMigrated"| C
    F["ENSv1RegistryOld#NewTTL\n(node)"] -->|"nodeIsMigrated"| C
    G["ENSv1RegistryOld#NewResolver\n(node)"] -->|"nodeIsMigrated"| C

    style B fill:#d4edda
    style C fill:#d4edda

Loading

_{Reviews (8): Last reviewed commit: "fix(enssdk): drop AccountIdString brand ..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR targets a Ponder indexing performance bottleneck by making composite IDs and migration-status lookups decomposable by Ponder’s profile matcher, enabling prefetch on hot tables in ensindexer.

Changes:

• Switched enssdk ID constructors from CAIP-style mixed delimiters to single --delimited tuple IDs.
• Split ENSv1 registry-migration tracking into two tables keyed by (parentNode,labelHash) and by node, with paired writes and payload-matching reads.
• Extracted migrated-node schema into its own ensdb-sdk schema module and re-exported it via ensindexer-abstract.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/enssdk/src/lib/ids.ts	Changes all exported ID constructors to --joined tuples to make keys prefetch-profileable.
packages/ensdb-sdk/src/ensindexer-abstract/protocol-acceleration.schema.ts	Removes the legacy single-table migrated_nodes schema from this module.
packages/ensdb-sdk/src/ensindexer-abstract/migrated-nodes.schema.ts	Adds new two-table migrated-node schema (*_by_parent, *_by_node).
packages/ensdb-sdk/src/ensindexer-abstract/index.ts	Re-exports the new migrated-nodes schema module.
apps/ensindexer/src/plugins/protocol-acceleration/handlers/ENSv1Registry.ts	Updates migration writes to the new (parentNode,labelHash) helper API.
apps/ensindexer/src/plugins/ensv2/handlers/ensv1/ENSv1Registry.ts	Updates migration reads to use payload-matching lookup helpers.
apps/ensindexer/src/lib/protocol-acceleration/registry-migration-status.ts	Removes the old single-table migration status helper.
apps/ensindexer/src/lib/protocol-acceleration/migrated-node-db-helpers.ts	Introduces new two-table read/write helpers with rationale documentation.
.changeset/enssdk-dash-delimited-ids.md	Changeset documenting the public enssdk ID wire-format change.
.changeset/ensdb-sdk-migrated-nodes-split.md	Changeset documenting the ensdb-sdk migrated-nodes table split/rekey.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shrugs]

@greptile review

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.