maestro-symphony

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

maestro-symphony

★ 42 Open GitHub ↗

Fast, mempool-aware, and extensible Bitcoin indexer and API server

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

🎵 ₿ _from hash to harmony: an orchestrated Bitcoin indexing suite_ ₿ 🎵

# [Maestro Symphony](https://www.gomaestro.org/)

---

## 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

<details>
<summary>Supported Networks</summary>

-   mainnet
-   testnet4
-   regtest

</details>

<details>
<summary>Indexers</summary>

-   Runes
-   Transaction count by address
-   UTXOs by address
-   Charms

</details>

**Endpoints:** [OpenAPI](docs/openapi.json)

**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+)](https://hub.docker.com/r/bitcoin/bitcoin) with RPC and P2P access
-   [Rust (stable)](https://www.rust-lang.org/tools/install)

### Optional Tools

-   [Docker](https://docs.docker.com/compose/install/)
-   [mise](https://mise.jdx.dev/getting-started.html)
-   [cargo-audit](https://github.com/RustSec/rustsec/tree/main/cargo-audit)

### Deployment Requirements

<details>
<summary>Testnet4</summary>

-   Disk: 4 GB
-   CPU: 2 cores
-   RAM: 4 GB
-   Sync time: ~30 minutes

</details>

<details>
<summary>Mainnet</summary>

-   Disk: 100 GB
-   CPU: 4 cores
-   RAM: 12 GB
-   Sync time: ~4 days

</details>

**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"` |
| | `max_rollback` | Number of rollbacked blocks from tip that can be handled | `32` |
| | `mempool` | Enable mempool awareness | `true` |
| | `utxo_cache_size` | Memory in GB to allocate to UTxO cache (default 40% RAM) | `1.0` |
| `[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"` |
| `[storage]` | `rocksdb_memory_budget`| Bound RocksDB memory usage in GB (default 25% RAM + ~2% DB)| `3.0` |

See [examples](examples/) to quickly get started.

---

## Deployment

### Quick Start with Snapshots

See instructions [here](docs/guides/setup-with-snapshot.md).

---

### Running Locally

Optionally, use `mise` to easily set up your environment:

```bash
mise install
```

#### Build

```bash
make build
```

#### Sync & Serve

```bash
make run [CONFIG=examples/testnet.toml]
```

#### Sync Only

```bash
make sync [CONFIG=examples/testnet.toml]
```

#### Serve Only

```bash
make serve [CONFIG=examples/testnet.toml]
```

#### Generate OpenAPI

```bash
make openapi
```

#### Install Git Hooks

```bash
make install-hooks
```

`pre-push` hook runs `make fmt-check` and `make lint`, matching the CI formatting and clippy checks.

---

### Running with Docker

#### Start

```bash
make compose-up
```

#### Stop

```bash
make compose-down
```

---

## Endpoint Examples

### Rune UTXOs by Address

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

```json
{
    "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)

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

```json
{
    "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

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

#### Rune Balance Changes in a Transaction

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

```json
{
    "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": []
    }
}
```

---

## Security

Maestro Symphony has undergone professional security audits to ensure the safety and reliability of the codebase.

### Audit Reports

-   **[Thesis Defense Security Audit (September 2025)](docs/audits/Thesis-Defense-audit-9-18-25.pdf)** - Independent security assessment of the core indexing and API components.

For reporting security vulnerabilities, please see our [Security Policy](SECURITY.md).

---

## Contributing

Pull requests and issues are welcome! See the [Kanban board](https://github.com/orgs/maestro-org/projects/16/views/1) for project status and tasks.

---

## License

This project is licensed under the [Apache 2.0 License](./LICENSE).

maestro-symphony

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README