RustBus is a high-performance blockchain explorer, indexer and microservices engine for the BSV blockchain (BSV), engineered to far surpass traditional indexers with exceptional scalability and efficiency. Written in Rust, RustBus harnesses modern technologies—GraphQL, REST, WebSocket APIs, PostgreSQL partitioning, and ZeroMQ—to provide real-time transaction and block indexing for both mainnet and testnet. Ideal for developers querying BSV transactions, miners tracking blocks, or enterprises leveraging BSV's massive blockchain, RustBus is your premier solution.
- Scalable Indexing: Manages BSV's large-scale blocks and transactions using PostgreSQL table partitioning by block height, optimized for mainnet.
- Modern APIs:
- GraphQL: Query transactions, blocks, and OP_RETURN data via a flexible
/graphqlendpoint with a GraphiQL playground. - REST: Retrieve transactions at
/tx/{txid}or filter by type at/txs?type=BCAT. - WebSocket: Subscribe to real-time transaction notifications at
/wsfor protocols like RUN, MAP or BCAT.
- GraphQL: Query transactions, blocks, and OP_RETURN data via a flexible
- Real-Time Notifications: Connects to BSV nodes via ZeroMQ for instant block updates.
- Prometheus Metrics: Tracks performance at
/metrics(port 8080) with metrics likerustbus_txs_indexed_total. - Mainnet & Testnet Support: Configurable with
NETWORK=mainnetorNETWORK=testnet. - Historical Syncing: Syncs blocks from any starting height (e.g.,
START_HEIGHT=800000) with reorg handling. - Dockerized Deployment: Lightweight (~100MB) Docker image for seamless CI/CD and production.
- Efficient Storage: Selective indexing with GIN trigram indexes on OP_RETURN for rapid searches.
- CI/CD Pipeline: Automated testing, linting, and Docker builds via GitHub Actions.
Launch RustBus in minutes with Docker, PostgreSQL, and a BSV node.
- Docker: Install from docker.com.
- PostgreSQL 15+: Install locally or use a managed service.
- BSV Node: Run a BSV node with RPC (port 8332) and ZeroMQ (port 28332) enabled.
- Rust 1.81+ (optional for local builds): Install via rustup.rs.
Clone the Repository:
git clone https://github.com/murphsicles/RustBus cd RustBusConfigure Environment:
- Copy the example environment file:
cp .env.example .env
- Edit
.envwith your settings:DATABASE_URL=postgres://user:pass@localhost:5432/rustbus DATABASE_URL=postgres://user:pass@localhost:5432/rustbus BSV_RPC_URL=http://127.0.0.1:8332 BSV_RPC_USER=rpcuser BSV_RPC_PASSWORD=rpcpass ZMQ_ADDR=tcp://127.0.0.1:28332 NETWORK=mainnet START_HEIGHT=800000 METRICS_PORT=9090 BIND_ADDR=0.0.0.0:8080
- Copy the example environment file:
Set Up PostgreSQL:
- Create the database:
sudo -u postgres createdb rustbus sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'pass';" - Apply the partitioned schema:
psql -h localhost -U postgres -d rustbus -f schema.sql
- Create the database:
Build and Run with Docker:
docker build -t rustbus:latest . docker run -d --name rustbus -p 8080:8080 --env-file .env rustbus:latestVerify:
- GraphQL Playground: Open
http://localhost:8080/graphql. - Health Check:
curl http://localhost:8080/health - Metrics:
curl http://localhost:8080/metrics - Check indexed blocks:
psql -d rustbus -c "SELECT COUNT(*) FROM blocks;"
- GraphQL Playground: Open
Configure RustBus via .env or Docker -e flags:
| Variable | Description | Example |
|---|---|---|
| DATABASE_URL | PostgreSQL connection string | postgres://user:pass@localhost:5432/rustbus |
| BSV_NODE | BSV node RPC address (host:port) | 127.0.0.1:8332 |
| ZMQ_ADDR | ZeroMQ address for block notifications | tcp://127.0.0.1:28332 |
| NETWORK | Blockchain network | mainnet or testnet |
| START_HEIGHT | Starting block height for historical sync | 800000 |
| METRICS_PORT | Port for Prometheus metrics | 8080 |
DATABASE_URL: PostgreSQL connection string (e.g.,postgres://user:pass@db:5432/rustbus)BSV_NODE: BSV node address (e.g.,bsv-node:8333)ZMQ_ADDR: ZMQ address (e.g.,tcp://bsv-node:28332)NETWORK:mainnetortestnetSTART_HEIGHT: Starting block height (default:0)BIND_ADDR: HTTP bind address (default:0.0.0.0:8080)METRICS_PORT: Prometheus metrics port (default:9090)PROTOCOLS: Transaction protocol regexes (e.g.,RUN:run://; MAP:1PuQa7)
Fetch a transaction by TXID:
query {
transaction(txid: "abc123...") {
txidblock_heighttx_typeop_return
}
}Run via http://localhost:8080/graphql or curl:
curl -X POST -H "Content-Type: application/json" \
-d '{"query":"query { transaction(txid: \"abc123...\") { txid block_height tx_type op_return } }"}' \
http://localhost:8080/graphqlGet transactions by type:
curl "http://localhost:8080/txs?type=RUN&limit=10"Get a single transaction:
curl http://localhost:8080/tx/abc123...Subscribe to RUN transactions:
wscat -c ws://127.0.0.1:8080/wsSend:
{"client_id": "test1", "filter_type": "RUN"}Monitor indexing performance:
curl http://localhost:8080/metrics Example
output:rustbus_txs_indexed_total{network="mainnet"} 123456
rustbus_block_process_seconds{network="mainnet"} 0.05
rustbus_active_subscriptions 10RustBus uses partitioned PostgreSQL tables for scalability. Key tables (schema.sql): -transactions:
CREATETABLEtransactions (
txid TEXTNOT NULL,
block_height BIGINTNOT NULL,
tx_type TEXTNOT NULL,
op_return TEXT,
tx_hex TEXTNOT NULL,
PRIMARY KEY (txid, block_height)
) PARTITION BY RANGE (block_height);-Partitions: transactions_p0_100000, transactions_p100000_200000, etc.
-Indexes: GIN trigram on op_return, B-tree on tx_type, block_height. -blocks:
CREATETABLEblocks (
height BIGINTPRIMARY KEY,
hash TEXTNOT NULL,
timestampBIGINTNOT NULL
) PARTITION BY RANGE (height);Apply:
psql -d rustbus -f schema.sql Build and push to Docker Hub:
docker build -t yourusername/rustbus:latest . docker push yourusername/rustbus:latest Deploy with Fly.io (example fly.toml):
app = "rustbus"primary_region = "iad"
[http_service]
internal_port = 8080force_https = trueauto_stop_machines = trueauto_start_machines = truemin_machines_running = 1Run:
flyctl deploy Build and run locally without Docker:
cargo build --release
cargo runRun tests:
cargo test --verboseLint:
cargo clippy --all-targets --all-features -- -D warnings- Lite mode for minimal transaction data (tx hash, block height).
- Advanced filtering for RUN, MAP sub-contexts, with discovery API.
- Explicit mempool transaction support in GraphQL.
We welcome contributions! Fork the repo, create a branch, and submit a PR. See CONTRIBUTING.md for guidelines.
MIT License. See LICENSE.
RustBus redefines BSV exploration with:
- Performance: Rust's speed and safety for mainnet-scale indexing.
- Flexibility: GraphQL, REST, and WebSocket APIs for all use cases.
- Scalability: Partitioned storage and efficient indexing.
- Reliability: CI/CD with GitHub Actions and Docker.
Join the BSV revolution with RustBus—the explorer that scales as big as your ambitions!