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

package/src/blockchain/constants.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_TOKEN_ID =
+  'wSHV2S4qX9jFsLjQo8r1BsMLH2ZRKsZx6EJd1sbozGPieEC4Jf' as const;

package/src/blockchain/types.ts

@@ -0,0 +1,121 @@
+import { ArchiveNodeDatabaseRow } from '../db/sql/events-actions/types.js';
+
+export type Transactions = Map<string, ArchiveNodeDatabaseRow[]>;
+
+export type BlocksWithTransactionsMap = Map<string, Transactions>;
+
+export type FieldElementIdWithValueMap = Map<string, string>;
+
+export enum BlockStatusFilter {
+  all = 'ALL',
+  pending = 'PENDING',
+  canonical = 'CANONICAL',
+}
+
+export type Event = {
+  accountUpdateId: string;
+  transactionInfo: TransactionInfo;
+  data: string[];
+};
+
+export type Action = {
+  accountUpdateId: string;
+  transactionInfo: TransactionInfo;
+  data: string[];
+};
+
+export type NetworkState = {
+  maxBlockHeight: MaxBlockHeightInfo;
+};
+
+export type MaxBlockHeightInfo = {
+  canonicalMaxBlockHeight: number;
+  pendingMaxBlockHeight: number;
+};
+
+export type BlockInfo = {
+  height: number;
+  stateHash: string;
+  parentHash: string;
+  ledgerHash: string;
+  chainStatus: string;
+  timestamp: string;
+  globalSlotSinceHardfork: number;
+  globalSlotSinceGenesis: number;
+  distanceFromMaxBlockHeight: number;
+  lastVrfOutput: string;
+};
+
+export type TransactionInfo = {
+  status: string;
+  hash: string;
+  memo: string;
+  authorizationKind: string;
+  sequenceNumber: number;
+  zkappAccountUpdateIds: number[];
+};
+
+export type Events = {
+  eventData: Event[];
+  blockInfo: BlockInfo;
+}[];
+
+export type ActionStates = {
+  actionStateOne: string;
+  actionStateTwo: string;
+  actionStateThree: string;
+  actionStateFour: string;
+  actionStateFive: string;
+};
+
+export type Actions = {
+  actionState: ActionStates;
+  actionData: Action[];
+  blockInfo: BlockInfo;
+}[];
+
+export type UserCommand = {
+  hash: string;
+  kind: string;
+  from: string;
+  to: string;
+  amount: string;
+  fee: string;
+  memo: string;
+  nonce: number;
+  status: string;
+  failureReason: string | null;
+};
+
+export type ZkAppCommand = {
+  hash: string;
+  feePayer: string;
+  fee: string;
+  memo: string;
+  status: string;
+  failureReason: string | null;
+};
+
+export type FeeTransfer = {
+  recipient: string;
+  fee: string;
+  type: string;
+};
+
+export type BlockTransactions = {
+  coinbase: string;
+  userCommands: UserCommand[];
+  zkappCommands: ZkAppCommand[];
+  feeTransfer: FeeTransfer[];
+};
+
+export type Block = {
+  blockHeight: number;
+  creator: string;
+  stateHash: string;
+  parentHash: string;
+  dateTime: string;
+  transactions: BlockTransactions;
+};
+
+export type Blocks = Block[];

package/src/blockchain/utils.ts

@@ -0,0 +1,54 @@
+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 {
+  return {
+    height: Number(row.height),
+    stateHash: row.state_hash,
+    parentHash: row.parent_hash,
+    ledgerHash: row.ledger_hash,
+    chainStatus: row.chain_status,
+    timestamp: row.timestamp,
+    globalSlotSinceHardfork: Number(row.global_slot_since_hard_fork),
+    globalSlotSinceGenesis: Number(row.global_slot_since_genesis),
+    distanceFromMaxBlockHeight: Number(row.distance_from_max_block_height),
+    lastVrfOutput: row.last_vrf_output,
+  };
+}
+
+export function createTransactionInfo(
+  row: ArchiveNodeDatabaseRow
+): TransactionInfo {
+  return {
+    status: row.status,
+    hash: row.hash,
+    memo: row.memo,
+    authorizationKind: row.authorization_kind,
+    sequenceNumber: row.sequence_number,
+    zkappAccountUpdateIds: row.zkapp_account_updates_ids,
+  };
+}
+
+export function createEvent(
+  accountUpdateId: string,
+  data: string[],
+  transactionInfo: TransactionInfo
+): Event {
+  return {
+    accountUpdateId,
+    data,
+    transactionInfo,
+  };
+}
+
+export function createAction(
+  accountUpdateId: string,
+  data: string[],
+  transactionInfo: TransactionInfo
+): Action {
+  return {
+    accountUpdateId,
+    data,
+    transactionInfo,
+  };
+}

