{"id":43395265,"url":"https://github.com/namehash/ens-subgraph-transition-tools","last_synced_at":"2026-02-02T14:25:26.187Z","repository":{"id":272646717,"uuid":"913510297","full_name":"namehash/ens-subgraph-transition-tools","owner":"namehash","description":"Tooling to confirm equivalency of ENSNode with the ENS Subgraph.","archived":false,"fork":false,"pushed_at":"2025-12-23T18:29:58.000Z","size":5031,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-25T08:42:24.355Z","etag":null,"topics":["ens","ponder","subgraph"],"latest_commit_sha":null,"homepage":"https://ensnode.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/namehash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-07T20:31:13.000Z","updated_at":"2025-12-23T18:30:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"fc0801f1-9044-4fae-b4ce-64730982ac7c","html_url":"https://github.com/namehash/ens-subgraph-transition-tools","commit_stats":null,"previous_names":["namehash/ens-subgraph-transition-tools"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/namehash/ens-subgraph-transition-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fens-subgraph-transition-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fens-subgraph-transition-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fens-subgraph-transition-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fens-subgraph-transition-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/namehash","download_url":"https://codeload.github.com/namehash/ens-subgraph-transition-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namehash%2Fens-subgraph-transition-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29012920,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T12:48:30.580Z","status":"ssl_error","status_checked_at":"2026-02-02T12:46:38.384Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ens","ponder","subgraph"],"created_at":"2026-02-02T14:25:24.901Z","updated_at":"2026-02-02T14:25:26.177Z","avatar_url":"https://github.com/namehash.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ENS Subgraph Transition Tools\n\nThis project provides a suite of tools for verifying that [ENSNode](https://github.com/namehash/ensnode) is a reliable replacement for the ENS Subgraph.\n\n- **Snapshot Equivalency Tool**: 1:1 data\n- **Resolution Equivalency Tool**: 1:1 resolution responses\n\n## Install\n\n```bash\ngit clone https://github.com/namehash/ens-subgraph-transition-tools\ncd ens-subgraph-transition-tools\nbun install\n```\n\n## Snapshot Equivalency Tool (`snapshot-eq`)\n\n\u003e appoximates a database dump \u0026 diff, but via the graphql api: it iterates over relevant top-level collection queries, paginating over all records compares their responses to highlight discrepancies.\n\nconfigure via env variables or `.env.local` at root of project:\n- `ENSNODE_API_URL` — ex: `http://localhost:42069`\n  - must be an ENSNode instance that provies a ponder-native api endpoint at `/ponder` and a subgraph-compatible endpoint at `/subgraph`\n- `SUBGRAPH_API_KEY`\n  - https://thegraph.com/studio/apikeys\n- `DATABASE_URL`\n  - used for `CLUSTER`ing an ENSIndexer index before snapshotting, same value as ENSIndexer's `DATABASE_URL`\n\ncommands, (run from `tools/snapshot-eq`):\n- `bun start --help`\n- `bun start snapshot \u003cblockheight\u003e \u003censnode|subgraph\u003e [--deployment=(mainnet|sepolia|holesky)]`\n  - takes a 'snapshot' of the indexer at the provided blockheight by iterating over all pages of resources, persisting responses to `snapshots/`\n  - if ensnode, code waits for the indexer to be ready at that blockheight and CLUSTERs the `public` schema\n  - if subgraph, timetravel queries are used to fetch data\n- `bun start clean \u003cblockheight\u003e \u003censnode|subgraph\u003e [--deployment=(mainnet|sepolia|holesky)]`\n  - deletes the specific `snapshots/` directory\n- `bun start diff \u003cblockheight\u003e [--deployment=(mainnet|sepolia|holesky)]`\n  - using subgraph responses as the source of truth, compares snapshots and prints any differences between them\n\n### Snapshot Example Usage\n\nThese commands will snapshot ENSNode configured with the eth plugin reading from the mainnet ENS deployment, producing a 1:1 Subgraph-compatible index.\n\n```bash\n# 0. start in the snapshot-eq tool directory\ncd tools/snapshot-eq\n\n# 1. acquire subgraph snapshot via Snapshot Archives (below) OR snapshot it yourself:\nSUBGRAPH_API_KEY=xyz \\\nbun start snapshot --deployment mainnet 21921222 subgraph\n\n# 2. clean the existing mainnet ensnode snapshot directory\nbun start clean --deployment mainnet 21921222 ensnode\n\n# 3. have ENSNode running with ENSIndexer like so:\nDATABASE_SCHEMA=public \\\nENS_DEPLOYMENT_CHAIN=mainnet \\\nACTIVE_PLUGINS=subgraph \\\nHEAL_REVERSE_ADDRESSES=false \\\nEND_BLOCK=21921222 \\\npnpm run dev --disable-ui\n\n# 2. run the snapshot tool\n# NOTE: it will wait for ENSNode to be at that block, CLUSTER it, and snapshot it\nENSNODE_URL=http://localhost:42069 \\\nDATABASE_URL=postgresql://postgres:password@127.0.0.1/ponder \\\nbun start snapshot --deployment mainnet 21921222 ensnode\n\n# 4. diff the two snapshots\nbun start diff --deployment mainnet 21921222\n```\n\nNOTE: somtimes the subgraph returns **incorrect** responses, in particular for event `id`s — if you see many event id mismatches (especially off-by-ones) simply delete the offending subgraph snapshot and re-snapshot like:\n\n```bash\nrm ../../snapshots/mainnet/21921222/subgraph/Domains_4192000_15769084310.json\nSUBGRAPH_API_KEY=xyz bun start snapshot --deployment mainnet 21921222 subgraph\n```\n\nNOTE: we're running ponder in development mode because otherwise we'd have to manually drop the `public` schema, but make sure not to edit any files in the ensindexer project or it'll start indexing from scratch. use `pnpm run start` if you don't want to worry about that, and be prepared to run `DROP SCHEMA 'public' CASCADE;` when you want to run ponder in dev mode again.\n\nNOTE: snapshots are resumable, so you can always Ctrl-C and re-start a snapshot and it will resume where it left off (after computing TotalCount).\n\n### Snapshot Archives\n\n🚧 WIP\n\nTODO: snapshot upload/download via public R2\n\n### Description\n\nTo index the subgraph or ENSNode at a specific blockheight, the tool runs an exhaustive set of graphql queries, using the subgraph as source of truth. for each generated query, the idempotent results are stored as json files in `snapshots/[:deployment]/[:blockheight]/[:indexer]/[:OperationName]_[:skip]_[:operationKey].json` which can be compared using the `diff` command.\n\nan `operationKey` is a [deterministic hash of a graphql document + variables](https://commerce.nearform.com/open-source/urql/docs/basics/document-caching/#operation-keys), an implementation detail from `urql`\n\nfor the subgraph, [timetravel queries](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/#time-travel-queries) are used to retrieve data at a specific blockheight.\n\nfor ENSNode, timetravel is not supported, so ENSIndexer should be run until the specified `endBlock` and then snapshotted with this tool.\n\n## resolution equivalency tool (`resolution-eq`)\n\n🚧 WIP\n\n\u003e This tool verifies equivalency in resolution responses between different ENS resolution services.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamehash%2Fens-subgraph-transition-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamehash%2Fens-subgraph-transition-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamehash%2Fens-subgraph-transition-tools/lists"}