Feat/query module

packages/api/src/graphql/modules/MempoolResolver.ts

@@ -10,6 +10,7 @@ import {
 import { inject } from "tsyringe";
 import { IsNumberString } from "class-validator";
 import {
+  InclusionStatus,
   Mempool,
   PendingTransaction,
   TransactionStorage,
@@ -106,13 +107,6 @@ export class TransactionObject {
   }
 }
 
-export enum InclusionStatus {
-  UNKNOWN = "unknown",
-  PENDING = "pending",
-  INCLUDED = "included",
-  SETTLED = "settled",
-}
-
 registerEnumType(InclusionStatus, {
   name: "InclusionStatus",
 });

packages/sdk/package.json

@@ -29,7 +29,8 @@
     "@proto-kit/module": "*",
     "@proto-kit/protocol": "*",
     "@proto-kit/sequencer": "*",
-    "o1js": "^1.6.0",
+    "@proto-kit/api": "*",
+    "o1js": "^2.10.0",
     "tsyringe": "^4.10.0"
   },
   "devDependencies": {

packages/sdk/src/client/ClientAppChain.ts

@@ -29,6 +29,8 @@ import {
   AppChain,
   AppChainModule,
   MinimalAppChainDefinition,
+  BlockExplorerQuery,
+  BlockExplorerTransportModule,
 } from "@proto-kit/sequencer";
 import { container } from "tsyringe";
 import { Field, PublicKey, UInt64 } from "o1js";
@@ -40,6 +42,7 @@ import { GraphqlTransactionSender } from "../graphql/GraphqlTransactionSender";
 import { Signer } from "../transaction/InMemorySigner";
 import { AppChainTransaction } from "../transaction/AppChainTransaction";
 import { TransactionSender } from "../transaction/InMemoryTransactionSender";
+import { GraphqlBlockExplorerTransportModule } from "../graphql/GraphqlBlockExplorerTransportModule";
 
 export type InferModules<Container extends TypedClass<ModuleContainer<any>>> =
   Container extends TypedClass<infer Type>
@@ -77,6 +80,7 @@ export class ClientAppChain<
       TransactionSender: GraphqlTransactionSender,
       QueryTransportModule: GraphqlQueryTransportModule,
       NetworkStateTransportModule: GraphqlNetworkStateTransportModule,
+      BlockExplorerTransportModule: GraphqlBlockExplorerTransportModule,
     });
 
     appChain.configurePartial({
@@ -86,6 +90,7 @@ export class ClientAppChain<
       TransactionSender: {},
       QueryTransportModule: {},
       NetworkStateTransportModule: {},
+      BlockExplorerTransportModule: {},
     });
 
     /**
@@ -200,6 +205,7 @@ export class ClientAppChain<
       InferModules<AppChainModules["Protocol"]>
     >;
     network: NetworkStateQuery;
+    explorer: BlockExplorerQuery;
   } {
     const queryTransportModule = this.container.resolve<QueryTransportModule>(
       "QueryTransportModule"
@@ -210,7 +216,13 @@ export class ClientAppChain<
         "NetworkStateTransportModule"
       );
 
+    const blockExplorerTransportModule =
+      this.container.resolve<BlockExplorerTransportModule>(
+        "BlockExplorerTransportModule"
+      );
+
     const network = new NetworkStateQuery(networkStateTransportModule);
+    const explorer = new BlockExplorerQuery(blockExplorerTransportModule);
 
     return {
       runtime: QueryBuilderFactory.fromRuntime(
@@ -224,6 +236,8 @@ export class ClientAppChain<
       ),
 
       network,
+
+      explorer,
     };
   }
 }

packages/sdk/src/graphql/GraphqlBlockExplorerTransportModule.ts

@@ -0,0 +1,83 @@
+import { inject, injectable } from "tsyringe";
+import { gql } from "@urql/core";
+import {
+  AppChainModule,
+  Block,
+  BlockExplorerTransportModule,
+  InclusionStatus
+} from "@proto-kit/sequencer";
+
+import { GraphqlClient } from "./GraphqlClient";
+
+@injectable()
+export class GraphqlBlockExplorerTransportModule
+  extends AppChainModule
+  implements BlockExplorerTransportModule
+{
+  public constructor(
+    @inject("GraphqlClient") private readonly graphqlClient: GraphqlClient
+  ) {
+    super();
+  }
+
+  public async waitTxInclusion(txHash: string): Promise<InclusionStatus> {
+    const query = gql`
+      query transactionState($hash: String!) {
+        transactionState(hash: $hash)
+      }
+    `;
+
+    const queryResult = await this.graphqlClient.client
+      .query(query, { hash: txHash })
+      .toPromise();
+
+    if (queryResult.error) {
+      throw new Error(`Error in waitTxInclusion query: ${queryResult.error}`);
+    }
+
+    return queryResult.data?.transactionState;
+  }
+
+  async getBlock(param?: string | number): Promise<Block> {
+    let hash: string | undefined;
+    let height: number | undefined;
+
+    if (typeof param === "string") {
+      hash = param;
+    } else if (typeof param === "number") {
+      height = param;
+    }
+
+    const query = gql`
+      query block($hash: String, $height: Float) {
+        block(hash: $hash, height: $height) {
+          hash
+          previousBlockHash
+          height
+          txs {
+            tx {
+              methodId
+              nonce
+              sender
+              argsFields
+              auxiliaryData
+            }
+            status
+            statusMessage
+          }
+          transactionsHash
+        }
+      }
+    `;
+
+    const queryResult = await this.graphqlClient.client
+      .query(query, { hash, height })
+      .toPromise();
+
+    if (queryResult.error) {
+      throw new Error("Error fetching block!");
+    }
+
+    return queryResult.data;
+  }
+}

packages/sdk/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./query/StateServiceQueryModule";
 export * from "./query/BlockStorageNetworkStateModule";
+export * from "./query/InMemoryBlockExplorer";
 export * from "./transaction/AppChainTransaction";
 export * from "./transaction/InMemorySigner";
 export * from "./transaction/InMemoryTransactionSender";
@@ -8,5 +9,6 @@ export * from "./graphql/GraphqlClient";
 export * from "./graphql/GraphqlQueryTransportModule";
 export * from "./graphql/GraphqlTransactionSender";
 export * from "./graphql/GraphqlNetworkStateTransportModule";
+export * from "./graphql/GraphqlBlockExplorerTransportModule";
 export * from "./client/ClientAppChain";
 export * from "./testing/TestingAppChain";

packages/sdk/src/query/InMemoryBlockExplorer.ts

@@ -0,0 +1,70 @@
+import { inject, injectable } from "tsyringe";
+import {
+  AppChainModule,
+  Block,
+  BlockExplorerTransportModule,
+  BlockStorage,
+  ClientBlock,
+  TransactionStorage,
+  InclusionStatus
+} from "@proto-kit/sequencer";
+import { ModuleContainerLike } from "@proto-kit/common";
+
+@injectable()
+export class InMemoryBlockExplorer
+  extends AppChainModule
+  implements BlockExplorerTransportModule
+{
+  private readonly blockStorage: BlockStorage;
+
+  private readonly transactionStorage: TransactionStorage;
+
+  public constructor(
+    @inject("Sequencer") public sequencer: ModuleContainerLike
+  ) {
+    super();
+    this.blockStorage =
+      sequencer.dependencyContainer.resolve<BlockStorage>("BlockStorage");
+    this.transactionStorage =
+      sequencer.dependencyContainer.resolve<TransactionStorage>(
+        "TransactionStorage"
+      );
+  }
+
+  public async waitTxInclusion(txHash: string): Promise<InclusionStatus> {
+    const dbTx = await this.transactionStorage.findTransaction(txHash);
+
+    if (dbTx?.block !== undefined) {
+      return InclusionStatus.INCLUDED;
+    }
+
+    return InclusionStatus.UNKNOWN;
+  }
+
+  async getBlock(param?: string | number): Promise<ClientBlock | undefined> {
+    let hash: string | undefined;
+    let height: number | undefined;
+
+    if (typeof param === "string") {
+      hash = param;
+    } else if (typeof param === "number") {
+      height = param;
+    }
+
+    let block: Block | undefined;
+
+    if (hash !== undefined) {
+      block = await this.blockStorage.getBlock(hash);
+    } else {
+      const blockHeight =
+        height ?? (await this.blockStorage.getCurrentBlockHeight()) - 1;
+      block = await this.blockStorage.getBlockAt(blockHeight);
+    }
+
+    if (block !== undefined) {
+      return block;
+    }
+
+    return undefined;
+  }
+}

packages/sequencer/src/helpers/query/BlockExplorerQuery.ts

@@ -0,0 +1,79 @@
+import { inject, injectable } from "tsyringe";
+import { sleep } from "@proto-kit/common";
+import { BlockExplorerTransportModule, ClientBlock } from "./BlockExplorerTransportModule";
+
+export enum InclusionStatus {
+  UNKNOWN = "unknown",
+  PENDING = "pending",
+  INCLUDED = "included",
+  SETTLED = "settled",
+}
+
+export type TransactionFetcher = (txHash: string) => Promise<InclusionStatus>;
+
+@injectable()
+export class BlockExplorerQuery {
+  public constructor(
+    @inject("BlockExplorerTransportModule")
+    private readonly blockExplorer: BlockExplorerTransportModule
+  ) {}
+
+  /**
+   * Waits for a transaction to be included in a block by polling at regular intervals.
+   *
+   * @param txHash - Hash string of the transaction to search for
+   * @param interval - Polling interval in milliseconds (default: 1000)
+   * @param maxAttempts - Maximum number of polling attempts (default: 10)
+   * @returns Promise resolving to an object containing the transaction inclusion state
+   *
+   * @example
+   * ```typescript
+   * // Wait with default settings (1s interval, 10 attempts)
+   * const result = await blockExplorer.waitTxInclusion(txHash);
+   *
+   * // Wait with custom interval (500ms) and more attempts (20)
+   * const result = await blockExplorer.waitTxInclusion(txHash, 500, 20);
+   * ```
+   */
+  public async waitTxInclusion(
+    txHash: string,
+    interval = 1000,
+    maxAttempts = 10
+  ): Promise<{ transactionState: InclusionStatus }> {
+    let remainingAttempts = maxAttempts;
+
+    while (true) {
+      const status = await this.blockExplorer.waitTxInclusion(txHash);
+      console.log("from transport: ", status);
+      if (status === "INCLUDED") {
+        return { transactionState: InclusionStatus.INCLUDED };
+      }
+
+      remainingAttempts -= 1;
+
+      if (remainingAttempts <= 0) {
+        return { transactionState: InclusionStatus.UNKNOWN };
+      }
+      console.log("baybay");
+      await sleep(interval);
+    }
+  }
+
+  /**
+   * Retrieves a block by its hash or height.
+   *
+   * @param {string|number} [param] - Block hash (string) or block height (number). If omitted, returns the latest block.
+   * @returns {Promise<BlockModel|undefined>} Promise resolving to a BlockModel object, or undefined if block is not found
+   *
+   * @example
+   * // Get block by hash
+   * const block = await blockExplorer.getBlock("216543...");
+   *
+   * @example
+   * // Get block by height
+   * const block = await blockExplorer.getBlock(42);
+   */
+  async getBlock(param?: string | number): Promise<ClientBlock | undefined> {
+    return await this.blockExplorer.getBlock(param);
+  }
+}

