chaindexing / chaindexing-rs

Index any EVM chain and query in SQL

Chaindexing

Index any EVM chain and query in SQL

Getting Started | Examples | Design Goals & Features | RoadMap | Contributing

Getting Started

📊 Here is what indexing and tracking owers of your favorite NFTs looks like:

use chaindexing::states::{ContractState, Filters, Updates};
use chaindexing::{EventContext, EventHandler};

use crate::states::Nft;

pub struct TransferHandler;

#[chaindexing::augmenting_std::async_trait]
impl EventHandler for TransferHandler {
    fn abi(&self) -> &'static str {
        "event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)"
    }
    async fn handle_event<'a, 'b>(&self, context: EventContext<'a, 'b>) {
        let event_params = context.get_event_params();

        let _from = event_params.get_address_string("from");
        let to = event_params.get_address_string("to");
        let token_id = event_params.get_u32("tokenId");

        if let Some(existing_nft) =
            Nft::read_one(&Filters::new("token_id", token_id), &context).await
        {
          let updates = Updates::new("owner_address", &to);
          existing_nft.update(&updates, &context).await;
        } else {
            let new_nft = Nft {
                token_id,
                owner_address: to,
            };

            new_nft.create(&context).await;
        }
    }
}

A quick and effective way to get started is by exploring the comprehensive examples provided here: https://github.com/chaindexing/chaindexing-examples/tree/main/rust.

Design Goals & Features

• 💸 Free forever
  
• ⚡ Real-time use-cases
  
• 🌐 Multi-chain
  
• 🧂 Granular, 🧩 Modular & 📈 Scalable
  
• 🌍 Environment-agnostic to allow inspecting 🔍 & replicating indexes anywhere!
  
• 🔓 ORM-agnostic, use any ORM to access indexed data
  
• 📤 Easy export to any data lake: S3, Snowflake, etc.
  
• 🚫 No complex YAML/JSON/CLI config
  
• 💪 Index contracts discovered at runtime
  
• ✨ Handles re-org with no UX impact
  
• 🔥 Side effect handling for notifications & bridging use cases
  
• 💸 Optimize RPC cost by indexing when certain activities happen in your DApp
  
• 💎 Language-agnostic, so no macros!
  

RoadMap

• ⬜ Expose is_at_block_tail flag to improve op heuristics for applications
  
• ⬜ Support SQLite Database (Currently supports only Postgres)
  
• ⬜ Support indexing raw transactions & call traces.
  
• ⬜ Improved error handling/messages/reporting (Please feel free to open an issue when an opaque runtime error is encountered)
  
• ⬜ Support TLS connections
  
• ⬜ Minimal UI for inspecting events and indexed states
  

Contributing

All contributions are welcome. Before working on a PR, please consider opening an issue detailing the feature/bug. Equally, when submitting a PR, please ensure that all checks pass to facilitate a smooth review process.

chaindexing-rs's Issues

Add SQL parser

This will help guide users when they have written an invalid SQL syntax. To stay language agnostic, it must be runtime-based. Eventually, after most libraries have been built, we can expose an extra macro, or even sqlx's parser, to be used at compile time.

Consider removing Diesel

Currently, this library uses tokio-postgres and diesel as the RDBMS clients. We need to pick one for obvious reasons.

ANALYSIS (WIP)

Exhaustive Error handling

Deserialization of timestamp fields fails

Action: Investigate tokio-postgres.

Analysis: Timestamp fields should be encoded as serde::Value::String("\"<value>\"") -- the inner extra quotes are essential for serde to reach an agreement with chrono when deserializing. However, it seems tokio-postgres somehow gets rid of those extra quotes when converting a Row to its equivalent serde::Value.

Ingest raw transactions block by block optionally

Validate config on start

GET All Blocks Concurrently

Currently, blocks are fetched for the logs in a blocking fashion. It will greatly improve the ingestion performance if we fetched them concurrently instead.

Prune stale events

The engine should be able to intelligently prune processed and stale events.

Optimize reset count logic

Support JSON fields

Allow opting out of populating block timestamps

Currently, we make blocking RPC calls to fetch blocks for ingested events. This could be a performance bottleneck for DApps that do not require block_timestamp values. It would be better to have an opt-out configuration to allow drastic latency reduction in such DApps.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

cargo

chaindexing-tests/Cargo.toml

• ethers 2.0
• futures-util 0.3
• dotenvy 0.15
• diesel 2
• rand 0.8.5
• tokio 1.37

chaindexing/Cargo.toml

• async-trait 0.1
• bb8 0.8
• derive_more 0.99
• chrono 0.4
• diesel 2
• diesel-async 0.4
• pin-project-lite 0.2.14
• ethers 2.0
• serde 1.0
• serde_json 1
• tokio-postgres 0.7
• tokio 1
• uuid 1
• futures-core 0.3
• futures-util 0.3

docker-compose

docker-compose.yml

• postgres 16

github-actions

.github/workflows/ci.yml

• actions/checkout v4
• actions/checkout v4
• actions/checkout v4
• Swatinem/rust-cache v2
• actions/checkout v4

---

• Check this box to trigger a request for Renovate to run again on this repository