Full sync

What You'll Learn

In this guide, you'll learn how to:

Set up and configure the Bitcoin Indexer

Run the indexer from scratch

Monitor indexing progress effectively

Prerequisites

To start the indexer, you'll need:

Bitcoin Core fully synced with txindex=1

PostgreSQL running with databases created

Sufficient storage space

Archive bootstrap recommended

If you haven't already, consider bootstrapping from archives to save days of indexing time.

Start indexing services

The Bitcoin Indexer runs separate services for each metaprotocol. Navigate to your indexer directory:

Terminal

$ cd ~/bitcoin-indexer/bitcoin-indexer

Index Ordinals (includes BRC-20)

Terminal

$ ./target/release/bitcoin-indexer ordinals service start --config-path=bitcoin-indexer-config.toml
[32m✓[0m Loading configuration from bitcoin-indexer-config.toml
[32m✓[0m Connected to Bitcoin node at 127.0.0.1:8332
[32m✓[0m Connected to PostgreSQL databases
[32m✓[0m Starting Ordinals indexer from block 819542
[1mProcessing block 819543...[0m

Index Runes

In a separate terminal:

Terminal

$ ./target/release/bitcoin-indexer runes service start --config-path=bitcoin-indexer-config.toml
[32m✓[0m Loading configuration from bitcoin-indexer-config.toml
[32m✓[0m Connected to Bitcoin node at 127.0.0.1:8332
[32m✓[0m Starting Runes indexer from block 840000
[1mProcessing block 840001...[0m

Resource usage

Each service uses the CPU cores and memory specified in your configuration. Ensure your system has enough resources to run multiple services simultaneously.

Monitor indexing progress

Check service logs

The indexer outputs detailed progress information:

Terminal

$ tail -f ~/bitcoin-indexer/bitcoin-indexer/ordinals.log
2024-12-15 10:30:45 [INFO] Processing block 819600
2024-12-15 10:30:46 [INFO] Found 23 new inscriptions
2024-12-15 10:30:46 [INFO] Updated 45 transfers
2024-12-15 10:30:47 [INFO] Block 819600 processed in 1.2s

Query indexer status via API

Once the API server starts (usually after a few blocks):

Terminal

$ curl http://localhost:3000/ordinals/v1/status
{
  "block_height": 819600,
  "inscriptions_indexed": 52342567,
  "latest_inscription_number": 52342567,
  "sync_percentage": 99.93,
  "blocks_behind": 523
}

Monitor system resources

Use htop to monitor resource usage:

Terminal

$ htop
# Look for:
# - bitcoin-indexer processes using 60-80% CPU
# - Memory usage within limits
# - Disk I/O activity

Service management

Stop services gracefully

Terminal

$ ps aux | grep bitcoin-indexer
user  12345  75.2  8.3  bitcoin-indexer ordinals service
user  12346  68.1  6.2  bitcoin-indexer runes service

$ # Stop with SIGTERM for clean shutdown
$ kill -TERM 12345 12346

Restart after interruption

The indexer automatically resumes from the last processed block:

Terminal

$ ./target/release/bitcoin-indexer ordinals service start --config-path=bitcoin-indexer-config.toml
[32m✓[0m Detected previous state at block 819600
[32m✓[0m Resuming indexing from block 819601

Systemd service setup

For production deployments, use systemd to manage services:

Create Ordinals service

title="/etc/systemd/system/bitcoin-indexer-ordinals.service"

[Unit]
Description=Bitcoin Indexer - Ordinals Service
After=network.target postgresql.service bitcoind.service

[Service]
Type=simple
User=bitcoin-indexer
WorkingDirectory=/home/bitcoin-indexer/bitcoin-indexer
ExecStart=/home/bitcoin-indexer/bitcoin-indexer/target/release/bitcoin-indexer ordinals service start --config-path=bitcoin-indexer-config.toml
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

Create Runes service

title="/etc/systemd/system/bitcoin-indexer-runes.service"

[Unit]
Description=Bitcoin Indexer - Runes Service
After=network.target postgresql.service bitcoind.service

[Service]
Type=simple
User=bitcoin-indexer
WorkingDirectory=/home/bitcoin-indexer/bitcoin-indexer
ExecStart=/home/bitcoin-indexer/bitcoin-indexer/target/release/bitcoin-indexer runes service start --config-path=bitcoin-indexer-config.toml
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

Enable and start services

Terminal

$ sudo systemctl daemon-reload
$ sudo systemctl enable bitcoin-indexer-ordinals bitcoin-indexer-runes
$ sudo systemctl start bitcoin-indexer-ordinals bitcoin-indexer-runes
$ sudo systemctl status bitcoin-indexer-ordinals
[32m●[0m bitcoin-indexer-ordinals.service - Bitcoin Indexer - Ordinals Service
     Loaded: loaded (/etc/systemd/system/bitcoin-indexer-ordinals.service; enabled)
     Active: [32mactive (running)[0m since Mon 2024-12-15 10:30:00 UTC

Performance optimization

During initial sync

Optimize for throughput during catch-up:

title="bitcoin-indexer-config.toml"

[resources]
# Use more cores during initial sync
cpu_core_available = 12
bitcoind_rpc_threads = 10

After reaching chain tip

Reduce resource usage for steady-state operation:

[resources]
# Reduce for normal operation
cpu_core_available = 4
bitcoind_rpc_threads = 4

Verify successful indexing

Check API endpoints

Test that APIs are returning data:

Terminal

$ curl http://localhost:3000/ordinals/v1/inscriptions/0
$ curl http://localhost:3000/runes/v1/runes

Monitor metrics

If Prometheus metrics are enabled:

Terminal

$ curl http://localhost:9153/metrics | grep bitcoin_indexer
bitcoin_indexer_blocks_processed_total{protocol="ordinals"} 52600
bitcoin_indexer_inscriptions_total 52342567
bitcoin_indexer_api_requests_total{endpoint="/ordinals/v1/inscriptions"} 1523

Troubleshooting

Service won't start

ERROR: Failed to connect to Bitcoin node

Solutions:

1Verify Bitcoin node is running: bitcoin-cli getblockcount
2Check RPC credentials match configuration
3Ensure ZMQ ports are not blocked

Slow indexing speed

If processing less than 1 block/second:

1Check Bitcoin node performance
2Verify PostgreSQL isn't bottlenecked
3Monitor disk I/O with iotop
4Consider archive bootstrap if starting from scratch

Database connection pool exhausted

ERROR: connection pool timeout

Solutions:

1Increase max_connections in PostgreSQL
2Reduce bitcoind_rpc_threads in config
3Check for long-running queries

Next steps

Use the Ordinals API

Query inscriptions and digital artifacts

Use the Runes API

Access Runes token data

Use the BRC-20 API

Query BRC-20 token balances