package/src/consensus/mina-consensus.ts

@@ -0,0 +1,137 @@
+import blakejs from 'blakejs';
+const { blake2bHex } = blakejs;
+import { type BlockInfo } from '../blockchain/types.js';
+
+export { select, getAllPredicate, filterBestTip };
+
+function getAllPredicate<T>(array: T[], predicate: (arg: T) => boolean) {
+  const data: T[] = [];
+  for (let i = 0; i < array.length; i++) {
+    if (predicate(array[i])) {
+      data.push(array[i]);
+    }
+  }
+  return data;
+}
+
+function filterBestTip<T extends { blockInfo: BlockInfo }>(
+  eventOrActionData: T[]
+) {
+  const highestTipBlocks = getAllPredicate(
+    eventOrActionData,
+    (e) => e.blockInfo.distanceFromMaxBlockHeight === 0
+  );
+  if (highestTipBlocks.length > 1) {
+    const selectedBlock = chainSelect(highestTipBlocks);
+    const startIndex = eventOrActionData.length - highestTipBlocks.length;
+    eventOrActionData.splice(
+      startIndex,
+      highestTipBlocks.length,
+      selectedBlock
+    );
+  }
+}
+
+function chainSelect<T extends { blockInfo: BlockInfo }>(blocks: T[]) {
+  if (blocks.length === 1) return blocks[0];
+  let existing = blocks[0];
+  for (let i = 1; i < blocks.length; i++) {
+    existing = select(existing, blocks[i]);
+  }
+  return existing;
+}
+
+/**
+ * Selects the best chain based on Mina Protocol's short range tie breaker rules.
+ *
+ * This function mirrors the OCaml implementation and utilizes the short range rules specified
+ * here: https://github.com/MinaProtocol/mina/tree/develop/docs/specs/consensus#521-short-range-fork-rule
+ *
+ * The tie breaker rules are also more formally documented here: https://github.com/MinaProtocol/mina/tree/develop/docs/specs/consensus
+ *
+ * When comparing two chains:
+ * 1. Compare based on state hash.
+ * 2. If equal, fallback to VRF comparisons.
+ * 3. If still equal, use the chain length as the final determinant.
+ *
+ * @param {T} existing - The current chain.
+ * @param {T} candidate - The new chain to be compared against the current chain.
+ * @returns {T} - The chain that is considered the "best" based on the aforementioned criteria.
+ */
+function select<T extends { blockInfo: BlockInfo }>(
+  existing: T,
+  candidate: T
+): T {
+  const candidateHashIsBigger = compareWithCondition(
+    existing.blockInfo.stateHash,
+    candidate.blockInfo.stateHash,
+    compareStrings,
+    true
+  );
+
+  const candidateVRFIsBigger = compareWithCondition(
+    existing.blockInfo,
+    candidate.blockInfo,
+    compareVRF,
+    candidateHashIsBigger
+  );
+
+  const candidateLengthIsBigger = compareWithCondition(
+    existing.blockInfo,
+    candidate.blockInfo,
+    compareBlockChainLength,
+    candidateVRFIsBigger
+  );
+
+  return candidateLengthIsBigger ? candidate : existing;
+}
+
+/**
+ * Takes two values and compares them using the provided compare function.
+ *
+ * In our compare function, the following semantics should apply:
+ *  - If `a` is less than `b`, then a negative number should be returned.
+ *  - If `a` is greater than `b`, then a positive number should be returned.
+ *  - If `a` is equal to `b`, then 0 should be returned.
+ *
+ * When we call `compare`, if the result is negative, then `a` is returned.A positive result means `b` is returned.
+ * If the result is 0, then the `condition` is used to determine which value is returned.
+ * Meaning, if the `condition` is true, then `b` is returned. Otherwise, `a` is returned.
+ *
+ * @param a - The first value to compare
+ * @param b - The second value to compare
+ * @param compare - The function used to compare the two values
+ * @param condition - The condition used to determine which value is returned if the two values are equal
+ * @returns
+ */
+function compareWithCondition<T>(
+  a: T,
+  b: T,
+  compare: (a: T, b: T) => number,
+  condition: boolean
+): boolean {
+  const c = compare(a, b);
+  return c < 0 || (c === 0 && condition);
+}
+
+function compareStrings(a: string, b: string): number {
+  if (a > b) return 1;
+  if (a < b) return -1;
+  return 0;
+}
+
+function getHashOfVRF(vrfOutput: string): string {
+  /* last_vrf_output is a sequence of hex-digit pairs derived from a bitstring */
+  const vrfBuf = Buffer.from(vrfOutput, 'hex');
+  return blake2bHex(vrfBuf);
+}
+
+function compareVRF(existing: BlockInfo, candidate: BlockInfo): number {
+  const existingVRFHash = getHashOfVRF(existing.lastVrfOutput);
+  const candidateVRFHash = getHashOfVRF(candidate.lastVrfOutput);
+  return compareStrings(existingVRFHash, candidateVRFHash);
+}
+
+function compareBlockChainLength(existing: BlockInfo, candidate: BlockInfo) {
+  return existing.height - candidate.height;
+}

