@o1-labs/mina-archive-node-graphql 0.0.6 → 2.0.0

package/src/db/archive-node-adapter/archive-node-adapter.ts

@@ -4,6 +4,8 @@ import type {
   Events,
   NetworkState,
   Blocks,
+  VerificationKeyUpdates,
+  ZkappCommands,
 } from '../../blockchain/types.js';
 import type { DatabaseAdapter } from './archive-node-adapter.interface.js';
 import type {
@@ -11,16 +13,29 @@ import type {
   EventFilterOptionsInput,
   BlockQueryInput,
   BlockSortByInput,
+  VerificationKeyUpdateFilterInput,
+  ZkappCommandFilterOptionsInput,
 } from '../../resolvers-types.js';
 import { getTables, USED_TABLES } from '../../db/sql/events-actions/queries.js';
+import { buildPostgresOptions } from './postgres-options.js';
 import { EventsService } from '../../services/events-service/events-service.js';
 import { IEventsService } from '../../services/events-service/events-service.interface.js';
 import { ActionsService } from '../../services/actions-service/actions-service.js';
 import { IActionsService } from '../../services/actions-service/actions-service.interface.js';
+import { ZkappCommandsService } from '../../services/zkapp-commands-service/zkapp-commands-service.js';
+import { IZkappCommandsService } from '../../services/zkapp-commands-service/zkapp-commands-service.interface.js';
 import { NetworkService } from '../../services/network-service/network-service.js';
 import { INetworkService } from '../../services/network-service/network-service.interface.js';
 import { BlocksService } from '../../services/blocks-service/blocks-service.js';
 import { IBlocksService } from '../../services/blocks-service/blocks-service.interface.js';
+import { VerificationKeyUpdatesService } from '../../services/verification-key-updates-service/verification-key-updates-service.js';
+import { IVerificationKeyUpdatesService } from '../../services/verification-key-updates-service/verification-key-updates-service.interface.js';
+
+/**
+ * Connect deadline for the readiness pinger, in seconds. Kept short so a probe
+ * fails fast rather than hanging for the driver's 30s default.
+ */
+const PING_CONNECT_TIMEOUT_S = 2;
 
 export class ArchiveNodeAdapter implements DatabaseAdapter {
   /**
@@ -30,21 +45,38 @@ export class ArchiveNodeAdapter implements DatabaseAdapter {
    * `postgres.Sql` instance across the adapter is safe.
    */
   private client: postgres.Sql;
+  /**
+   * Dedicated single-connection client for readiness pings. postgres.js queues
+   * onto busy connections, so using the main pool can make a merely-busy DB look
+   * unreachable while long GraphQL queries are running.
+   */
+  private pingClient: postgres.Sql;
   private eventsService: IEventsService;
   private actionsService: IActionsService;
+  private zkappCommandsService: IZkappCommandsService;
   private networkService: INetworkService;
   private blocksService: IBlocksService;
+  private verificationKeyUpdatesService: IVerificationKeyUpdatesService;
 
   constructor(connectionString: string | undefined) {
     if (!connectionString)
       throw new Error(
         'Missing Postgres Connection String. Please provide a valid connection string in the environment variables or in your configuration file to connect to the Postgres database.'
       );
-    this.client = postgres(connectionString);
+    this.client = postgres(connectionString, buildPostgresOptions());
+    this.pingClient = postgres(connectionString, {
+      max: 1,
+      idle_timeout: 60,
+      connect_timeout: PING_CONNECT_TIMEOUT_S,
+    });
     this.eventsService = new EventsService(this.client);
     this.actionsService = new ActionsService(this.client);
+    this.zkappCommandsService = new ZkappCommandsService(this.client);
     this.networkService = new NetworkService(this.client);
     this.blocksService = new BlocksService(this.client);
+    this.verificationKeyUpdatesService = new VerificationKeyUpdatesService(
+      this.client
+    );
   }
 
   async getEvents(
@@ -61,10 +93,27 @@ export class ArchiveNodeAdapter implements DatabaseAdapter {
     return this.actionsService.getActions(input, options);
   }
 
+  async getZkappCommands(
+    input: ZkappCommandFilterOptionsInput,
+    options: unknown
+  ): Promise<ZkappCommands> {
+    return this.zkappCommandsService.getZkappCommands(input, options);
+  }
+
   async getNetworkState(options: unknown): Promise<NetworkState> {
     return this.networkService.getNetworkState(options);
   }
 
+  async getVerificationKeyUpdates(
+    input: VerificationKeyUpdateFilterInput,
+    options: unknown
+  ): Promise<VerificationKeyUpdates> {
+    return this.verificationKeyUpdatesService.getVerificationKeyUpdates(
+      input,
+      options
+    );
+  }
+
   async getBlocks(
     query: BlockQueryInput | null | undefined,
     limit: number | null | undefined,
@@ -95,7 +144,21 @@ export class ArchiveNodeAdapter implements DatabaseAdapter {
     }
   }
 
+  async ping(): Promise<boolean> {
+    try {
+      await this.pingClient`SELECT 1`;
+      return true;
+    } catch (error) {
+      console.warn(
+        `[readiness] database ping failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+      return false;
+    }
+  }
+
   async close() {
-    return this.client.end();
+    await Promise.all([this.client.end(), this.pingClient.end()]);
   }
 }

package/src/db/archive-node-adapter/postgres-options.ts

@@ -0,0 +1,90 @@
+import type postgres from 'postgres';
+
+export { buildPostgresOptions, resolvePoolConfig, POOL_DEFAULTS };
+export type { PostgresPoolConfig };
+
+/**
+ * Connection-pool and timeout configuration for the archive-node Postgres
+ * client. Without these limits a single expensive query can hold a connection
+ * open indefinitely, exhausting the pool and cascading into an outage. The
+ * defaults are deliberately conservative so the server is safe to expose
+ * publicly out of the box, and every value is tunable via the environment.
+ */
+interface PostgresPoolConfig {
+  /**
+   * Maximum pooled connections in total, not per host: a multi-host `PG_CONN`
+   * fails over to the first reachable host rather than fanning out, so the pool
+   * only ever points at one host at a time.
+   */
+  max: number;
+  /** Seconds a connection may sit idle before it is closed. */
+  idleTimeout: number;
+  /** Seconds to wait for a new connection before giving up. */
+  connectTimeout: number;
+  /**
+   * Server-side `statement_timeout` in milliseconds. A query running longer
+   * than this is cancelled by Postgres. `0` disables the timeout.
+   */
+  statementTimeout: number;
+}
+
+const POOL_DEFAULTS: PostgresPoolConfig = {
+  max: 10,
+  idleTimeout: 30,
+  connectTimeout: 30,
+  statementTimeout: 15_000,
+};
+
+/**
+ * Parse a non-negative integer from an env value, falling back to `fallback`
+ * when the value is missing or malformed. We fall back rather than throw so a
+ * stray typo never silently disables a safety limit (e.g. `max` becoming 0).
+ */
+function intFromEnv(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === '') return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) return fallback;
+  return parsed;
+}
+
+type EnvSource = Record<string, string | undefined>;
+
+function resolvePoolConfig(env: EnvSource = process.env): PostgresPoolConfig {
+  return {
+    // `max` must be at least 1 — a pool of 0 connections can never serve a query.
+    max: Math.max(1, intFromEnv(env.PG_MAX_CONNECTIONS, POOL_DEFAULTS.max)),
+    idleTimeout: intFromEnv(env.PG_IDLE_TIMEOUT, POOL_DEFAULTS.idleTimeout),
+    connectTimeout: intFromEnv(
+      env.PG_CONNECT_TIMEOUT,
+      POOL_DEFAULTS.connectTimeout
+    ),
+    statementTimeout: intFromEnv(
+      env.PG_STATEMENT_TIMEOUT,
+      POOL_DEFAULTS.statementTimeout
+    ),
+  };
+}
+
+/**
+ * Build the options object passed to `postgres()`. `statement_timeout` is sent
+ * as a startup connection parameter so it applies to every query on every
+ * connection in the pool.
+ */
+function buildPostgresOptions(
+  env: EnvSource = process.env
+): postgres.Options<Record<string, never>> {
+  const config = resolvePoolConfig(env);
+  return {
+    max: config.max,
+    idle_timeout: config.idleTimeout,
+    connect_timeout: config.connectTimeout,
+    connection: {
+      // Sent as a startup connection parameter, so it applies to every query.
+      // Stringified deliberately: postgres.js drops falsy startup parameters,
+      // so numeric 0 would be omitted instead of explicitly disabling it.
+      // Its type narrows this specific key to number, but the startup-packet
+      // implementation serialises strings and the index signature allows them.
+      statement_timeout: String(config.statementTimeout) as unknown as number,
+    },
+  };
+}

package/src/db/sql/best-chain.ts

@@ -0,0 +1,34 @@
+import type postgres from 'postgres';
+
+/**
+ * The height of the best chain's tip — the anchor every "walk back from the tip"
+ * recursive CTE starts from.
+ *
+ * This is deliberately NOT `(SELECT MAX(height) FROM blocks)`. The archive keeps every
+ * block it ever saw, so after a hard fork the abandoned chain's blocks stay in the table
+ * ABOVE the new chain's tip, marked `orphaned`. A global max then lands on a dead block:
+ * with the `chain_status = 'pending'` guard the anchor matches nothing and the walk
+ * silently degrades to canonical-only rows; without the guard the walk follows the dead
+ * chain. Either way the live tip and everything the network produced since the fork is
+ * invisible to `inBestChain`, events, actions and action-state resolution.
+ *
+ * Seen on mainnet at the Mesa upgrade (2026-09-03): the old chain reached height 548187
+ * before stopping, the fork block was 548147, and for the whole first hour
+ * `blocks(inBestChain: true)` returned nothing above 548147 while `networkState`
+ * correctly reported a pending tip of 548164 — the two disagreed because only one of
+ * them excluded orphans.
+ *
+ * Restricting the max to non-orphaned blocks makes the anchor agree with
+ * `networkState.pendingMaxBlockHeight` (which is computed per `chain_status`), and it is
+ * a no-op in normal operation, where the highest block is always the pending tip.
+ */
+export const BEST_CHAIN_TIP_HEIGHT_SQL =
+  "(SELECT MAX(height) FROM blocks WHERE chain_status <> 'orphaned')";
+
+/**
+ * {@link BEST_CHAIN_TIP_HEIGHT_SQL} as a fragment for tagged-template queries. The text is
+ * a constant with no user input, which is what makes `unsafe` safe here.
+ */
+export function bestChainTipHeight(db_client: postgres.Sql) {
+  return db_client.unsafe(BEST_CHAIN_TIP_HEIGHT_SQL);
+}

package/src/db/sql/events-actions/queries.ts

@@ -2,6 +2,7 @@ import type postgres from 'postgres';
 import { ArchiveNodeDatabaseRow } from './types.js';
 import { BlockStatusFilter } from '../../../blockchain/types.js';
 import { BLOCK_RANGE_SIZE } from '../../../server/server.js';
+import { bestChainTipHeight } from '../best-chain.js';
 
 function fullChainCTE(db_client: postgres.Sql, from?: string, to?: string) {
   let toAsNum = to ? Number(to) : undefined;
@@ -20,20 +21,27 @@ function fullChainCTE(db_client: postgres.Sql, from?: string, to?: string) {
       FROM
         blocks b
       WHERE
-        height = (SELECT max(height) FROM blocks)
+        height = ${bestChainTipHeight(db_client)}
     ) 
     UNION ALL
     SELECT
       b.id, b.state_hash, b.parent_hash, b.parent_id, b.height, b.global_slot_since_genesis, b.global_slot_since_hard_fork, b.timestamp, b.chain_status, b.ledger_hash, b.last_vrf_output
     FROM
       blocks b
+      -- The walk terminates because genesis has parent_id = NULL, so the
+      -- id = parent_id join can never match there. No block is its own parent
+      -- (parent_id is a FK to blocks.id; a self-reference would be a cycle), so
+      -- no explicit id <> parent_id guard is needed. A schema/hard-fork change
+      -- that ever self-references a block would loop here — see the matching
+      -- note in getZkappsWithPendingEventsQuery.
       INNER JOIN pending_chain ON b.id = pending_chain.parent_id
-      AND pending_chain.id <> pending_chain.parent_id
       AND pending_chain.chain_status <> 'canonical'
-  ), 
+  ),
   full_chain AS (
     SELECT
-      DISTINCT id, state_hash, parent_id, parent_hash, height, global_slot_since_genesis, global_slot_since_hard_fork, timestamp, chain_status, ledger_hash, (SELECT max(height) FROM blocks) - height AS distance_from_max_block_height, last_vrf_output
+      DISTINCT id, state_hash, parent_id, parent_hash, height, global_slot_since_genesis, global_slot_since_hard_fork, timestamp, chain_status, ledger_hash, ${bestChainTipHeight(
+        db_client
+      )} - height AS distance_from_max_block_height, last_vrf_output
     FROM
       (
         SELECT
@@ -63,10 +71,9 @@ function fullChainCTE(db_client: postgres.Sql, from?: string, to?: string) {
             // If no params ar provided, then we query the last BLOCK_RANGE_SIZE blocks
             fromAsNum
               ? db_client`AND b.height >= ${fromAsNum} AND b.height < ${toAsNum!}`
-              : db_client`AND b.height >= (
-                SELECT MAX(b2.height)
-                FROM blocks b2
-            ) - ${BLOCK_RANGE_SIZE}`
+              : db_client`AND b.height >= ${bestChainTipHeight(
+                  db_client
+                )} - ${BLOCK_RANGE_SIZE}`
           }
       ) AS full_chain
   )
@@ -256,8 +263,8 @@ function emittedActionsCTE(db_client: postgres.Sql) {
 
 function emittedActionStateCTE(
   db_client: postgres.Sql,
-  fromActionState?: string,
-  endActionState?: string
+  fromActionStateHeight?: string,
+  endActionStateHeight?: string
 ) {
   return db_client`
   emitted_action_state AS (
@@ -308,14 +315,28 @@ function emittedActionStateCTE(
       INNER JOIN zkapp_field zkf4 ON zkf4.id = zks.element4
     WHERE
       1 = 1
+    -- Filter on the position of the checkpoint ON THE CHAIN, resolved by
+    -- resolveActionStateBoundary() before this query runs.
+    --
+    -- This used to compare zkf0.id against the id of the requested action state.
+    -- zkapp_field is the interning table for every field value in the archive,
+    -- and its id records when a value was FIRST WRITTEN, not where it sits on
+    -- the chain. Any archive filled out of chain order — a bulk import, a
+    -- hard-fork migration, a bootstrap — breaks that assumption, and the filter
+    -- then silently dropped real actions or returned actions from before the
+    -- checkpoint. See tests/integration/action-state-ordering.test.ts.
+    --
+    -- Greater-or-equal keeps the checkpoint's own block in the answer. o1js
+    -- removes it in createActionsList by comparing actionStateOne with the
+    -- requested value, so excluding it here would change what clients receive.
     ${
-      fromActionState
-        ? db_client`AND zkf0.id >= (SELECT id FROM zkapp_field WHERE field = ${fromActionState})`
+      fromActionStateHeight
+        ? db_client`AND emitted_actions.height >= ${fromActionStateHeight}`
         : db_client``
     }
     ${
-      endActionState
-        ? db_client`AND zkf0.id <= (SELECT id FROM zkapp_field WHERE field = ${endActionState})`
+      endActionStateHeight
+        ? db_client`AND emitted_actions.height <= ${endActionStateHeight}`
         : db_client``
     }
   )`;
@@ -378,17 +399,21 @@ export function getActionsQuery(
   status: BlockStatusFilter,
   to?: string,
   from?: string,
-  fromActionState?: string,
-  endActionState?: string
+  fromActionStateHeight?: string,
+  endActionStateHeight?: string
 ) {
   return db_client<ArchiveNodeDatabaseRow[]>`
-  WITH 
+  WITH
   ${fullChainCTE(db_client, from, to)},
   ${accountIdentifierCTE(db_client, address, tokenId)},
   ${blocksAccessedCTE(db_client, status)},
   ${emittedZkAppCommandsCTE(db_client)},
   ${emittedActionsCTE(db_client)},
-  ${emittedActionStateCTE(db_client, fromActionState, endActionState)}
+  ${emittedActionStateCTE(
+    db_client,
+    fromActionStateHeight,
+    endActionStateHeight
+  )}
   SELECT *
   FROM emitted_action_state
   `;
@@ -412,9 +437,115 @@ JOIN max_heights mh
   `;
 }
 
-export function checkActionState(db_client: postgres.Sql, actionState: string) {
-  return db_client`
-  SELECT field FROM zkapp_field WHERE field = ${actionState}
+export type ActionStateBoundaryRow = {
+  boundary_height: string | null;
+  window_start: string | null;
+  /**
+   * true  — the account still held the requested action state when the window
+   *         began, so nothing was missed before it.
+   * false — the state had already moved on, so actions are missing.
+   * null  — the account was never accessed below the window, which means the
+   *         checkpoint itself is inside it.
+   */
+  state_entering_window: boolean | null;
+};
+
+/**
+ * Resolves an action state to its position on the chain, for one account.
+ *
+ * This replaces the old `checkActionState`, which only asked whether the value
+ * existed anywhere in `zkapp_field`. That accepted any field value in the whole
+ * database — action data, app state, another account's action state — so the
+ * server answered with data that had nothing to do with the request instead of
+ * raising an error.
+ *
+ * The lookup is deliberately NOT limited to the queried block range. A checkpoint
+ * is a position, not data: resolving it does not need its block to be inside the
+ * window. Restricting it to the window would make an out-of-range checkpoint
+ * resolve to nothing, and `height >= NULL` selects no rows — the server would
+ * then answer with an empty list, which a reducer reads as "no actions to fold".
+ *
+ * Returns one row:
+ *
+ *   boundary_height        the lowest block height at which this account's action
+ *                          state was the requested value, over the canonical chain
+ *                          plus the current pending chain. NULL means the value is
+ *                          not an action state of this account at all.
+ *   window_start           the first block height this query covers, derived the
+ *                          same way as fullChainCTE.
+ *   state_entering_window  this account's action state at its last accessed block
+ *                          below window_start, or NULL if it was never accessed
+ *                          below it. If this still equals the requested value, no
+ *                          action was missed between the checkpoint and the start
+ *                          of the window, so the answer is complete even though the
+ *                          checkpoint itself lies outside it.
+ */
+export function resolveActionStateBoundary(
+  db_client: postgres.Sql,
+  address: string,
+  tokenId: string,
+  actionState: string,
+  from?: string,
+  to?: string
+) {
+  const fromAsNum = from ? Number(from) : null;
+  const toAsNum = to ? Number(to) : null;
+
+  return db_client<ActionStateBoundaryRow[]>`
+  WITH RECURSIVE pending_chain AS (
+    (
+      SELECT id, parent_id, chain_status
+      FROM blocks
+      WHERE height = ${bestChainTipHeight(db_client)}
+    )
+    UNION ALL
+    SELECT b.id, b.parent_id, b.chain_status
+    FROM blocks b
+      -- Same invariant as fullChainCTE: genesis has parent_id = NULL, and no
+      -- block is its own parent, so an explicit id <> parent_id guard never
+      -- excludes a row.
+      INNER JOIN pending_chain ON b.id = pending_chain.parent_id
+      AND pending_chain.chain_status <> 'canonical'
+  ),
+  bounds AS (
+    SELECT ${
+      fromAsNum !== null
+        ? db_client`${fromAsNum}::bigint`
+        : toAsNum !== null
+        ? db_client`${toAsNum - BLOCK_RANGE_SIZE}::bigint`
+        : db_client`${bestChainTipHeight(
+            db_client
+          )} - ${BLOCK_RANGE_SIZE}::bigint`
+    } AS window_start
+  ),
+  target AS (
+    SELECT id FROM zkapp_field WHERE field = ${actionState}
+  ),
+  account_action_states AS (
+    SELECT b.height, zks.element0 AS state_field_id
+    FROM accounts_accessed aa
+      INNER JOIN blocks b ON b.id = aa.block_id
+      INNER JOIN zkapp_accounts zkacc ON zkacc.id = aa.zkapp_id
+      INNER JOIN zkapp_action_states zks ON zks.id = zkacc.action_state_id
+    WHERE aa.account_identifier_id = (
+        SELECT ai.id FROM account_identifiers ai
+        WHERE ai.public_key_id = (SELECT id FROM public_keys WHERE value = ${address})
+          AND ai.token_id = (SELECT id FROM tokens WHERE value = ${tokenId})
+      )
+      AND (b.chain_status = 'canonical' OR b.id IN (SELECT id FROM pending_chain))
+  )
+  SELECT
+    (
+      SELECT min(height) FROM account_action_states
+      WHERE state_field_id = (SELECT id FROM target)
+    ) AS boundary_height,
+    (SELECT window_start FROM bounds) AS window_start,
+    (
+      SELECT state_field_id FROM account_action_states
+      WHERE height < (SELECT window_start FROM bounds)
+      ORDER BY height DESC
+      LIMIT 1
+    ) = (SELECT id FROM target) AS state_entering_window
   `;
 }
 
@@ -427,16 +558,27 @@ export function getTables(db_client: postgres.Sql) {
 export const USED_TABLES = [
   'blocks',
   'account_identifiers',
+  'public_keys',
+  'tokens',
   'accounts_accessed',
   'blocks_zkapp_commands',
+  'public_keys',
+  'tokens',
   'zkapp_commands',
+  'zkapp_fee_payer_body',
   'zkapp_account_update',
   'zkapp_account_update_body',
+  'zkapp_updates',
   'zkapp_events',
   'zkapp_field_array',
   'zkapp_field',
+  'zkapp_account_precondition',
+  'zkapp_network_precondition',
+  'zkapp_global_slot_bounds',
+  'zkapp_states_nullable',
   'zkapp_verification_key_hashes',
   'zkapp_verification_keys',
+  'zkapp_updates',
   'zkapp_accounts',
   'zkapp_action_states',
 ] as const;
@@ -447,17 +589,19 @@ export function getZkappsWithPendingEventsQuery(db_client: postgres.Sql) {
   -- start at the tip
   SELECT id, parent_id, chain_status
     FROM blocks
-   WHERE height = (SELECT MAX(height) FROM blocks)
+   WHERE height = ${bestChainTipHeight(db_client)}
 
   UNION ALL
 
   -- walk back until we re-join the canonical branch
+  -- The id <> parent_id guard was dropped here for the same reason as in
+  -- fullChainCTE: no block is its own parent, so it never excludes a row, and
+  -- the walk terminates on genesis's NULL parent_id regardless.
   SELECT b.id, b.parent_id, b.chain_status
     FROM blocks b
     JOIN pending_chain pc
       ON b.id = pc.parent_id
-   WHERE pc.id <> pc.parent_id
-     AND pc.chain_status <> 'canonical'
+   WHERE pc.chain_status <> 'canonical'
 )
 SELECT DISTINCT
   pk.value AS public_key

package/src/db/sql/verification-key-updates/queries.ts

@@ -0,0 +1,132 @@
+import type postgres from 'postgres';
+import { BlockStatusFilter } from '../../../blockchain/types.js';
+
+export type VerificationKeyUpdateDatabaseRow = {
+  account_update_id: number;
+  address: string;
+  token_id: string;
+  verification_key_hash: string;
+  state_hash: string;
+  parent_hash: string;
+  height: string;
+  global_slot_since_genesis: string;
+  global_slot_since_hard_fork: string;
+  timestamp: string;
+  chain_status: string;
+  ledger_hash: string;
+  distance_from_max_block_height: string;
+  last_vrf_output: string;
+  status: string;
+  hash: string;
+  memo: string;
+  authorization_kind: string;
+  sequence_number: number;
+  zkapp_account_updates_ids: number[];
+};
+
+export function getVerificationKeyUpdatesQuery(
+  client: postgres.Sql,
+  verificationKeyHash: string,
+  from: number,
+  to: number,
+  status: BlockStatusFilter
+) {
+  const statusClause =
+    status === BlockStatusFilter.all
+      ? client`AND b.chain_status <> 'orphaned'`
+      : client`AND b.chain_status = ${status.toLowerCase()}`;
+
+  return client<VerificationKeyUpdateDatabaseRow[]>`
+      WITH RECURSIVE pending_chain AS (
+        SELECT id, parent_id
+        FROM blocks
+        WHERE chain_status = 'pending'
+          AND height = (
+            SELECT MAX(height) FROM blocks WHERE chain_status = 'pending'
+          )
+
+        UNION ALL
+
+        SELECT parent.id, parent.parent_id
+        FROM blocks parent
+        INNER JOIN pending_chain child ON parent.id = child.parent_id
+        WHERE parent.chain_status <> 'canonical'
+          AND child.id <> child.parent_id
+      ),
+      -- Resolve the requested hash to the set of zkapp_updates rows that SET
+      -- that verification key, before touching any block. The set is small — one
+      -- row per distinct update that ever wrote this key — and MATERIALIZED
+      -- keeps the planner from inlining it back into the join tree, where it
+      -- would hash the whole of zkapp_updates and zkapp_account_update_body once
+      -- per query. Measured on a 681k-block devnet archive over the maximum
+      -- 10 000-block range: 405 ms inlined, 199 ms materialised.
+      target_updates AS MATERIALIZED (
+        SELECT zu.id
+        FROM zkapp_verification_key_hashes vkh
+        INNER JOIN zkapp_verification_keys vk ON vk.hash_id = vkh.id
+        INNER JOIN zkapp_updates zu ON zu.verification_key_id = vk.id
+        WHERE vkh.value = ${verificationKeyHash}
+      ),
+      full_chain AS (
+        SELECT b.*
+        FROM blocks b
+        WHERE b.height >= ${from}
+          AND b.height < ${to}
+          AND (
+            b.chain_status = 'canonical'
+            OR b.id IN (SELECT id FROM pending_chain)
+          )
+      )
+      SELECT
+        zau.id AS account_update_id,
+        pk.value AS address,
+        t.value AS token_id,
+        ${verificationKeyHash}::text AS verification_key_hash,
+        b.state_hash,
+        b.parent_hash,
+        b.height,
+        b.global_slot_since_genesis,
+        b.global_slot_since_hard_fork,
+        b.timestamp,
+        b.chain_status,
+        b.ledger_hash,
+        (SELECT MAX(height) FROM blocks) - b.height
+          AS distance_from_max_block_height,
+        b.last_vrf_output,
+        bzc.status,
+        zc.hash,
+        zc.memo,
+        zaub.authorization_kind,
+        bzc.sequence_no AS sequence_number,
+        zc.zkapp_account_updates_ids
+      FROM full_chain b
+      INNER JOIN blocks_zkapp_commands bzc ON bzc.block_id = b.id
+      INNER JOIN zkapp_commands zc ON zc.id = bzc.zkapp_command_id
+      INNER JOIN LATERAL UNNEST(zc.zkapp_account_updates_ids)
+        WITH ORDINALITY AS update_ref(id, position) ON TRUE
+      INNER JOIN zkapp_account_update zau ON zau.id = update_ref.id
+      -- An account update SETS a verification key through update_id. The other
+      -- column that names a verification key on this table,
+      -- verification_key_hash_id, is the PRECONDITION: the key the update
+      -- requires the account to already have. Filtering on that one would answer
+      -- "who called this contract" instead of "who deployed it".
+      INNER JOIN zkapp_account_update_body zaub ON zaub.id = zau.body_id
+        AND zaub.update_id IN (SELECT id FROM target_updates)
+      INNER JOIN account_identifiers ai ON ai.id = zaub.account_identifier_id
+      INNER JOIN public_keys pk ON pk.id = ai.public_key_id
+      INNER JOIN tokens t ON t.id = ai.token_id
+      WHERE bzc.status = 'applied'
+        ${statusClause}
+      -- state_hash is what makes this order total. Two competing tips sit at the
+      -- same height, and pending_chain seeds from every block at the maximum
+      -- pending height, so both are in the answer. A command carried by both —
+      -- the normal case during a reorg; one command was measured in 8 blocks at
+      -- a single height on devnet — then produces rows that agree on height,
+      -- sequence_no, account-update position and zkapp_account_update.id alike.
+      ORDER BY
+        b.height ASC,
+        b.state_hash ASC,
+        bzc.sequence_no ASC,
+        update_ref.position ASC
+    `;
+}