In this guide, we will set up a project that uses Checkpoint to expose data.

Setup the starter template project

First, clone the Checkpoint starter template project that can be found at: https://github.com/snapshot-labs/checkpoint-template.

To successfully, follow this guide and run the template project, you'll need the following dependencies set up on your computer:

  • Node.js (>=14.x.x)

  • Yarn

  • MySQL (or Docker to quickly run an image).

1. Setup dependencies

First, install Node dependencies by running the following command in the project's directory:


2. Run project

Checkpoint projects (and by extension this template) require a MySQL database connection to store indexed data. If you have a MySQL server running, then create a copy of the .env.example file and name .env. Then update the DATABASE_URL value in the .env file to match the connection string to your database.

If you have Docker on your computer, you can quickly startup a MySQL server by running the following command in a separate terminal:

docker run \
    -it -p 3306:3306 \
    -e MYSQL_ROOT_PASSWORD="default_password" \
    -e MYSQL_DATABASE="checkpoint" mysql:8.0 \

And then you can use mysql://root:default_password@localhost:3306/checkpoint as your .env files DATABASE_URL value .

Next, start the server by running:

yarn dev

This will start the indexing process and also startup the GraphQL server for querying indexed information.

Querying the API data

This starter project defines a Post entity in its src/schema.gql schema file and is setup to write data based on that structure. Read more on how Entity schemas are used to generate GraphQL queries here.

Now that the server is running, open up your browser and visit http://localhost:3000. This will show a GraphiQL interface to explore the exposed data.

Try executing the following query:

query {
  posts {

You should get a response similar to the one in this image:

The response to your queries depends on how much on-chain data Checkpoint has indexed. If the server has run long enough, you'll get more results. Checkpoint exposes a _metadata query, which can be used to track the latest block it has indexed. Example of this is:

query {
  _metadata(id: "last_indexed_block") {

Template project structure

Here is a quick description of important files within the template project and what each does.

├── src
│   ├── checkpoints.json
│   ├── config.json
│   ├── index.ts
│   ├── schema.gql
│   ├── utils.ts
│   └── writers.ts
  • src/schema.gql: Defines the Post entity Checkpoint uses to generate API queries.

  • src/config.json: Defines the CheckpointConfiguration object used to initialize Checkpoint and it contains the details of a Poster contract deployed to the goerli-alpha network.

  • src/writers.ts: Defines the Writers responsible for writing Post data whenever Checkpoint encounters a new_post event.

  • src/index.ts: This is the entrypoint, that initializes Checkpoint, starts its indexer and also exposes the graphql API.

  • src/checkpoints.json: Defines blocks where we are sure the contracts events exists. This is used to seed checkpoint inside the index.ts file to speed up Checkpoints indexing.

You are encouraged to try modifying the template project to understand how Checkpoint works and quickly get started using it to index your contracts data on Starknet.

Last updated