How it works and install

How it works and install for chainstar. Raw blockchain data to clean dimensional tables in your own warehouse, from one command.

chainstar pulls blocks, transactions and token transfers from an RPC endpoint (yours, or a free public one), saves them as Parquet, loads them into DuckDB or Postgres, and builds a small star schema with dbt: facts for transfers and fees, dimensions for wallets, tokens, contracts and dates. All chains share the same tables, so one warehouse can hold Ethereum, Base, Bitcoin and Solana side by side.

extract  →  decode  →  load  →  model
 cryo        cryo      DuckDB    dbt        (Ethereum, Base)
 JSON-RPC    -         DuckDB    dbt        (Bitcoin, Solana)

extract: on Ethereum and Base, cryo fetches blocks, transactions and ERC-20 Transfer events for your block range into Parquet files, decoding each Transfer log into token, sender, recipient and value. cryo does not support Bitcoin or Solana, so for those chainstar reads blocks over plain JSON-RPC itself and writes Parquet files in the same layout (see Chains).
decode (Ethereum and Base): for every token contract seen, cryo calls name(), symbol() and decimals().
load: the Parquet files are copied into raw tables (schema chainstar_raw).
model: a bundled dbt project builds the star schema (schema chainstar) and tests it.

This is an early release (0.1, unreleased). It supports Ethereum, Base, Bitcoin and Solana, and DuckDB and Postgres as targets.

Install

There are three ways; pick one.

Docker image (no Python or Rust needed, cryo included). Published to the GitHub Container Registry by this repository's Docker image workflow, for amd64 and arm64 (Apple silicon and other 64-bit ARM machines):

docker run --rm -v "$PWD:/work" ghcr.io/bit-primitive/chainstar --help

ghcr.io/bit-primitive/chainstar:latest follows main; version tags such as :0.1.0 follow releases. To build the image yourself: docker build -t chainstar . in a checkout (the cryo compile takes about 5 minutes).

How the container sees your files: the folder you mount at /work is chainstar's working folder, so warehouse.duckdb, data/ and exports appear in it, and paths you pass (--output mine.xlsx, --target duckdb:my.duckdb) are relative to it. Pass your own RPC URL with -e CHAINSTAR_RPC_URL (it is read from your environment, not written into the command). Add -it for quickstart's questions; without a terminal it uses the defaults, as with --yes. The image runs as an unprivileged user (uid 1000); on Linux, --user "$(id -u):$(id -g)" makes the files yours. DuckDB's postgres and excel extensions are included, so exports and Postgres targets work without downloads.

uv or pipx (Python 3.11 or newer):

uv tool install git+https://github.com/Bit-Primitive/chainstar
# or: pipx install git+https://github.com/Bit-Primitive/chainstar

chainstar is not on PyPI yet; once it is, uv tool install chainstar or pipx install chainstar.

cryo, for Ethereum and Base outside Docker. It is written in Rust; get Rust from https://rustup.rs, then:

cargo install cryo_cli

This installs cryo 0.3.2 from crates.io, the version chainstar is tested with. Bitcoin and Solana need nothing else.