Add fetch events to network API

CHANGELOG.md

@@ -19,6 +19,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > No unreleased changes yet
 
+### 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.
+
 ## [0.9.2](https://github.com/o1-labs/snarkyjs/compare/9c44b9c2...1abdfb70)
 
 ### Added

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
@@ -452,6 +466,112 @@ function sendZkappQuery(json: string) {
 `;
 }
 
+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
+    }
+    eventData {
+      index
+      data
+    }
+  }
+}
+`;
+};
+
+type EventActionFilterOptions = {
+  to?: UInt32;
+  from?: UInt32;
+};
+
+/**
+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 and block height 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 = {}
+): Promise<any> {
+  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;
+  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: any) => {
+        return event.blockInfo.distanceFromMaxBlockHeight !== 0;
+      });
+      break;
+    }
+  }
+
+  return fetchedEvents.map((event: any) => {
+    const events = event.eventData.map(
+      (eventData: { index: string; data: string[] }) => {
+        return [eventData.index].concat(eventData.data);
+      }
+    );
+    return {
+      events,
+      height: event.blockInfo.height,
+    };
+  });
+}
+
 // removes the quotes on JSON keys
 function removeJsonQuotes(json: string) {
   let cleaned = JSON.stringify(JSON.parse(json), null, 2);

src/lib/mina.ts

@@ -320,7 +320,11 @@ interface Mina {
   };
   accountCreationFee(): UInt64;
   sendTransaction(transaction: Transaction): Promise<TransactionId>;
-  fetchEvents: (publicKey: PublicKey, tokenId?: Field) => any;
+  fetchEvents: (
+    publicKey: PublicKey,
+    tokenId?: Field,
+    filterOptions?: Fetch.EventActionFilterOptions
+  ) => any;
   getActions: (
     publicKey: PublicKey,
     tokenId?: Field
@@ -460,7 +464,7 @@ function LocalBlockchain({
           }
           events[addr][tokenId].push({
             events: p.body.events,
-            slot: networkState.globalSlotSinceGenesis.toString(),
+            height: networkState.blockchainLength.toString(),
           });
         }
 
@@ -587,9 +591,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
@@ -755,9 +776,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 await Fetch.fetchEvents(
+        { publicKey: pubKey, tokenId: token },
+        archiveEndpoint,
+        filterOptions
       );
     },
     getActions() {
@@ -837,7 +867,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() {
@@ -975,8 +1005,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);
 }
 
 /**

src/lib/zkapp.ts

@@ -1036,21 +1036,36 @@ super.init();
   }
 
   /**
-   * Fetches a list of events that have been emitted by this {@link SmartContract}.
-   */
+    Asynchronously fetches events emitted by this {@link SmartContract} and returns an array of events with their corresponding types.
+    @async
+    @param [start=UInt32.from(0)] - The start height of the events to fetch.
+    @param end - The end height of the events to fetch. If not provided, fetches events up to the latest height.
+    @returns A promise that resolves to an array of objects, each containing the event type and event data for the specified range.
+    @throws If there is an error fetching events from the Mina network.
+    @example
+    const startHeight = UInt32.from(1000);
+    const endHeight = UInt32.from(2000);
+    const events = await myZkapp.fetchEvents(startHeight, endHeight);
+    console.log(events);
+  */
   async fetchEvents(
     start: UInt32 = UInt32.from(0),
     end?: UInt32
   ): Promise<{ type: string; event: ProvablePure<any> }[]> {
     // filters all elements so that they are within the given range
     // only returns { type: "", event: [] } in a flat format
-    let events = (await Mina.fetchEvents(this.address, this.self.body.tokenId))
+    let events = (
+      await Mina.fetchEvents(this.address, this.self.body.tokenId, {
+        from: start,
+        to: end,
+      })
+    )
       .filter((el: any) => {
-        let slot = UInt32.from(el.slot);
+        let height = UInt32.from(el.height);
         return end === undefined
-          ? start.lessThanOrEqual(slot).toBoolean()
-          : start.lessThanOrEqual(slot).toBoolean() &&
-              slot.lessThanOrEqual(end).toBoolean();
+          ? start.lessThanOrEqual(height).toBoolean()
+          : start.lessThanOrEqual(height).toBoolean() &&
+              height.lessThanOrEqual(end).toBoolean();
       })
       .map((el: any) => el.events)
       .flat();