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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o1-labs/mina-archive-node-graphql",
-  "version": "0.0.6",
+  "version": "2.0.0",
   "description": "A NodeJS GraphQL server for exposing Mina Protocol archive node data for o1js/zkApps",
   "repository": {
     "type": "git",
@@ -24,9 +24,10 @@
     "start": "node build/src/index.js",
     "dev": "cross-env NODE_NO_WARNINGS=1 npx nodemon --exec 'node -r dotenv/config --loader ts-node/esm' src/index.ts",
     "test": "./run-tests.sh",
-    "test:unit": "npm run build && for f in ./build/tests/unit/*test.js ./build/tests/utils.test.js ./build/tests/services/*/*.test.js; do node --enable-source-maps --test \"$f\"; done",
-    "test:coverage": "npm run build && npx c8 --include 'build/src/**' --reporter text --reporter lcov -- bash -c 'for f in ./build/tests/unit/*test.js ./build/tests/utils.test.js ./build/tests/services/*/*.test.js; do node --enable-source-maps --test \"$f\"; done'",
-    "test:integration": "npm run build && node --enable-source-maps --test ./build/tests/integration/integration.test.js",
+    "test:unit": "npm run build && (ec=0; for f in ./build/tests/unit/*test.js ./build/tests/utils.test.js ./build/tests/services/*/*.test.js; do node --enable-source-maps --test \"$f\" || ec=$?; done; exit $ec)",
+    "test:coverage": "npm run build && npx c8 --include 'build/src/**' --check-coverage --lines 50 --functions 50 --statements 50 --branches 80 --reporter text --reporter lcov -- bash -c 'ec=0; for f in ./build/tests/unit/*test.js ./build/tests/utils.test.js ./build/tests/services/*/*.test.js; do node --enable-source-maps --test \"$f\" || ec=$?; done; exit $ec'",
+    "test:integration": "npm run build && (ec=0; for f in ./build/tests/integration/*.test.js; do node --enable-source-maps --test \"$f\" || ec=$?; done; exit $ec)",
+    "test:live-api": "npm run build && node --enable-source-maps --test ./build/tests/live-api/*.test.js",
     "test:live-network": "npm run build && node --enable-source-maps --test-timeout 600000 --test ./build/tests/live-network/live-network.test.js",
     "test:devnet-dump": "npm run build && node --enable-source-maps --test-timeout 900000 --test ./build/tests/devnet-dump/devnet-dump.test.js",
     "clean": "rimraf ./build",
@@ -38,15 +39,26 @@
     "compose": "docker compose up",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["mina", "mina-protocol", "archive-node", "graphql", "o1js", "zkapp", "blockchain"],
+  "keywords": [
+    "mina",
+    "mina-protocol",
+    "archive-node",
+    "graphql",
+    "o1js",
+    "zkapp",
+    "blockchain"
+  ],
   "author": "O(1) Labs <build@o1labs.org>",
-  "license": "ISC",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "devDependencies": {
     "@graphql-codegen/cli": "^6.0.1",
     "@graphql-codegen/typescript": "^5.0.2",
     "@graphql-codegen/typescript-resolvers": "^5.0.1",
     "@graphql-eslint/eslint-plugin": "^4.4.0",
-    "@types/node": "^20.5.7",
+    "@types/node": "^22.20.1",
     "@typescript-eslint/eslint-plugin": "^6.5.0",
     "@typescript-eslint/parser": "^6.5.0",
     "artillery": "^2.0.0-36",
@@ -62,10 +74,15 @@
     "typescript": "^5.2.2"
   },
   "dependencies": {
-    "@envelop/core": "^4.0.0",
-    "@envelop/disable-introspection": "^5.0.0",
-    "@envelop/graphql-jit": "^6.0.1",
-    "@envelop/opentelemetry": "^5.0.0",
+    "@envelop/core": "^5.5.1",
+    "@envelop/disable-introspection": "^9.1.1",
+    "@envelop/graphql-jit": "^11.1.1",
+    "@envelop/opentelemetry": "^9.1.1",
+    "@escape.tech/graphql-armor-block-field-suggestions": "^3.0.1",
+    "@escape.tech/graphql-armor-cost-limit": "^2.4.3",
+    "@escape.tech/graphql-armor-max-aliases": "^2.6.2",
+    "@escape.tech/graphql-armor-max-depth": "^2.4.2",
+    "@escape.tech/graphql-armor-max-tokens": "^2.5.1",
     "@graphql-tools/executor-http": "^3.0.4",
     "@graphql-tools/graphql-file-loader": "^8.1.2",
     "@graphql-tools/load": "^8.1.2",
@@ -76,10 +93,12 @@
     "blakejs": "^1.2.1",
     "dotenv": "^16.3.1",
     "graphql": "^16.8.0",
-    "graphql-yoga": "4.0.4",
-    "postgres": "^3.3.5"
+    "graphql-yoga": "5.21.2",
+    "pino": "^10.3.1",
+    "postgres": "^3.3.5",
+    "prom-client": "^15.1.3"
   },
   "volta": {
-    "node": "20.18.0"
+    "node": "22.12.0"
   }
 }

