Project Structure

This page provides an overview of the project structure of a blockflow project. It covers top-level files and folders, configuration file, and schema file.

Click the file and folder names to learn more about each convention.


Top-Level Folders

After completing the project initiation step, the CLI generates a folder structure with all the necessary boilerplate code set up. Let's explore this folder structure in detail:


studio.yaml

The studio.yaml file is a crucial component of your project. It serves as the main configuration file, defining the structure and behaviour of your indexer.

name: cli-demo
description: a project to showcase cli working
startBlock: latest
userId: XXXXXXXX-XXXX-XXXX-XXXXXXXX-XXXXXXXX
projectId: XXXXXXXX-XXXX-XXXX-XXXXXXXX-XXXXXXXX
network: Ethereum
user: Jane-doe
schema:
  file: ./studio.schema.ts
execution: parallel
Resources:
  - Name: usdt
    Abi: src/abis/usdt.json
    Type: contract/event
    Address: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
    Triggers:
      - Event: Transfer(address indexed,address indexed,uint256)
        Handler: src/handlers/usdt/Transfer.TransferHandler

This YAML file specifies the details of the subgraph, including:

  • The blockchain network it will connect to (e.g., Ethereum, Polygon, etc.)

  • The smart contracts it will index and their addresses

  • The events and data entities to be indexed from those contracts

  • The mapping functions that transform the raw blockchain data into the desired format


studio.schema.ts

The studio.schema.ts file is a TypeScript file responsible for defining the data model or schema of your database. It specifies the entities and their relationships within the indexed blockchain data.

import { String, Number } from "@blockflow-labs/utils";

export interface Transfer {
  id: String;
  from_address: string;
  to_address: string;
  amount: Number;
}

In this file, you define the structure of the data entities that will be stored in the database. These entities represent the various types of data you want to index from the blockchain, such as smart contracts, events, and any relevant data associated with them.

Remember no comments are allowed in studio.schema.ts

Once done with defining the schema. You need to run below code to get started.

blockflow typegen

A types folder will generated inside src folder containing schema.ts file.


handlers

The mapping functions defined in the handlers directory are automatically triggered and executed whenever a specific event or function is emitted or called on the blockchain. Each mapping function is associated with a particular event or function from the smart contracts being indexed defined in studio.yaml file.

To generate boilerplate code for these handler use below command.

blockflow codegen

Here, an example of handler's boilerplate code.

import {
  IEventContext,
  IBind,
  Instance,
  ISecrets,
} from "@blockflow-labs/utils";

/**
 * @dev Event::Transfer(address from, address to, uint256 value)
 * @param context trigger object with contains {event: {from ,to ,value }, transaction, block, log}
 * @param bind init function for database wrapper methods
 */
export const TransferHandler = async (
  context: IEventContext,
  bind: IBind,
  secrets: ISecrets,
) => {
  // Implement your event handler logic for Transfer here

  const { event, transaction, block, log } = context;
  const { from, to, value } = event;
};

We will dive deeper into this code in handlers section.


abis

The abis folder is used to store the Application Binary Interface (ABI) files for the smart contracts being indexed.