Barreleye

Barreleye is an open-source multi-chain blockchain indexer and explorer.

Features:

• Easy to use — start on a single machine, scale up as needed
• Scalable — optimized for handling lots of data
• Multi-chain — designed to support multiple blockchain architectures

Important

This is a work-in-progress and not yet ready for use or production.

Requirements

1. Rust v1.83+ — if you're compiling from source
2. Blockchain nodes — for indexing (eg: Bitcoin, Ethereum, etc)

Get Started

Clone, build & install:

git clone https://github.com/barreleye/barreleye
cd barreleye
cargo build
cargo install

Run locally:

cargo run

This will do the following:

• Start the server, which will handle API requests
• Start the indexer, which will:
  • Store extracted blockchain data in Parquet files
  • Store relational data in SQLite
  • Store warehouse data in DuckDB

For production you'll probably want to store extracted blockchain data in the cloud (eg: Amazon S3, Cloudflare R2, etc), as opposed to your localhost:

cargo run -- \
  --storage http://s3.us-east-1.amazonaws.com/bucket_name/

And structured data in RDBMS like PostgreSQL or MySQL, instead of SQLite:

cargo run -- \
  --storage http://s3.us-east-1.amazonaws.com/bucket_name/ \
  --database postgres://postgres-host:5432/database_name

As well as analytics data in ClickHouse, instead of DuckDB:

cargo run -- \
  --storage http://s3.us-east-1.amazonaws.com/bucket_name/ \
  --database postgres://postgres-host:5432/database_name \
  --warehouse http://example.clickhouse.cloud:8123/database_name

Modes

Barreleye operates two parallel components: the indexer and the server. The indexer retrieves blockchain data, while the server manages API requests, handling data and address information.

Barreleye automatically runs both the indexer and server in parallel:

cargo run

Run only the indexer:

cargo run -- --mode indexer

Run only the server:

cargo run -- --mode http

Tip

The indexer operates in failover mode, with a single primary instance running while secondary instances stand by, ready to take over if the primary fails.

Data Management

Barreleye does not come with any pre-defined data. Instead, it gives you the ability to add and manage data yourself. The API calls below give an overview of how to manage data.

Add Blockchains

Add a Bitcoin RPC node:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "net_bitcoin",
    "name": "Bitcoin",
    "architecture": "bitcoin",
    "blockTime": 600000,
    "rpcEndpoint": "http://username:password@127.0.0.1:8332"
  }' \
  http://localhost:4000/v1/networks

Add an EVM-based RPC node (archive node is required):

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "net_ethereum",
    "name": "Ethereum",
    "architecture": "evm",
    "chainId": 1,
    "blockTime": 12000,
    "rpcEndpoint": "http://127.0.0.1:8545"
  }' \
  http://localhost:4000/v1/networks

Add Tokens

Add native Bitcoin currency:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "network": "net_bitcoin",
    "name": "bitcoin",
    "symbol": "BTC",
    "decimals": 8
  }' \
  http://localhost:4000/v1/tokens

Add native Ethereum currency:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "network": "net_ethereum",
    "name": "Ether",
    "symbol": "ETH",
    "decimals": 18
  }' \
  http://localhost:4000/v1/tokens

Add an ERC-20 token:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "network": "net_ethereum",
    "name": "USD Coin",
    "symbol": "USDC",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "decimals": 6
  }' \
  http://localhost:4000/v1/tokens

Add Tags

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "tag_exchange",
    "name": "Exchange",
    "riskLevel": "low"
  }' \
  http://localhost:4000/v1/tags

Add Entities

An entity can be an item that contains one or several blockchain addresses:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "ent_coinbase",
    "name": "Coinbase",
    "description": "",
    "tags": ["tag_exchange"]
  }' \
  http://localhost:4000/v1/entities

Add addresses:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "entity": "ent_coinbase",
    "network": "net_ethereum",
    "addresses": [
      {
        "address": "0x71660c4005BA85c37ccec55d0C4493E66Fe775d3",
        "description": "Address #1"
      }, {
        "address": "0x503828976d22510aad0201ac7ec88293211d23da",
        "description": "Address #2"
      }
    ]
  }' \
  http://localhost:4000/v1/addresses

Address Info

Query information about a particular blockchain address:

curl -X GET \
  -H 'Content-Type: application/json' \
  http://localhost:4000/v1/info?q=<BLOCKCHAIN_ADDRESS>

Notes

• Be aware of your RPC node limits. Indexer makes a significant amount of RPC calls to index historical and new blocks.
• For indexing, you might have to set ClickHouse's max_server_memory_usage_to_ram_ratio to 2 (read more)

License

Barreleye is free, open source and permissively licensed. Except where noted (below and/or in individual files), all code in this repository is dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

Your contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.