Maestro Docs

The 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. This guide explains how to construct and integrate custom logic to be extracted and persisted during transaction processing by the Maestro Symphony indexer.

Steps

1. Create a New Indexer Project and Initialize it

After forking the repo, create a file or module in the /custom subdirectory. Setup a new project directory

Bash

mkdir -p src/sync/stages/index/indexers/custom/my_proj

Create the files (plus any extra that you need)

Bash

touch mod.rs indexer.rs tables.rs

Generate the mod.rs (and add your related files)

Bash

pub mod indexer;
pub mod tables;

It is recommended to split logic across multiple files (see the runes indexer for reference).

2. Register a New Enum Variant

Create a new TransactionIndexerType enum variant:

Text

src/sync/stages/index/indexers/custom/my_proj/mod.rs

Add your variant only at the end. Example:

Rust

/// Unique u8 for each transaction indexer, used in the key encodings. Do not modify, only add new
/// variants.
#[derive(Clone, Copy, Encode, Decode, PartialEq, Eq, std::hash::Hash, Debug)]
#[repr(u8)]
pub enum TransactionIndexerType {
    TxCountByAddress = 0,
    Runes = 1,
    UtxosByAddress = 2,
    MyProjIndexer = 3,      // my_proj indexer
}

⚠️ Do not reorder or delete existing variants. They are encoded as u8 and reused in key encodings. Any change will corrupt existing indexed data unless starting from a clean state.

3. Define the Indexer Object

Implement a struct that represents your indexer and implements the ProcessTransaction trait.

Rust

pub struct MyProjIndexer {
    start_height: u64,
    track_inputs: bool,
}

impl ProcessTransaction for MyProjIndexer {
    fn process_tx(
        &mut self,
        task: &mut IndexerTask,
        tx: &Transaction,
        ctx: &IndexerContext,
    ) -> Result<(), Error> {
        ...
    }
}

Where:

task: read/write interface to storage
tx: the transaction being processed
ctx: context with input resolver, block height, hash, network, arbitrary data to outputs, etc.

A resolver lets you provide a transcation input UTXO reference and receive the corresponding transaction output UTXO. Reference:
runes/indexer.rs#L41-L61

4. Implement and Handle Config

Your indexer should expose a new() function that takes a configuration struct and returns an instance of the indexer. This enables configuration-driven behavior such as start_height, track_inputs, or custom logic.

Rust

impl MyProjIndexer {
    pub fn new(config: MyProjIndexerConfig) -> Result<Self, Error> {
        let start_height = config.start_height;
        let track_inputs = config.track_inputs;

        Ok(Self {
            start_height,
            track_inputs,
        })
    }
}

#[derive(Clone, Debug, Deserialize)]
pub struct MyProjIndexerConfig {
    #[serde(default)]
    pub start_height: u64,
    #[serde(default)]
    pub track_inputs: bool,
}

The MyProjIndexerConfig struct should define fields relevant to your indexer. Reference

5. Define Storage Tables

Define custom key-value tables for storing the new data using the define_indexer_table! macro.

Text

src/sync/stages/index/indexers/custom/my_proj/tables.rs

Example:

Rust

define_indexer_table! {
    name: MyProjIndexerKV,
    key_type: ScriptPubKey,
    value_type: u64,
    indexer: TransactionIndexer::MyProjIndexer,
    table: 0
}

Rust

// key-value:
address => tx_count

Each table must:

Have a unique table ID
Use your new enum variant
Use key/value types that implement Encode and Decode

Reference:
tx_count_by_address.rs#L20-L26

6. Implement `ProcessTransaction`

Process each transaction by:

Iterating over inputs, ouputs, resolving UTXOs, etc.
Reading/writing to storage with

Rust

impl ProcessTransaction for MyProjIndexer {
    fn process_tx(
        &mut self,
        task: &mut IndexerTask,
        tx: &Transaction,
        ctx: &IndexerContext,
    ) -> Result<(), Error> {
        let TransactionWithId { tx, .. } = tx;
        ...
        // retrieve value from KV store
        task.get::<MyProjIndexerKV>(&key)?;
        ...
        // set value in KV store
        task.put::<MyProjIndexerKV>(&key, &value)?;
        ...
    }
}

Example:
tx_count_by_address.rs#L38-L76

7. Register Module and Add to Factory

Add your my_proj module in custom/mod.rs:

Rust

pub mod id;
pub mod runes;
pub mod tx_count_by_address;
pub mod utxos_by_address;
pub mod my_proj;            // my_proj indexer

Reference Next, add your variant to:

The TransactionIndexerFactory enum
The create_indexer function

Rust

#[derive(Clone, Debug, Deserialize)]
#[serde(tag = "type")]
pub enum TransactionIndexerFactory {
    TxCountByAddress,
    Runes(RunesIndexerConfig),
    UtxosByAddress,
    MyProjIndexer(MyProjIndexerConfig),
}

impl TransactionIndexerFactory {
    pub fn create_indexer(self) -> Result<Box<dyn ProcessTransaction>, Error> {
        match self {
            Self::TxCountByAddress => Ok(Box::new(TxCountByAddressIndexer::new())),
            Self::Runes(c) => Ok(Box::new(RunesIndexer::new(c)?)),
            Self::UtxosByAddress => Ok(Box::new(UtxosByAddressIndexer::new())),
            Self::MyProjIndexer(c) => Ok(Box::new(MyProjIndexer::new(c)?)),
        }
    }
}

8. (Optional) Attach Metadata to UTXOs

To persist data across transactions using UTXOs (e.g., inscriptions, runes), you can attach metadata during output processing:

Rust

task.attach_metadata_to_output(vout, &data)?;

Later, during input resolution:

Rust

let meta = ctx.resolver.resolve_input(input)?.metadata::<YourType>()?;

Examples:

This saves storage and avoids manually tracking UTXOs elsewhere.

For working examples, refer to:

🎉 You’re Done!

You have now walked through a guide on how to index a custom piece of data and add an API endpoint using the Maestro Symphony. Be sure to check out Maestro’s additional services for further assisting your development of building on Bitcoin.

SupportIf you are experiencing any trouble with the above, reach out on Discord.

​Steps

​1. Create a New Indexer Project and Initialize it

​2. Register a New Enum Variant

​3. Define the Indexer Object

​4. Implement and Handle Config

​5. Define Storage Tables

​6. Implement ProcessTransaction

​7. Register Module and Add to Factory

​8. (Optional) Attach Metadata to UTXOs

​🎉 You’re Done!

Steps

1. Create a New Indexer Project and Initialize it

2. Register a New Enum Variant

3. Define the Indexer Object

4. Implement and Handle Config

5. Define Storage Tables

6. Implement `ProcessTransaction`

7. Register Module and Add to Factory

8. (Optional) Attach Metadata to UTXOs

🎉 You’re Done!