maestro-symphony 0.1.1

Orchestrating Bitcoin blocks into readable harmony

maestro-symphony-0.1.1 is not a library.

🎵 ₿ from hash to harmony: an orchestrated Bitcoin indexing suite ₿ 🎵

Maestro Symphony

Overview

Maestro Symphony is a fast, mempool-aware, and extensible Bitcoin indexer and API server. It provides a framework for indexing UTXOs, metaprotocols, and any other onchain activity.

Core Features

mainnet
testnet4
regtest

Runes
Transaction count by address
UTXOs by address

Endpoints: OpenAPI

Mempool Awareness: Query any endpoint with ?mempool=true to include pending transactions.

Rollback Handling: Always maintains an index of the longest chain.

Prerequisites

Bitcoin Core (22+) with RPC and P2P access
Rust (stable)

Optional Tools

Docker
mise

Deployment Requirements

Disk: 1 GB
CPU: 2 cores
RAM: 4 GB
Sync time: ~6 hours

Disk: 24 GB
CPU: 4 cores
RAM: 16 GB
Sync time: ~4 days

NOTE: Deployment requirements are subject to change with new indexers and API endpoints.

Configuration

Below is a table describing the main configuration options for maestro-symphony. See the example configuration for context.

Section	Key/Field	Description	Example Value
root	`db_path`	Path to the database directory	`"tmp/symphony"`
`[sync.node]`	`p2p_address`	Host/IP and port for P2P connection to Bitcoin node	`"localhost:8333"`
	`rpc_address`	URL of your Bitcoin node's RPC endpoint	`"http://localhost:8332"`
	`rpc_user`	RPC username for your Bitcoin node	`"bitcoin"`
	`rpc_pass`	RPC password for your Bitcoin node	`"password"`
`[sync]`	`network`	Bitcoin network to connect to (`mainnet`, `testnet4`)	`"mainnet"`
	`safe_mode`	Enable safe mode for sync (recommended)	`true`
	`max_rollback`	Maximum blocks to roll back on reorg	`32`
	`mempool`	Enable mempool awareness	`true`
`[sync.indexers]`	`transaction_indexers`	List of enabled indexers and their options	See example below
`[server]`	`address`	Address and port for API server to listen on	`"0.0.0.0:8080"`

See examples to quickly get started.

Running Locally

Optionally, use mise to easily set up your environment:

mise install

Build

make build

Sync & Serve

make run [CONFIG=examples/testnet.toml]

Sync Only

make sync [CONFIG=examples/testnet.toml]

Serve Only

make serve [CONFIG=examples/testnet.toml]

Generate OpenAPI

make openapi

Running with Docker

Start

make compose-up

Stop

make compose-down

Endpoint Examples

Rune UTXOs by Address

curl -X GET "http://localhost:8080/addresses/tb1pn9dzakm6egrv90c9gsgs63axvmn6ydwemrpuwljnmz9qdk38ueqsqae936/runes/utxos" | jq .

{
    "data": [
        {
            "tx_hash": "63937d48e35d15a7c5530469210c202104cc94a945cc848554f336b3f4f24121",
            "output_index": 1,
            "height": 30562,
            "satoshis": "10000",
            "runes": [
                {
                    "id": "30562:50",
                    "amount": "100000000"
                }
            ]
        }
    ],
    "indexer_info": {
        "chain_tip": {
            "block_hash": "000000002ec229e75c52e8e9adf95149fdde167b59c3271abb6bf541ef85249b",
            "block_height": 87777
        },
        "mempool_timestamp": null,
        "estimated_blocks": []
    }
}

Rune Info (Batch)

curl -X POST "http://localhost:8080/runes/info" \
  -H "Content-Type: application/json" \
  -d '["30562:50", "ABCDEF"]' | jq .

{
    "data": {
        "30562:50": {
            "id": "30562:50",
            "name": "BESTINSLOTXYZ",
            "spaced_name": "BESTINSLOT•XYZ",
            "symbol": "ʃ",
            "divisibility": 8,
            "etching_tx": "63937d48e35d15a7c5530469210c202104cc94a945cc848554f336b3f4f24121",
            "etching_height": 30562,
            "terms": {
                "amount": "100000000",
                "cap": "3402823669209384634633746074316",
                "start_height": null,
                "end_height": null
            },
            "premine": "100000000"
        },
        "ABCDEF": null
    },
    "indexer_info": {
        "chain_tip": {
            "block_hash": "00000000000000108a4cd9755381003a01bea7998ca2d770fe09b576753ac7ef",
            "block_height": 31633
        },
        "mempool_timestamp": null,
        "estimated_blocks": []
    }
}

Mempool-Aware Rune UTXOs by Address

curl -X GET "http://localhost:8080/addresses/tb1pn9dzakm6egrv90c9gsgs63axvmn6ydwemrpuwljnmz9qdk38ueqsqae936/runes/utxos?mempool=true" | jq .

{
    "data": [
        {
            "tx_hash": "63937d48e35d15a7c5530469210c202104cc94a945cc848554f336b3f4f24121",
            "output_index": 1,
            "height": 30562,
            "satoshis": "10000",
            "runes": [
                {
                    "id": "30562:50",
                    "amount": "100000000"
                }
            ]
        }
    ],
    "indexer_info": {
        "chain_tip": {
            "block_hash": "000000002ec229e75c52e8e9adf95149fdde167b59c3271abb6bf541ef85249b",
            "block_height": 87777
        },
        "mempool_timestamp": "2025-06-23 22:04:31",
        "estimated_blocks": [
            {
                "block_height": 87778
            }
        ]
    }
}

Rune Balance Changes in a Transaction

curl -X GET "http://localhost:8080/addresses/<ADDRESS>/runes/tx/<TXID>" | jq .

{
    "data": [
        {
            "rune_id": "30562:50",
            "amount": "100000000",
            "output": 1,
            "block_height": 30562
        }
    ],
    "indexer_info": {
        "chain_tip": {
            "block_hash": "0000000000000035ec326a15b2f81822962f786028f33205b74b47a9b7cf3caf",
            "block_height": 38980
        },
        "mempool_timestamp": null,
        "estimated_blocks": []
    }
}

Contributing

Pull requests and issues are welcome! See the Kanban board for project status and tasks.

Feature Checklist

Base Indexer
- Addresses
  - Runes by address
  - Runes by address and rune ID
  - Runes by address and transaction ID
  - Rune UTXOs by address
  - Rune UTXOs by address and rune ID
  - UTXOs by address
  - Satoshi balance by address
  - BRC20 by address
  - Inscriptions by address
  - Transactions by address
- Runes
  - Rune info by rune ID
  - Rune balance by rune ID and UTXO
  - List runes
  - Holders by rune
  - UTXOs by rune
Wallet activity
- Addresses
  - Satoshi activity by address
  - Metaprotocol activity by address
  - Historical satoshi balance by address
  - Inscription activity by address
  - Address statistics
Alkanes
Webhook Notifications

License

This project is licensed under the Apache 2.0 License.