watcher-ts/packages/graph-test-watcher

Example Watcher

Setup

First try the stack orchestrator to quickly get started. Advanced users can see here for instructions on setting up a local environment by hand.

Run the following command to install required packages:

yarn

Run

• In packages/graph-node, deploy an Example contract:

  yarn example:deploy
  

• Set the returned address to the variable $EXAMPLE_ADDRESS:

  EXAMPLE_ADDRESS=<EXAMPLE_ADDRESS>
  

• In packages/graph-node/test/subgraph/example1/subgraph.yaml:

  • Set the source address for Example1 datasource to the EXAMPLE_ADDRESS.
  • Set the startBlock less than or equal to the latest mined block.

• Build the example subgraph:

  yarn build:example
  

• Run the job-runner:

  yarn job-runner
  

• Run the watcher:

  yarn server
  

• The output from the block handler in the mapping code should be visible in the job-runner for each block.

• Run the following GQL subscription at the graphql endpoint http://127.0.0.1:3008/graphql

  subscription {
    onEvent {
      event {
        __typename
        ... on TestEvent {
          param1
          param2
        },
      },
      block {
        number
        hash
      }
    }
  }
  

• In packages/graph-node, trigger the Test event by calling a example contract method:

  yarn example:test --address $EXAMPLE_ADDRESS
  

  • A Test event shall be visible in the subscription at endpoint.

  • The subgraph entity Category should be updated in the database.

  • An auto-generated diff-staged entry State should be added.

• Run the query for entity in at the endpoint:

  query {
    category(
      block: { hash: "EVENT_BLOCK_HASH" },
      id: "1"
    ) {
      __typename
      id
      count
      name
    }
  }
  

• Run the getState query at the endpoint to get the latest State for EXAMPLE_ADDRESS:

  query {
    getState (
      blockHash: "EVENT_BLOCK_HASH"
      contractAddress: "EXAMPLE_ADDRESS"
      # kind: "checkpoint"
      # kind: "diff"
      kind: "diff_staged"
    ) {
      cid
      block {
        cid
        hash
        number
        timestamp
        parentHash
      }
      contractAddress
      data
    }
  }
  

• diff states get created corresponding to the diff_staged states when their respective blocks reach the pruned region.

• In packages/graph-test-watcher:

  • After the diff state has been created, create a checkpoint:

    yarn checkpoint create --address $EXAMPLE_ADDRESS
    

    • A checkpoint state should be created at the latest canonical block hash.

    • Run the getState query again at the endpoint with the output blockHash and kind checkpoint.

• All the State entries can be seen in pg-admin in table state.

Customize

• Indexing on an event:

  • Edit the custom hook function handleEvent (triggered on an event) in hooks.ts to perform corresponding indexing using the Indexer object.

  • While using the indexer storage methods for indexing, pass diff as true if default state is desired to be generated using the state variables being indexed.

• Generating state:

  • Edit the custom hook function createInitialState (triggered if the watcher passes the start block, checkpoint: true) in hooks.ts to save an initial State using the Indexer object.

  • Edit the custom hook function createStateDiff (triggered on a block) in hooks.ts to save the state in a diff State using the Indexer object. The default state (if exists) is updated.

  • Edit the custom hook function createStateCheckpoint (triggered just before default and CLI checkpoint) in hooks.ts to save the state in a checkpoint State using the Indexer object.

• The existing example hooks in hooks.ts are for an ERC20 contract.