packages/sequencer/src/helpers/query/BlockExplorerTransportModule.ts

@@ -0,0 +1,8 @@
+import { Block } from "../../storage/model/Block";
+
+export type ClientBlock = Pick<Block, "hash" | "previousBlockHash" | "height" | "transactions" | "transactionsHash">;
+
+export interface BlockExplorerTransportModule {
+  waitTxInclusion(txHash: string): Promise<string>;
+  getBlock(param?: string | number): Promise<ClientBlock | undefined>;
+}

packages/sequencer/src/index.ts

@@ -84,6 +84,8 @@ export * from "./helpers/query/QueryTransportModule";
 export * from "./helpers/query/QueryBuilderFactory";
 export * from "./helpers/query/NetworkStateQuery";
 export * from "./helpers/query/NetworkStateTransportModule";
+export * from "./helpers/query/BlockExplorerQuery";
+export * from "./helpers/query/BlockExplorerTransportModule";
 export * from "./state/prefilled/PreFilledStateService";
 export * from "./state/async/AsyncMerkleTreeStore";
 export * from "./state/async/AsyncStateService";

packages/stack/test/graphql/graphql-server.ts

@@ -4,6 +4,7 @@ import {
   InMemorySigner,
   InMemoryTransactionSender,
   StateServiceQueryModule,
+  InMemoryBlockExplorer,
 } from "@proto-kit/sdk";
 import { PrivateKey, PublicKey } from "o1js";
 import { Runtime, runtimeMethod, runtimeModule } from "@proto-kit/module";
@@ -125,6 +126,7 @@ export async function startGraphqlServer() {
     TransactionSender: InMemoryTransactionSender,
     QueryTransportModule: StateServiceQueryModule,
     NetworkStateTransportModule: BlockStorageNetworkStateModule,
+    BlockExplorerTransportModule: InMemoryBlockExplorer,
   });
 
   appChain.configure({
@@ -208,6 +210,7 @@ export async function startGraphqlServer() {
     Signer: {
       signer: PrivateKey.random(),
     },
+    BlockExplorerTransportModule: {},
   });
 
   await appChain.start(false, container.createChildContainer());