o1-labs / o1-labs/Archive-Node-API
Add zkApp command range query with account update details
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 19
- Forks
- 9
- Avg merge
- 14h 20m
- Merged PRs (30d)
- 8
Description
We need a GraphQL query that exposes zkApp command account-update data from the archive DB by block range.
Right now, Archive-Node-API exposes parts of this data through queries like blocks, actions(address), and events(address). Clients that need the full zkApp command/account-update tree have to make many account-scoped queries and reconstruct the command data themselves. That is slow, incomplete when the account set is not known ahead of time, and hard to make deterministic.
The archive DB already stores this as one relational tree:
blocks -> zkApp commands -> account updates -> actions/events/app state/preconditions
We need a GraphQL query that returns that tree directly for a bounded block range.
Proposed query shape:
query ZkappCommands($from: Int!, $to: Int!) {
zkappCommands(input: { from: $from, to: $to, status: ALL }) {
blockInfo {
height
stateHash
parentHash
timestamp
chainStatus
globalSlotSinceGenesis
distanceFromMaxBlockHeight
}
hash
feePayer
fee
memo
status
failureReason
sequenceNumber
accountUpdates {
id
publicKey
tokenId
authorizationKind
balanceChange
incrementNonce
callDepth
actions
events
appState
accountPrecondition {
state
actionState
provedState
isNew
}
networkPrecondition {
globalSlotSinceGenesis
}
}
}
}
Proposed input:
input ZkappCommandFilterOptionsInput {
from: Int
to: Int
status: BlockStatusFilter
accountPublicKey: String
tokenId: String
}
Requirements:
fromis inclusive andtois exclusive, matching existing range query behavior.- The existing block range cap should apply.
- Results must be deterministic: block height, zkApp command sequence number, account update order.
actions,events,appState,accountPrecondition.state, andaccountPrecondition.actionStateshould be returned as field arrays.accountPublicKeyandtokenIdshould be optional filters. The unfiltered block-range query is the important path because callers may not know all account public keys ahead of time.- The SQL should filter block range/status and failed commands before expanding nested action/event/state arrays, since this query can be large on dense ranges.
This would let clients retrieve zkApp command data already present in Postgres through one GraphQL range query instead of doing many smaller account-scoped queries and reconstructing the command tree client-side.
WIP implementation for reference: https://github.com/Hebilicious/Archive-Node-API/pull/1
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by examining the existing GraphQL range queries and the blocks, actions(address), and events(address) entry points, then trace how the archive PostgreSQL data is exposed. Compare the WIP pull request with the proposed schema and requirements; done means a bounded, deterministic zkApp command query returns the specified nested fields and filters.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql, postgresql, typescript
- Domain
- api, backend, database
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100