package/src/context.ts

@@ -0,0 +1,18 @@
+import { Span } from '@opentelemetry/sdk-trace-base';
+import { ArchiveNodeAdapter } from './db/archive-node-adapter/archive-node-adapter.js';
+import { DatabaseAdapter } from './db/archive-node-adapter/archive-node-adapter.interface.js';
+
+export { buildContext, GraphQLContext };
+
+interface GraphQLContext {
+  db_client: DatabaseAdapter;
+  [OPEN_TELEMETRY_GRAPHQL: symbol]: Span | undefined; // Will only be set if we are in the scope of a GraphQL request
+}
+
+async function buildContext(connectionString: string | undefined) {
+  const db_client = new ArchiveNodeAdapter(connectionString);
+  await db_client.checkSQLSchema();
+  return {
+    db_client,
+  };
+}

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

@@ -0,0 +1,23 @@
+import type { EventFilterOptionsInput } from '../../resolvers-types.js';
+import type {
+  Actions,
+  Events,
+  NetworkState,
+  Blocks,
+} from '../../blockchain/types.js';
+import type { BlockQueryInput, BlockSortByInput } from '../../resolvers-types.js';
+
+export interface DatabaseAdapter {
+  getEvents(input: EventFilterOptionsInput, options?: unknown): Promise<Events>;
+  getActions(
+    input: EventFilterOptionsInput,
+    options?: unknown
+  ): Promise<Actions>;
+  getNetworkState(options?: unknown): Promise<NetworkState>;
+  getBlocks(
+    query: BlockQueryInput | null | undefined,
+    limit: number | null | undefined,
+    sortBy: BlockSortByInput | null | undefined,
+    options: unknown
+  ): Promise<Blocks>;
+}

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

@@ -0,0 +1,101 @@
+import postgres from 'postgres';
+import type {
+  Actions,
+  Events,
+  NetworkState,
+  Blocks,
+} from '../../blockchain/types.js';
+import type { DatabaseAdapter } from './archive-node-adapter.interface.js';
+import type {
+  ActionFilterOptionsInput,
+  EventFilterOptionsInput,
+  BlockQueryInput,
+  BlockSortByInput,
+} from '../../resolvers-types.js';
+import { getTables, USED_TABLES } from '../../db/sql/events-actions/queries.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 { 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';
+
+export class ArchiveNodeAdapter implements DatabaseAdapter {
+  /**
+   * Connections are created lazily once a query is created.
+   * This means that simply doing const sql = postgres(...) won't have any
+   * effect other than instantiating a new sql instance. Because of this, sharing the
+   * `postgres.Sql` instance across the adapter is safe.
+   */
+  private client: postgres.Sql;
+  private eventsService: IEventsService;
+  private actionsService: IActionsService;
+  private networkService: INetworkService;
+  private blocksService: IBlocksService;
+
+  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.eventsService = new EventsService(this.client);
+    this.actionsService = new ActionsService(this.client);
+    this.networkService = new NetworkService(this.client);
+    this.blocksService = new BlocksService(this.client);
+  }
+
+  async getEvents(
+    input: EventFilterOptionsInput,
+    options: unknown
+  ): Promise<Events> {
+    return this.eventsService.getEvents(input, options);
+  }
+
+  async getActions(
+    input: ActionFilterOptionsInput,
+    options: unknown
+  ): Promise<Actions> {
+    return this.actionsService.getActions(input, options);
+  }
+
+  async getNetworkState(options: unknown): Promise<NetworkState> {
+    return this.networkService.getNetworkState(options);
+  }
+
+  async getBlocks(
+    query: BlockQueryInput | null | undefined,
+    limit: number | null | undefined,
+    sortBy: BlockSortByInput | null | undefined,
+    options: unknown
+  ): Promise<Blocks> {
+    return this.blocksService.getBlocks(query, limit, sortBy, options);
+  }
+
+  async checkSQLSchema() {
+    let tables;
+    try {
+      tables = await (
+        await getTables(this.client)
+      ).map((table) => table.tablename);
+    } catch (e) {
+      throw new Error(
+        `Could not connect to Postgres with the specified connection string. Please check that Postgres is available and that your connection string is correct and try again.\nReason: ${e}`
+      );
+    }
+
+    for (const table of USED_TABLES) {
+      if (!tables.includes(table)) {
+        throw new Error(
+          `Missing table ${table}. Please make sure the table exists in the database.`
+        );
+      }
+    }
+  }
+
+  async close() {
+    return this.client.end();
+  }
+}