Add fetch events to network API

[MartinMinkov]

Description

This PR supports fetching events from a GraphQL API that implements the following schema. It aims to keep the API functionality as the existing fetch events API.

The following changes have been made:

1. Add method overloading to the Mina.Network function to take in an object that can specify an endpoint to be used for the archive API.
2. Add support to fetch events from the archive API in the Fetch module. Fetching events is done by the newly added fetchEvents function that is exposed.
3. Refactor the existing fetchEvents function inside zkapp.ts to filter by block heights instead of slots.

Impact

By adding a way to fetch events for SnarkyJS, zkApps can now reliably fetch its event data from a datastore (like the Archive Node). This unlocks many use cases as Events can notify that the state has changed or even as a basic solution to off-chain storage.

Tested

Manual testing uses an internally deployed archive API and matching deployed zkApp to fetch events.

If you wish to test the newly added functionality, run this build and use this script:

import {
  Field,
  state,
  State,
  UInt32,
  fetchEvents,
  method,
  PrivateKey,
  SmartContract,
  Mina,
  isReady,
  shutdown,
  PublicKey,
  Reducer,
  Permissions,
} from 'snarkyjs';

await isReady;

const INCREMENT = Field(1);

export class SimpleZkapp extends SmartContract {
  @state(Field) x = State<Field>();
  @state(Field) y = State<Field>();

  @state(Field) counter = State<Field>();
  @state(Field) actionsHash = State<Field>();

  events = {
    updateValue: Field,
    newState: Field,
    address: PublicKey,
  };

  reducer = Reducer({ actionType: Field });

  init(zkappKey: PrivateKey) {
    super.init(zkappKey);
    this.x.set(initialState);
    this.y.set(Field(0));
    this.counter.set(Field(0));
    this.actionsHash.set(Reducer.initialActionsHash);
    this.account.permissions.set({
      ...Permissions.default(),
      send: Permissions.proofOrSignature(),
      receive: Permissions.proofOrSignature(),
    });
  }

  @method rollupIncrements() {
    // get previous counter & actions hash, assert that they're the same as on-chain values
    let counter = this.counter.get();
    this.counter.assertEquals(counter);
    let actionsHash = this.actionsHash.get();
    this.actionsHash.assertEquals(actionsHash);

    // compute the new counter and hash from pending actions
    let pendingActions = this.reducer.getActions({
      fromActionHash: actionsHash,
    });

    let { state: newCounter, actionsHash: newActionsHash } =
      this.reducer.reduce(
        pendingActions,
        // state type
        Field,
        // function that says how to apply an action
        (state: Field, _action: Field) => {
          return state.add(1);
        },
        { state: counter, actionsHash }
      );

    // update on-chain state
    this.counter.set(newCounter);
    this.actionsHash.set(newActionsHash);
  }

  @method update(z: Field): Field {
    this.emitEvent('updateValue', z);
    let x = this.x.get();
    this.x.assertEquals(x);
    let newX = x.add(z);
    this.x.set(newX);
    this.y.set(z);
    this.emitEvent('newState', newX);
    this.emitEvent('address', this.address);

    this.reducer.dispatch(INCREMENT);

    return newX;
  }
}

let Berkeley = Mina.Network({
  mina: 'https://proxy.berkeley.minaexplorer.com/graphql',
  archive: 'https://archive.berkeley.minaexplorer.com/',
});
Mina.setActiveInstance(Berkeley);

// the zkapp account
const address = PublicKey.fromBase58(
  'B62qrfn5xxChtPGJne9HuDJZ4ziWVgWxeL3hntGBqMmf45p4hudo3tw'
);
let initialState = Field(1);
let zkapp = new SimpleZkapp(address);

