From bfdc8be94789e6d7e0fef184db33e78515b8974a Mon Sep 17 00:00:00 2001 From: 0xkenj1 Date: Thu, 7 Nov 2024 22:17:14 -0300 Subject: [PATCH 1/4] docs: update packages docs --- packages/data-flow/README.md | 28 ++++++- packages/indexer-client/README.md | 40 ++++++++++ packages/metadata/README.md | 28 +++++++ packages/pricing/README.md | 28 +++++++ packages/processors/README.md | 51 +++++++++++-- .../processors/src/allo/allo.processor.ts | 3 + packages/repository/README.md | 30 ++++++++ packages/shared/README.md | 73 ++++++------------- 8 files changed, 226 insertions(+), 55 deletions(-) diff --git a/packages/data-flow/README.md b/packages/data-flow/README.md index 65ce7fa..8fc4ce4 100644 --- a/packages/data-flow/README.md +++ b/packages/data-flow/README.md @@ -25,7 +25,7 @@ Available scripts that can be run using `pnpm`: You can import the package in your TypeScript or JavaScript files as follows: ```typescript -import { EventsFetcher } from "@grants-stack-indexer/data-flow"; +import { EventsFetcher, Orchestrator, EventsRegistry, EventsFetcher, EventsProcessor } from "@grants-stack-indexer/data-flow"; ``` ### Example @@ -43,3 +43,29 @@ const result = await eventsFetcher.fetcEventsByBlockNumberAndLogIndex( logIndex, ); ``` + +## API + +### [Orchestrator](./src/orchestrator.ts) + +The `Orchestrator` class is responsible for orchestrating the processing pipeline for the gitcoin grants-stack-indexer. + +### [EventsRegistry](./src/eventsRegistry.ts) + +The `EventsRegistry` class is responsible for registering processed events in the processing pipeline. + +### [EventsProcessor](./src/eventsProcessor.ts) + +The `EventsProcessor` class is responsible for processing events in the processing pipeline. + +### [EventsFetcher](./src/eventsFetcher.ts) + +The `EventsFetcher` class is responsible for fetching events from the blockchain. + +### [StrategyRegistry](./src/strategyRegistry.ts) + +The `StrategyRegistry` stores strategy IDs in memory to populate strategy events with them. + +### [DataLoader](./src/data-loader/dataLoader.ts) + +The `DataLoader` is responsible for applying changesets to the database.. diff --git a/packages/indexer-client/README.md b/packages/indexer-client/README.md index aa666be..1ffd989 100644 --- a/packages/indexer-client/README.md +++ b/packages/indexer-client/README.md @@ -18,6 +18,34 @@ Available scripts that can be run using `pnpm`: | `test` | Run tests using vitest | | `test:cov` | Run tests with coverage report | +## 📋 Prerequisites + +- Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed. + +## Installation + +```bash +$ pnpm install +``` + +## Building + +To build the monorepo packages, run: + +```bash +$ pnpm build +``` + +## Test + +```bash +# unit tests +$ pnpm run test + +# test coverage +$ pnpm run test:cov +``` + ## Usage ### Importing the Package @@ -34,3 +62,15 @@ import { EnvioIndexerClient } from "@grants-stack-indexer/indexer-client"; const envioIndexerClient = new EnvioIndexerClient("http://example.com/graphql", "secret"); await envioIndexerClient.getEventsByBlockNumberAndLogIndex(1, 12345, 0); ``` + +## API + +### [IIndexerClient](./src/interfaces/indexerClient.interface.ts) + +Available methods + +- `getEventsAfterBlockNumberAndLogIndex(chainId: ChainId, fromBlock: number, logIndex: number, limit?: number): Promise` + +## References + +- [Envio](https://docs.envio.dev/docs/HyperIndex/overview) diff --git a/packages/metadata/README.md b/packages/metadata/README.md index 65e714a..d36ff2d 100644 --- a/packages/metadata/README.md +++ b/packages/metadata/README.md @@ -22,6 +22,34 @@ Available scripts that can be run using `pnpm`: | `test` | Run tests using vitest | | `test:cov` | Run tests with coverage report | +## 📋 Prerequisites + +- Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed. + +## Installation + +```bash +$ pnpm install +``` + +## Building + +To build the monorepo packages, run: + +```bash +$ pnpm build +``` + +## Test + +```bash +# unit tests +$ pnpm run test + +# test coverage +$ pnpm run test:cov +``` + ## Usage ### Importing the Package diff --git a/packages/pricing/README.md b/packages/pricing/README.md index 673b67d..641f6f6 100644 --- a/packages/pricing/README.md +++ b/packages/pricing/README.md @@ -23,6 +23,34 @@ Available scripts that can be run using `pnpm`: | `test` | Run tests using vitest | | `test:cov` | Run tests with coverage report | +## 📋 Prerequisites + +- Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed. + +## Installation + +```bash +$ pnpm install +``` + +## Building + +To build the monorepo packages, run: + +```bash +$ pnpm build +``` + +## Test + +```bash +# unit tests +$ pnpm run test + +# test coverage +$ pnpm run test:cov +``` + ## Usage ### Importing the Package diff --git a/packages/processors/README.md b/packages/processors/README.md index 94b07b4..a4b4749 100644 --- a/packages/processors/README.md +++ b/packages/processors/README.md @@ -1,6 +1,6 @@ -# grants-stack-indexer: processors package +# Grants stack indexer v2 `processors` package -Description of your package goes here. +The `processors` package provides a set of utilities for processing and transforming data within the grants stack indexer project. It includes processors for handling Allo, Strategy, and Registry events. ## Setup @@ -22,14 +22,55 @@ Available scripts that can be run using `pnpm`: | `test` | Run tests using vitest | | `test:cov` | Run tests with coverage report | +## 📋 Prerequisites + +- Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed. + +## Installation + +```bash +$ pnpm install +``` + +## Building + +To build the monorepo packages, run: + +```bash +$ pnpm build +``` + +## Test + +```bash +# unit tests +$ pnpm run test + +# test coverage +$ pnpm run test:cov +``` + ## Usage -Describe how to use your package here. +```typescript +import { AlloProcessor } from "@grants-stack-indexer/processors"; + +const alloProcessor = new AlloProcessor(chainId, dependencies); +const changeset = await this.alloProcessor.process(event); +``` ## API -Describe your package's API here. +### Processors + +This package provides the following repositories: + +1. **AlloProcessor**: Handles the processing of Allo V2 events from the Allo contract by delegating them to the appropriate handler + +2. **RegistryProcessor**: Handles the processing of Allo V2 events from the Registry contract by delegating them to the appropriate handler + +3. **StrategyProcessor**: Handles the processing of Allo V2 events from the Strategy contract by delegating them to the appropriate handler ## References -Add any relevant references here. +- [Allo Protocol](https://github.com/allo-protocol/allo-v2) diff --git a/packages/processors/src/allo/allo.processor.ts b/packages/processors/src/allo/allo.processor.ts index c93afc4..b78b3dc 100644 --- a/packages/processors/src/allo/allo.processor.ts +++ b/packages/processors/src/allo/allo.processor.ts @@ -5,6 +5,9 @@ import type { IProcessor, ProcessorDependencies } from "../internal.js"; import { UnsupportedEventException } from "../internal.js"; import { PoolCreatedHandler } from "./handlers/index.js"; +/** + * AlloProcessor handles the processing of Allo V2 events by delegating them to the appropriate handler + */ export class AlloProcessor implements IProcessor<"Allo", AlloEvent> { constructor( private readonly chainId: ChainId, diff --git a/packages/repository/README.md b/packages/repository/README.md index 663def6..0682d29 100644 --- a/packages/repository/README.md +++ b/packages/repository/README.md @@ -22,6 +22,34 @@ Available scripts that can be run using `pnpm`: | `test` | Run tests using Vitest | | `test:cov` | Run tests with coverage report | +## 📋 Prerequisites + +- Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed. + +## Installation + +```bash +$ pnpm install +``` + +## Building + +To build the monorepo packages, run: + +```bash +$ pnpm build +``` + +## Test + +```bash +# unit tests +$ pnpm run test + +# test coverage +$ pnpm run test:cov +``` + ## Usage This package provides repository interfaces and implementations for projects and rounds. It uses Kysely as the query builder library. @@ -53,6 +81,8 @@ This package provides the following repositories: 2. **IRoundRepository**: Manages round-related database operations, including round roles and pending roles. +3. **IApplicationRepository**: Manages application-related database operations. + ## References - [Kysely](https://kysely.dev/) diff --git a/packages/shared/README.md b/packages/shared/README.md index f7ffa2e..d2adb1b 100644 --- a/packages/shared/README.md +++ b/packages/shared/README.md @@ -1,66 +1,41 @@ -# ts-turborepo-boilerplate: sample-lib package +# Grants stack indexer `shared` package -> Note: use this lib as reference but preferred way is to re-write package -> from zero instead of refactoring this one. -> When you don't need this anymore, you can delete it +The `@grants-stack-indexer/shared` package provides shared utilities, types, constants and logger. This package is designed to be used across the packages of this monorepo to ensure consistency and reusability. -Sample library that exposes a Blockchain provider to query -account balances on Ethereum mainnet or EVM-compatible blockchains +## 📋 Prerequisites -## Setup +- Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed. -1. Change package name to your own in [`package.json`](./package.json) -2. Install dependencies running `pnpm install` +## Installation -## Available Scripts - -Available scripts that can be run using `pnpm`: - -| Script | Description | -| ------------- | ------------------------------------------------------- | -| `build` | Build library using tsc | -| `check-types` | Check types issues using tsc | -| `clean` | Remove `dist` folder | -| `lint` | Run ESLint to check for coding standards | -| `lint:fix` | Run linter and automatically fix code formatting issues | -| `format` | Check code formatting and style using Prettier | -| `format:fix` | Run formatter and automatically fix issues | -| `test` | Run tests using vitest | -| `test:cov` | Run tests with coverage report | - -## Usage +```bash +$ pnpm install +``` -### Importing the Package +## Building -You can import the package in your TypeScript or JavaScript files as follows: +To build the monorepo packages, run: -```typescript -import { BlockchainProvider } from "@ts-turborepo-boilerplate/sample-lib"; +```bash +$ pnpm build ``` -### Example - -```typescript -// EVM-provider -const rpcUrl = ""; //non-empty valid url -const address = "0x..."; - -const provider = new BlockchainProvider(rpcUrl); +## Test -const balance = await provider.getBalance(address); +```bash +# unit tests +$ pnpm run test -console.log(`Balance of ${address} is ${balance}`); +# test coverage +$ pnpm run test:cov ``` -## API - -### [IBlockchainProvider](./src/interfaces/blockchainProvider.interface.ts) - -Available methods +## Usage -- `getBalance(address: Address)` +### Importing the Package -## References +You can import the package in your TypeScript files as follows: -- [Viem](https://viem.sh/) -- [Offchain docs: Internal module pattern](https://www.notion.so/defi-wonderland/Best-Practices-c08b71f28e59490f8dadef64cf61c9ac?pvs=4#89f99d33053a426285bacc6275d994c0) +```typescript +import { ILogger, ProcessorEvent, stringify } from "@grants-stack-indexer/shared"; +``` From 5d5862c695462572fa76983242823d9f0aa397e3 Mon Sep 17 00:00:00 2001 From: 0xkenj1 Date: Thu, 7 Nov 2024 22:46:39 -0300 Subject: [PATCH 2/4] docs: update packages docs --- README.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9e90a49..61fafc4 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,33 @@ Grants Stack Indexer v2 is a tool designed to index blockchain events generated ## 📖 Overview -This repository is a monorepo that contains 1 package and 2 applications: +This repository is a monorepo that contains 8 packages and 3 applications: -- @ts-turborepo-boilerplate/sample-lib: A sample library for querying account balances. -- @ts-turborepo-boilerplate/sample-app: A demo application demonstrating the use of sample-lib. -- @grants-stack-indexer/indexer: An [`envio`](https://docs.envio.dev/) indexer, that collects all the relevant events from Allo contracts. +### Applications + +- **@grants-stack-indexer/indexer**: An Envio indexer service that collects relevant events from Allo contracts. It is designed to run on the Envio hosted platform and includes a Dockerfile for deployment. + +- **@grants-stack-indexer/processing**: This service runs the core processing pipeline, coordinating components from various packages to process blockchain events. It manages an Orchestrator per chain. + +- **@grants-stack-indexer/scripts**: Contains scripts for managing the database schema and migrations. It includes scripts for running migrations and resetting the database schema. + +### Packages/libs + +- **@grants-stack-indexer/chain-providers**: Provides wrappers of the Viem library to interact with EVM-based blockchains. It includes utilities for reading contracts and making batch requests. + +- **@grants-stack-indexer/data-flow**: Manages the flow of data between different components of the indexer. It includes core components for the processing pipeline. + +- **@grants-stack-indexer/indexer-client**: A client library for interacting with blockchain event indexing services. It provides methods to fetch events by block number and log index. + +- **@grants-stack-indexer/metadata**: Handles metadata related to the indexed events. It provides a metadata provider to retrieve metadata from IPFS. + +- **@grants-stack-indexer/pricing**: Manages pricing data and calculations. It includes providers to get the price of a token at a specific timestamp using chainId and token address. + +- **@grants-stack-indexer/processors**: Contains various data processors used in the indexing pipeline. It includes processors for handling Allo, Strategy, and Registry events. + +- **@grants-stack-indexer/repository**: Manages the storage and retrieval of indexed data. It implements the Repository pattern to abstract database operations. + +- **@grants-stack-indexer/shared**: Provides shared utilities, types, constants, and logger. It is designed to be used across the packages of the monorepo to ensure consistency and reusability. ## 🚀 Local Deployment (Development) From 1a9fd23f884234245ab4b7eaef1c2ae2d4d75695 Mon Sep 17 00:00:00 2001 From: 0xkenj1 Date: Thu, 7 Nov 2024 22:55:24 -0300 Subject: [PATCH 3/4] fix: indexer client docs --- packages/indexer-client/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/indexer-client/README.md b/packages/indexer-client/README.md index 1ffd989..c0ae391 100644 --- a/packages/indexer-client/README.md +++ b/packages/indexer-client/README.md @@ -1,6 +1,6 @@ # @grants-stack-indexer/indexer-client -Is library for interacting with blockchain event indexing services. +This is a library for interacting with blockchain event indexing services. ## Available Scripts From 878d78c1781360125cf35c02cf5dd40bd44b5072 Mon Sep 17 00:00:00 2001 From: 0xkenj1 Date: Fri, 8 Nov 2024 12:38:58 -0300 Subject: [PATCH 4/4] fix: pr comments --- packages/data-flow/README.md | 32 +++++++++++++++++-- packages/processors/README.md | 2 +- .../processors/src/allo/allo.processor.ts | 2 +- 3 files changed, 32 insertions(+), 4 deletions(-) diff --git a/packages/data-flow/README.md b/packages/data-flow/README.md index 8fc4ce4..0ab5fe7 100644 --- a/packages/data-flow/README.md +++ b/packages/data-flow/README.md @@ -18,6 +18,34 @@ Available scripts that can be run using `pnpm`: | `test` | Run tests using vitest | | `test:cov` | Run tests with coverage report | +## 📋 Prerequisites + +- Ensure you have `node >= 20.0.0` and `pnpm >= 9.5.0` installed. + +## Installation + +```bash +$ pnpm install +``` + +## Building + +To build the monorepo packages, run: + +```bash +$ pnpm build +``` + +## Test + +```bash +# unit tests +$ pnpm run test + +# test coverage +$ pnpm run test:cov +``` + ## Usage ### Importing the Package @@ -64,8 +92,8 @@ The `EventsFetcher` class is responsible for fetching events from the blockchain ### [StrategyRegistry](./src/strategyRegistry.ts) -The `StrategyRegistry` stores strategy IDs in memory to populate strategy events with them. +The `StrategyRegistry` stores strategy IDs to populate strategy events with them given the Strategy address. ### [DataLoader](./src/data-loader/dataLoader.ts) -The `DataLoader` is responsible for applying changesets to the database.. +The `DataLoader` is responsible for applying changesets to the database. diff --git a/packages/processors/README.md b/packages/processors/README.md index a4b4749..e07f45c 100644 --- a/packages/processors/README.md +++ b/packages/processors/README.md @@ -63,7 +63,7 @@ const changeset = await this.alloProcessor.process(event); ### Processors -This package provides the following repositories: +This package provides the following events' processors: 1. **AlloProcessor**: Handles the processing of Allo V2 events from the Allo contract by delegating them to the appropriate handler diff --git a/packages/processors/src/allo/allo.processor.ts b/packages/processors/src/allo/allo.processor.ts index b78b3dc..87430a0 100644 --- a/packages/processors/src/allo/allo.processor.ts +++ b/packages/processors/src/allo/allo.processor.ts @@ -6,7 +6,7 @@ import { UnsupportedEventException } from "../internal.js"; import { PoolCreatedHandler } from "./handlers/index.js"; /** - * AlloProcessor handles the processing of Allo V2 events by delegating them to the appropriate handler + * AlloProcessor handles the processing of Allo V2 events from the Allo contract by delegating them to the appropriate handler */ export class AlloProcessor implements IProcessor<"Allo", AlloEvent> { constructor(