o1-labs / o1-labs/Archive-Node-API

Add zkApp command range query with account update details

Open
#161 2 comments 0 reactions 0 assignees View on GitHub

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:

  • from is inclusive and to is 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, and accountPrecondition.actionState should be returned as field arrays.
  • accountPublicKey and tokenId should 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.