console.log('---- emitted events: ----');
// fetches all events from zkapp starting block 0
let events = await zkapp.fetchEvents(UInt32.from(0));
console.log(events);
console.log('---- emitted events: ----');
// fetches all events starting at block 560 and ending at block 600
events = await zkapp.fetchEvents(UInt32.from(560), UInt32.from(600));
console.log(events);
console.log('---- emitted events: ----');
// fetches all events
events = await zkapp.fetchEvents();
console.log(events);
console.log('---- emitted events: ----');
events = await fetchEvents({
  publicKey: 'B62qrfn5xxChtPGJne9HuDJZ4ziWVgWxeL3hntGBqMmf45p4hudo3tw',
});
console.log(events);
await shutdown();

Example Output

When fetching events locally, events will look like:

let events = await zkapp.fetchEvents();
// Returned
[
  {
    type: 'simpleEvent',
    event: { value: [Array] },
    blockHeight: '0',
    blockHash: '',
    parentBlockHash: '',
    globalSlot: '0',
    chainStatus: '',
    transactionHash: '',
    transactionStatus: '',
    transactionMemo: ''
  },
  {
    type: 'complexEvent',
    event: Event { pub: [PublicKey], value: [Object] },
    blockHeight: '0',
    blockHash: '',
    parentBlockHash: '',
    globalSlot: '0',
    chainStatus: '',
    transactionHash: '',
    transactionStatus: '',
    transactionMemo: ''
  },
...
]

Fetching using the network API, with the script above looks like:

let events = await zkapp.fetchEvents();
// Returned
[
  {
    type: 'address',
    event: PublicKey { x: [Object], isOdd: [Object] },
    blockHeight: 600,
    blockHash: '3NKhg5GcmczaffFMRienet3doYuyzZ1Pe6CLpmioqTFWenaEhVBE',
    parentBlockHash: '3NLxzAPngJYcAPVHXsxyEnsbn2AeDPNP6MRKUg1iaEKRzBVzaMaw',
    globalSlot: 1519,
    chainStatus: 'canonical',
    transactionHash: '5JubYLuiRuBYn4JcHFBBnKC2HoLd9YDMRKKfmK15rsH1mt7MLhud',
    transactionStatus: 'applied',
    transactionMemo: 'E4YM2vTHhWEg66xpj52JErHUBU4pZ1yageL4TVDDpTTSsv8mK6YaH'
  },
  {
    type: 'newState',
    event: { value: [Array] },
    blockHeight: 600,
    blockHash: '3NKhg5GcmczaffFMRienet3doYuyzZ1Pe6CLpmioqTFWenaEhVBE',
    parentBlockHash: '3NLxzAPngJYcAPVHXsxyEnsbn2AeDPNP6MRKUg1iaEKRzBVzaMaw',
    globalSlot: 1519,
    chainStatus: 'canonical',
    transactionHash: '5JubYLuiRuBYn4JcHFBBnKC2HoLd9YDMRKKfmK15rsH1mt7MLhud',
    transactionStatus: 'applied',
    transactionMemo: 'E4YM2vTHhWEg66xpj52JErHUBU4pZ1yageL4TVDDpTTSsv8mK6YaH'
  },
  {
    type: 'updateValue',
    event: { value: [Array] },
    blockHeight: 600,
    blockHash: '3NKhg5GcmczaffFMRienet3doYuyzZ1Pe6CLpmioqTFWenaEhVBE',
    parentBlockHash: '3NLxzAPngJYcAPVHXsxyEnsbn2AeDPNP6MRKUg1iaEKRzBVzaMaw',
    globalSlot: 1519,
    chainStatus: 'canonical',
    transactionHash: '5JubYLuiRuBYn4JcHFBBnKC2HoLd9YDMRKKfmK15rsH1mt7MLhud',
    transactionStatus: 'applied',
    transactionMemo: 'E4YM2vTHhWEg66xpj52JErHUBU4pZ1yageL4TVDDpTTSsv8mK6YaH'
  }
  ...
]

[Trivo25]

awesome! Just left a few comments :)

[mitschabaude]

Very nice! I have a few comments mostly about type safety

[mitschabaude]

Looks great to me! I have some feedback regarding the event types we expose, but that could be addressed elsewhere if we want to get this out quickly