Skip to content

docs: Add reliable transaction pagination guidance and example - #168

Open
arunimshukla wants to merge 1 commit into
aave:mainfrom
arunimshukla:docs/reliable-transaction-pagination
Open

arunimshukla wants to merge 1 commit into
aave:mainfrom
arunimshukla:docs/reliable-transaction-pagination

Conversation

@arunimshukla

Copy link
Copy Markdown

Summary

  • Correct the README's claim that 100 entities is a hard per-query limit; 100 is the default collection size.
  • Replace the offset-only example with an ID cursor, a fixed finalized block hash, and per-page deployment/snapshot checks.
  • Add a dependency-free, read-only Node.js example scoped to one wallet's V2/V3 transaction history.
  • Add local tests for cursor advancement, tied timestamps, short and empty pages, HTTP/GraphQL errors, snapshot drift, and CLI failure handling.
  • Check that the README query matches the tested example and that selected fields exist in both current protocol schemas.

Why

The existing pagination paragraph confuses the default page size with a hard limit. It also provides no guidance for stable historical exports or for distinguishing failed/partial responses from complete results.

The updated guidance follows The Graph's querying best practices and GraphQL API documentation.

Related to #155 as query-troubleshooting guidance. This does not reproduce or diagnose that issue's position-query inconsistency, claim pagination caused it, or attempt to close it.

Scope

  • README and standalone example/test files only.
  • No schema, mapping, contract, deployment, dependency, or package-script changes.
  • No affected indexer deployment or new test deployment. The example issues read-only queries against an endpoint supplied by the caller.
  • Cursor exhaustion is not independent proof that all on-chain events were indexed correctly; the README makes that boundary explicit.

Validation

node --test examples/paginate-user-transactions.test.mjs
  • 17 tests passed on Node.js 24.19.0.
  • Verified the original README against upstream blob 5cc46fb064e55a488043c3a06e8e512425bedad1.
  • Reviewed query fields against schemas/v2.schema.graphql and schemas/v3.schema.graphql, and ID generation against src/utils/id-generation.ts.
  • Verified one contribution commit containing exactly the three intended files.
  • Tests use mocked responses. No live endpoint execution, deployed GraphQL schema validation, or subgraph build/deployment is claimed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant