Add fetch events to network API

CHANGELOG.md

@@ -17,6 +17,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/o1-labs/snarkyjs/compare/1abdfb70...HEAD)
 
+### Added
+
+- Added a new feature to the library: `fetchEvents` can now be used to fetch events for a specified zkApp from a GraphQL endpoint that implements the schema specified [here](https://github.com/o1-labs/Archive-Node-API/blob/efebc9fd3cfc028f536ae2125e0d2676e2b86cd2/src/schema.ts#L1). `Mina.Network` now accepts an additional endpoint to configure, which points to a GraphQL server running the mentioned schema. Use the `mina` property for normal usage and use `archive` to connect to the mentioned GraphQL server.
+
 ### Fixed
 
 - Added missing export of `Mina.TransactionId` https://github.com/o1-labs/snarkyjs/pull/785

src/examples/zkapps/local_events_zkapp.ts

@@ -86,14 +86,14 @@ await tx.prove();
 await tx.sign([feePayerKey]).send();
 
 console.log('---- emitted events: ----');
-// fetches all events from zkapp starting slot 0
+// fetches all events from zkapp starting block height 0
 let events = await zkapp.fetchEvents(UInt32.from(0));
 console.log(events);
 console.log('---- emitted events: ----');
-// fetches all events
-events = await zkapp.fetchEvents();
+// fetches all events from zkapp starting block height 0 and ending at block height 10
+events = await zkapp.fetchEvents(UInt32.from(0), UInt64.from(10));
 console.log(events);
 console.log('---- emitted events: ----');
-// fetches all events second time
+// fetches all events
 events = await zkapp.fetchEvents();
 console.log(events);

src/index.ts

@@ -47,6 +47,7 @@ export {
   fetchAccount,
   fetchLastBlock,
   fetchTransactionStatus,
+  fetchEvents,
   TransactionStatus,
   addCachedAccount,
   setGraphqlEndpoint,

src/lib/fetch.ts

@@ -24,24 +24,38 @@ export {
   fetchMissingData,
   fetchTransactionStatus,
   TransactionStatus,
+  EventActionFilterOptions,
   getCachedAccount,
   getCachedNetwork,
   addCachedAccount,
   defaultGraphqlEndpoint,
+  archiveGraphqlEndpoint,
   setGraphqlEndpoint,
+  setArchiveGraphqlEndpoint,
   sendZkappQuery,
   sendZkapp,
   removeJsonQuotes,
+  fetchEvents,
 };
 
 let defaultGraphqlEndpoint = 'none';
+let archiveGraphqlEndpoint = 'none';
 /**
  * Specifies the default GraphQL endpoint.
  */
 function setGraphqlEndpoint(graphqlEndpoint: string) {
   defaultGraphqlEndpoint = graphqlEndpoint;
 }
 
+/**
+ * Sets up a GraphQL endpoint to be used for fetching information from an Archive Node.
+ *
+ * @param A GraphQL endpoint.
+ */
+function setArchiveGraphqlEndpoint(graphqlEndpoint: string) {
+  archiveGraphqlEndpoint = graphqlEndpoint;
+}
+
 /**
  * Gets account information on the specified publicKey by performing a GraphQL query
  * to the specified endpoint. This will call the 'GetAccountInfo' query which fetches
@@ -451,6 +465,144 @@ function sendZkappQuery(json: string) {
 }
 `;
 }
+type FetchedEventActionBase = {
+  blockInfo: {
+    distanceFromMaxBlockHeight: number;
+    globalSlotSinceGenesis: number;
+    height: number;
+    stateHash: string;
+    parentHash: string;
+    chainStatus: string;
+  };
+  transactionInfo: {
+    hash: string;
+    memo: string;
+    status: string;
+  };
+};
+type FetchedEvents = {
+  eventData: {
+    index: string;
+    data: string[];
+  }[];
+} & FetchedEventActionBase;
+
+type EventActionFilterOptions = {
+  to?: UInt32;
+  from?: UInt32;
+};
+
+const getEventsQuery = (
+  publicKey: string,
+  tokenId: string,
+  filterOptions?: EventActionFilterOptions
+) => {
+  const { to, from } = filterOptions ?? {};
+  let input = `address: "${publicKey}", tokenId: "${tokenId}"`;
+  if (to !== undefined) {
+    input += `, to: ${to}`;
+  }
+  if (from !== undefined) {
+    input += `, from: ${from}`;
+  }
+  return `{
+  events(input: { ${input} }) {
+    blockInfo {
+      distanceFromMaxBlockHeight
+      height
+      globalSlotSinceGenesis
+      stateHash
+      parentHash
+      chainStatus
+    }
+    transactionInfo {
+      hash
+      memo
+      status
+    }
+    eventData {
+      data
+    }
+  }
+}`;
+};
+
+/**
+ * Asynchronously fetches event data for an account from the Mina Archive Node GraphQL API.
+ * @async
+ * @param accountInfo - The account information object.
+ * @param accountInfo.publicKey - The account public key.
+ * @param [accountInfo.tokenId] - The optional token ID for the account.
+ * @param [graphqlEndpoint=archiveGraphqlEndpoint] - The GraphQL endpoint to query. Defaults to the Archive Node GraphQL API.
+ * @param [filterOptions={}] - The optional filter options object.
+ * @returns A promise that resolves to an array of objects containing event data, block information and transaction information for the account.
+ * @throws If the GraphQL request fails or the response is invalid.
+ * @example
+ * const accountInfo = { publicKey: 'B62qiwmXrWn7Cok5VhhB3KvCwyZ7NHHstFGbiU5n7m8s2RqqNW1p1wF' };
+ * const events = await fetchEvents(accountInfo);
+ * console.log(events);
+ */
+async function fetchEvents(
+  accountInfo: { publicKey: string; tokenId?: string },
+  graphqlEndpoint = archiveGraphqlEndpoint,
+  filterOptions: EventActionFilterOptions = {}
+) {
+  if (!graphqlEndpoint)
+    throw new Error(
+      'fetchEvents: Specified GraphQL endpoint is undefined. Please specify a valid endpoint.'
+    );
+  const { publicKey, tokenId } = accountInfo;
+  let [response, error] = await makeGraphqlRequest(
+    getEventsQuery(
+      publicKey,
+      tokenId ?? TokenId.toBase58(TokenId.default),
+      filterOptions
+    ),
+    graphqlEndpoint
+  );
+  if (error) throw Error(error.statusText);
+  let fetchedEvents = response?.data.events as FetchedEvents[];
+  if (fetchedEvents === undefined) {
+    throw Error(
+      `Failed to fetch events data. Account: ${publicKey} Token: ${tokenId}`
+    );
+  }
+
+  // TODO: This is a temporary fix. We should be able to fetch the event/action data from any block at the best tip.
+  // Once https://github.com/o1-labs/Archive-Node-API/issues/7 is resolved, we can remove this.
+  // If we have multiple blocks returned at the best tip (e.g. distanceFromMaxBlockHeight === 0),
+  // then filter out the blocks at the best tip. This is because we cannot guarantee that every block
+  // at the best tip will have the correct event data or guarantee that the specific block data will not
+  // fork in anyway. If this happens, we delay fetching event data until another block has been added to the network.
+  let numberOfBestTipBlocks = 0;
+  for (let i = 0; i < fetchedEvents.length; i++) {
+    if (fetchedEvents[i].blockInfo.distanceFromMaxBlockHeight === 0) {
+      numberOfBestTipBlocks++;
+    }
+    if (numberOfBestTipBlocks > 1) {
+      fetchedEvents = fetchedEvents.filter((event) => {
+        return event.blockInfo.distanceFromMaxBlockHeight !== 0;
+      });
+      break;
+    }
+  }
+
+  return fetchedEvents.map((event) => {
+    let events = event.eventData.map((eventData) => eventData.data);
+
+    return {
+      events,
+      blockHeight: UInt32.from(event.blockInfo.height),
+      blockHash: event.blockInfo.stateHash,
+      parentBlockHash: event.blockInfo.parentHash,
+      globalSlot: UInt32.from(event.blockInfo.globalSlotSinceGenesis),
+      chainStatus: event.blockInfo.chainStatus,
+      transactionHash: event.transactionInfo.hash,
+      transactionStatus: event.transactionInfo.status,
+      transactionMemo: event.transactionInfo.memo,
+    };
+  });
+}
 
 // removes the quotes on JSON keys
 function removeJsonQuotes(json: string) {

src/lib/mina.ts

@@ -321,7 +321,11 @@ interface Mina {
   };
   accountCreationFee(): UInt64;
   sendTransaction(transaction: Transaction): Promise<TransactionId>;
-  fetchEvents: (publicKey: PublicKey, tokenId?: Field) => any;
+  fetchEvents: (
+    publicKey: PublicKey,
+    tokenId?: Field,
+    filterOptions?: Fetch.EventActionFilterOptions
+  ) => ReturnType<typeof Fetch.fetchEvents>;
   getActions: (
     publicKey: PublicKey,
     tokenId?: Field
@@ -461,7 +465,16 @@ function LocalBlockchain({
           }
           events[addr][tokenId].push({
             events: p.body.events,
-            slot: networkState.globalSlotSinceGenesis.toString(),
+            blockHeight: networkState.blockchainLength,
+            globalSlot: networkState.globalSlotSinceGenesis,
+            // The following fields are fetched from the Mina network. For now, we mock these values out
+            // since networkState does not contain these fields.
+            blockHash: '',
+            parentBlockHash: '',
+            chainStatus: '',
+            transactionHash: '',
+            transactionStatus: '',
+            transactionMemo: '',
           });
         }
 
@@ -543,10 +556,7 @@ function LocalBlockchain({
         JSON.stringify(networkState)
       );
     },
-    async fetchEvents(
-      publicKey: PublicKey,
-      tokenId: Field = TokenId.default
-    ): Promise<any[]> {
+    async fetchEvents(publicKey: PublicKey, tokenId: Field = TokenId.default) {
       return events?.[publicKey.toBase58()]?.[TokenId.toBase58(tokenId)] ?? [];
     },
     getActions(
@@ -588,9 +598,26 @@ LocalBlockchain satisfies (...args: any) => Mina;
 /**
  * Represents the Mina blockchain running on a real network
  */
-function Network(graphqlEndpoint: string): Mina {
+function Network(graphqlEndpoint: string): Mina;
+function Network(graphqlEndpoints: { mina: string; archive: string }): Mina;
+function Network(input: { mina: string; archive: string } | string): Mina {
   let accountCreationFee = UInt64.from(defaultAccountCreationFee);
-  Fetch.setGraphqlEndpoint(graphqlEndpoint);
+  let graphqlEndpoint: string;
+  let archiveEndpoint: string;
+
+  if (input && typeof input === 'string') {
+    graphqlEndpoint = input;
+    Fetch.setGraphqlEndpoint(graphqlEndpoint);
+  } else if (input && typeof input === 'object') {
+    graphqlEndpoint = input.mina;
+    archiveEndpoint = input.archive;
+    Fetch.setGraphqlEndpoint(graphqlEndpoint);
+    Fetch.setArchiveGraphqlEndpoint(archiveEndpoint);
+  } else {
+    throw new Error(
+      "Network: malformed input. Please provide a string or an object with 'mina' and 'archive' endpoints."
+    );
+  }
 
   // copied from mina/genesis_ledgers/berkeley.json
   // TODO fetch from graphql instead of hardcoding
@@ -756,9 +783,18 @@ function Network(graphqlEndpoint: string): Mina {
         isFinalRunOutsideCircuit: !hasProofs,
       });
     },
-    async fetchEvents() {
-      throw Error(
-        'fetchEvents() is not implemented yet for remote blockchains.'
+    async fetchEvents(
+      publicKey: PublicKey,
+      tokenId: Field = TokenId.default,
+      filterOptions: Fetch.EventActionFilterOptions = {}
+    ) {
+      let pubKey = publicKey.toBase58();
+      let token = TokenId.toBase58(tokenId);
+
+      return Fetch.fetchEvents(
+        { publicKey: pubKey, tokenId: token },
+        archiveEndpoint,
+        filterOptions
       );
     },
     getActions() {
@@ -838,7 +874,7 @@ let activeInstance: Mina = {
   async transaction(sender: DeprecatedFeePayerSpec, f: () => void) {
     return createTransaction(sender, f, 0);
   },
-  fetchEvents() {
+  fetchEvents(publicKey: PublicKey, tokenId: Field = TokenId.default) {
     throw Error('must call Mina.setActiveInstance first');
   },
   getActions() {
@@ -976,8 +1012,12 @@ async function sendTransaction(txn: Transaction) {
 /**
  * @return A list of emitted events associated to the given public key.
  */
-async function fetchEvents(publicKey: PublicKey, tokenId: Field) {
-  return await activeInstance.fetchEvents(publicKey, tokenId);
+async function fetchEvents(
+  publicKey: PublicKey,
+  tokenId: Field,
+  filterOptions: Fetch.EventActionFilterOptions = {}
+) {
+  return await activeInstance.fetchEvents(publicKey, tokenId, filterOptions);
 }
 
 /**