package/schema.graphql

@@ -66,16 +66,54 @@ input ActionFilterOptionsInput {
   endActionState: String
 }
 
+"""
+Find applied account updates that set a specific verification key.
+
+The block range is required and limited by the server's configured maximum.
+`from` is inclusive and `to` is exclusive.
+"""
+input VerificationKeyUpdateFilterInput {
+  verificationKeyHash: String!
+  from: Int!
+  to: Int!
+  status: BlockStatusFilter
+}
+
+"""
+Filter successful zkApp commands by block range.
+
+Both `from` and `to` are required. The range is bounded by `ZKAPP_COMMAND_RANGE_SIZE`, and the server may reject dense ranges that expand to too many account updates.
+"""
+input ZkappCommandFilterOptionsInput {
+  blockStatus: BlockStatusFilter
+  """
+  Mina block height to filter zkApp commands from, inclusive
+  """
+  from: Int!
+  """
+  Mina block height to filter zkApp commands to, exclusive
+  """
+  to: Int!
+  """
+  Optional account update public key filter.
+  """
+  accountPublicKey: String
+  """
+  Optional account update token id filter.
+  """
+  tokenId: String
+}
+
 type EventData {
   accountUpdateId: String!
   transactionInfo: TransactionInfo
-  data: [String]!
+  data: [String!]!
 }
 
 type ActionData {
   accountUpdateId: String!
   transactionInfo: TransactionInfo
-  data: [String]!
+  data: [String!]!
 }
 
 type BlockInfo {
@@ -101,7 +139,16 @@ type TransactionInfo {
   memo: String!
   authorizationKind: String!
   sequenceNumber: Int!
-  zkappAccountUpdateIds: [Int]!
+  zkappAccountUpdateIds: [Int!]!
+}
+
+type VerificationKeyUpdate {
+  accountUpdateId: String!
+  address: String!
+  tokenId: String!
+  verificationKeyHash: String!
+  blockInfo: BlockInfo!
+  transactionInfo: TransactionInfo!
 }
 
 type ActionStates {
@@ -114,16 +161,67 @@ type ActionStates {
 
 type EventOutput {
   blockInfo: BlockInfo
-  eventData: [EventData]
+  eventData: [EventData!]
 }
 
 type ActionOutput {
   blockInfo: BlockInfo
   transactionInfo: TransactionInfo
-  actionData: [ActionData]
+  actionData: [ActionData!]
   actionState: ActionStates!
 }
 
+"""
+Raw field array from the archive database.
+
+An empty `fields` array means the archive row exists but contains no field values.
+Nullable entries mean the corresponding nullable archive state slot has no field value.
+"""
+type ZkappFieldArray {
+  fields: [String]!
+}
+
+type ZkappAccountPrecondition {
+  state: ZkappFieldArray
+  actionState: ZkappFieldArray
+  provedState: Boolean
+  isNew: Boolean
+}
+
+type ZkappGlobalSlotBounds {
+  lowerBound: Int
+  upperBound: Int
+}
+
+type ZkappNetworkPrecondition {
+  globalSlotSinceGenesis: ZkappGlobalSlotBounds
+}
+
+type ZkappAccountUpdateOutput {
+  id: String!
+  publicKey: String!
+  tokenId: String!
+  authorizationKind: String!
+  balanceChange: String!
+  incrementNonce: Boolean!
+  callDepth: Int!
+  actions: [ZkappFieldArray!]!
+  events: [ZkappFieldArray!]!
+  appState: ZkappFieldArray
+  accountPrecondition: ZkappAccountPrecondition
+  networkPrecondition: ZkappNetworkPrecondition
+}
+
+type ZkappCommandOutput {
+  blockInfo: BlockInfo!
+  hash: String!
+  feePayer: String!
+  fee: String!
+  memo: String!
+  sequenceNumber: Int!
+  accountUpdates: [ZkappAccountUpdateOutput!]!
+}
+
 """
 Metadata about the network
 """
@@ -214,8 +312,28 @@ type Block {
 }
 
 type Query {
-  events(input: EventFilterOptionsInput!): [EventOutput]!
-  actions(input: ActionFilterOptionsInput!): [ActionOutput]!
+  """
+  The `MAJOR.MINOR` version of this schema.
+
+  Clients compare it with the schema version they were built against: an equal
+  major means the contract they code against still holds, and a higher minor
+  means this server has additive changes they may not know about yet.
+
+  Always available, even when `ENABLED_QUERIES` restricts which data queries
+  this server exposes — a compatibility check that can itself be switched off
+  is of no use to a client.
+  """
+  schemaVersion: String!
+  events(input: EventFilterOptionsInput!): [EventOutput!]!
+  actions(input: ActionFilterOptionsInput!): [ActionOutput!]!
+  verificationKeyUpdates(
+    input: VerificationKeyUpdateFilterInput!
+  ): [VerificationKeyUpdate!]!
+  zkappCommands(input: ZkappCommandFilterOptionsInput!): [ZkappCommandOutput!]!
   networkState: NetworkStateOutput!
-  blocks(query: BlockQueryInput, limit: Int, sortBy: BlockSortByInput): [Block]!
+  blocks(
+    query: BlockQueryInput
+    limit: Int
+    sortBy: BlockSortByInput
+  ): [Block!]!
 }

package/src/blockchain/types.ts

@@ -25,7 +25,9 @@ export type Action = {
 };
 
 export type NetworkState = {
-  maxBlockHeight: MaxBlockHeightInfo;
+  // Nullable when the archive has no canonical or pending blocks indexed yet.
+  // Matches the schema: NetworkStateOutput.maxBlockHeight is nullable.
+  maxBlockHeight: MaxBlockHeightInfo | null;
 };
 
 export type MaxBlockHeightInfo = {
@@ -55,6 +57,17 @@ export type TransactionInfo = {
   zkappAccountUpdateIds: number[];
 };
 
+export type VerificationKeyUpdate = {
+  accountUpdateId: string;
+  address: string;
+  tokenId: string;
+  verificationKeyHash: string;
+  blockInfo: BlockInfo;
+  transactionInfo: TransactionInfo;
+};
+
+export type VerificationKeyUpdates = VerificationKeyUpdate[];
+
 export type Events = {
   eventData: Event[];
   blockInfo: BlockInfo;
@@ -96,6 +109,57 @@ export type ZkAppCommand = {
   failureReason: string | null;
 };
 
+export type ZkappAccountPrecondition = {
+  state: ZkappFieldArray | null;
+  actionState: ZkappFieldArray | null;
+  provedState: boolean | null;
+  isNew: boolean | null;
+};
+
+export type ZkappFieldArray = {
+  fields: (string | null)[];
+};
+
+export type ZkappNestedFieldArray = {
+  fields: string[];
+};
+
+export type ZkappGlobalSlotBounds = {
+  lowerBound: number | null;
+  upperBound: number | null;
+};
+
+export type ZkappNetworkPrecondition = {
+  globalSlotSinceGenesis: ZkappGlobalSlotBounds;
+};
+
+export type ZkappAccountUpdate = {
+  id: string;
+  publicKey: string;
+  tokenId: string;
+  authorizationKind: string;
+  balanceChange: string;
+  incrementNonce: boolean;
+  callDepth: number;
+  actions: ZkappNestedFieldArray[];
+  events: ZkappNestedFieldArray[];
+  appState: ZkappFieldArray | null;
+  accountPrecondition: ZkappAccountPrecondition;
+  networkPrecondition: ZkappNetworkPrecondition;
+};
+
+export type ZkappCommand = {
+  blockInfo: BlockInfo;
+  hash: string;
+  feePayer: string;
+  fee: string;
+  memo: string;
+  sequenceNumber: number;
+  accountUpdates: ZkappAccountUpdate[];
+};
+
+export type ZkappCommands = ZkappCommand[];
+
 export type FeeTransfer = {
   recipient: string;
   fee: string;

package/src/blockchain/utils.ts

@@ -1,7 +1,31 @@
 import type { BlockInfo, TransactionInfo, Event, Action } from './types.js';
 import type { ArchiveNodeDatabaseRow } from '../db/sql/events-actions/types.js';
 
-export function createBlockInfo(row: ArchiveNodeDatabaseRow): BlockInfo {
+type BlockInfoRow = Pick<
+  ArchiveNodeDatabaseRow,
+  | 'height'
+  | 'state_hash'
+  | 'parent_hash'
+  | 'ledger_hash'
+  | 'chain_status'
+  | 'timestamp'
+  | 'global_slot_since_hard_fork'
+  | 'global_slot_since_genesis'
+  | 'distance_from_max_block_height'
+  | 'last_vrf_output'
+>;
+
+type TransactionInfoRow = Pick<
+  ArchiveNodeDatabaseRow,
+  | 'status'
+  | 'hash'
+  | 'memo'
+  | 'authorization_kind'
+  | 'sequence_number'
+  | 'zkapp_account_updates_ids'
+>;
+
+export function createBlockInfo(row: BlockInfoRow): BlockInfo {
   return {
     height: Number(row.height),
     stateHash: row.state_hash,
@@ -17,7 +41,7 @@ export function createBlockInfo(row: ArchiveNodeDatabaseRow): BlockInfo {
 }
 
 export function createTransactionInfo(
-  row: ArchiveNodeDatabaseRow
+  row: TransactionInfoRow
 ): TransactionInfo {
   return {
     status: row.status,

package/src/config.ts

@@ -0,0 +1,133 @@
+export { parseBoolean, validateConfig, assertValidConfig };
+
+type EnvSource = Record<string, string | undefined>;
+
+const TRUE_VALUES = new Set(['true', '1', 'yes', 'on']);
+const FALSE_VALUES = new Set(['false', '0', 'no', 'off']);
+
+/** Env vars interpreted as booleans. */
+const BOOLEAN_VARS = [
+  'ENABLE_GRAPHIQL',
+  'ENABLE_INTROSPECTION',
+  'ENABLE_LOGGING',
+  'ENABLE_METRICS',
+  'ENABLE_JAEGER',
+  'ENABLE_BLOCK_TRANSACTION_DETAILS',
+  'ENABLE_ZKAPP_COMMANDS_QUERY',
+] as const;
+
+/** Env vars that, when set, must be positive integers. */
+const POSITIVE_INT_VARS = ['PORT', 'BLOCK_RANGE_SIZE'] as const;
+
+/** Root query fields in schema.graphql — keep in sync. */
+const KNOWN_QUERIES = [
+  'events',
+  'actions',
+  'verificationKeyUpdates',
+  'zkappCommands',
+  'networkState',
+  'blocks',
+] as const;
+
+/**
+ * Parse a boolean environment value. Recognises `true/false`, `1/0`, `yes/no`,
+ * `on/off` (case-insensitive). Anything unrecognised — including the empty
+ * string or `undefined` — yields `fallback`.
+ *
+ * This replaces ad-hoc truthiness checks like `if (process.env.ENABLE_X)`, which
+ * treated the string `"false"` as `true` (#74).
+ */
+function parseBoolean(value: string | undefined, fallback = false): boolean {
+  if (value === undefined) return fallback;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === '') return fallback;
+  if (TRUE_VALUES.has(normalized)) return true;
+  if (FALSE_VALUES.has(normalized)) return false;
+  return fallback;
+}
+
+function isRecognisedBoolean(value: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  return TRUE_VALUES.has(normalized) || FALSE_VALUES.has(normalized);
+}
+
+/**
+ * Validate the environment, returning a list of human-readable problems (empty
+ * when valid). Catches the common misconfigurations — a missing connection
+ * string, a non-numeric port, a mistyped boolean — so they surface at startup
+ * rather than as confusing runtime behaviour.
+ */
+function validateConfig(env: EnvSource = process.env): string[] {
+  const errors: string[] = [];
+
+  if (!env.PG_CONN || env.PG_CONN.trim() === '') {
+    errors.push('PG_CONN is required (Postgres connection string).');
+  }
+
+  for (const name of BOOLEAN_VARS) {
+    const value = env[name];
+    if (
+      value !== undefined &&
+      value.trim() !== '' &&
+      !isRecognisedBoolean(value)
+    ) {
+      errors.push(`${name} must be a boolean (true/false), got "${value}".`);
+    }
+  }
+
+  for (const name of POSITIVE_INT_VARS) {
+    const value = env[name];
+    if (value !== undefined && value.trim() !== '') {
+      const parsed = Number(value);
+      if (!Number.isInteger(parsed) || parsed <= 0) {
+        errors.push(`${name} must be a positive integer, got "${value}".`);
+      }
+    }
+  }
+
+  const enabledQueries = env.ENABLED_QUERIES;
+  if (enabledQueries !== undefined) {
+    const names = enabledQueries
+      .split(',')
+      .map((query) => query.trim())
+      .filter((query) => query !== '');
+    if (names.length === 0) {
+      errors.push(
+        'ENABLED_QUERIES is set but lists no queries; unset it to expose all of ' +
+          `${KNOWN_QUERIES.join(', ')}.`
+      );
+    }
+
+    // schemaVersion is served whatever this lists (see src/resolvers.ts), so
+    // naming it is redundant rather than wrong. Rejecting it would fail startup
+    // over a list that asks for exactly what it already gets.
+    const unknown = names.filter(
+      (name) =>
+        !(KNOWN_QUERIES as readonly string[]).includes(name) &&
+        name !== 'schemaVersion'
+    );
+    if (unknown.length > 0) {
+      errors.push(
+        `ENABLED_QUERIES contains unknown queries: ${unknown.join(', ')}. ` +
+          `Known queries: ${KNOWN_QUERIES.join(', ')}. ` +
+          'schemaVersion is always served and does not need listing.'
+      );
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate the environment and throw a single aggregated error if anything is
+ * wrong, so the process fails fast at startup with a clear message instead of
+ * booting into a broken state.
+ */
+function assertValidConfig(env: EnvSource = process.env): void {
+  const errors = validateConfig(env);
+  if (errors.length > 0) {
+    throw new Error(
+      `Invalid configuration:\n${errors.map((e) => `  - ${e}`).join('\n')}`
+    );
+  }
+}

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

@@ -1,23 +1,46 @@
-import type { EventFilterOptionsInput } from '../../resolvers-types.js';
+import type {
+  ActionFilterOptionsInput,
+  EventFilterOptionsInput,
+  VerificationKeyUpdateFilterInput,
+  ZkappCommandFilterOptionsInput,
+} from '../../resolvers-types.js';
 import type {
   Actions,
   Events,
   NetworkState,
   Blocks,
+  VerificationKeyUpdates,
+  ZkappCommands,
 } from '../../blockchain/types.js';
-import type { BlockQueryInput, BlockSortByInput } from '../../resolvers-types.js';
+import type {
+  BlockQueryInput,
+  BlockSortByInput,
+} from '../../resolvers-types.js';
 
 export interface DatabaseAdapter {
   getEvents(input: EventFilterOptionsInput, options?: unknown): Promise<Events>;
   getActions(
-    input: EventFilterOptionsInput,
+    input: ActionFilterOptionsInput,
     options?: unknown
   ): Promise<Actions>;
+  getZkappCommands(
+    input: ZkappCommandFilterOptionsInput,
+    options?: unknown
+  ): Promise<ZkappCommands>;
   getNetworkState(options?: unknown): Promise<NetworkState>;
+  getVerificationKeyUpdates(
+    input: VerificationKeyUpdateFilterInput,
+    options?: unknown
+  ): Promise<VerificationKeyUpdates>;
   getBlocks(
     query: BlockQueryInput | null | undefined,
     limit: number | null | undefined,
     sortBy: BlockSortByInput | null | undefined,
     options: unknown
   ): Promise<Blocks>;
+  /**
+   * Lightweight connectivity check for readiness probes. Resolves `true` when the
+   * database answers a trivial query, `false` otherwise. Never throws.
+   */
+  ping(): Promise<boolean>;
 }