NBXplorer Documentation

NBXplorer is a minimalist UTXO tracker for HD wallets designed as an infrastructure tool for services. It supports various derivation schemes including P2SH, P2PKH, P2WPKH, P2WSH, Taproot, and multi-signature. It is designed to work on a pruned node and only indexes the UTXOs it is actively tracking.

Key Features:

• Miniscript support via Wallet Policies (BIP0388).
• Persistence using PostgreSQL.
• Support for multiple altcoins (e.g., BTC, LTC, DASH, DOGE, etc.).
• Automatic reconnection to nodes.
• REST API for interaction.
• Pruning of transaction data to save space.

The NBXplorer database schema is designed to be multi-tenant, multi-asset, and multi-chain. It uses a denormalized model to optimize query performance, where denormalization is managed automatically via database triggers.

The schema is organized into several logical groups:

• Blocks and transactions: blks, blks_txs, and txs.
• Outputs, Inputs, and Scripts: ins, outs, ins_outs, and scripts.
• Descriptors: descriptors and descriptors_scripts.
• Wallets: wallets, wallets_wallets, wallets_descriptors, and wallets_scripts.
• Double spending detection: spent_outs.

Developers can query the schema directly if the standard NBXplorer API does not meet their needs, or use it as a foundation for building custom indexers or APIs.

You can speed up the migration process by skipping certain data types if they are not required by your specific implementation:

• Skip Events: Use --nomigrateevts (NBXPLORER_NOMIGRATEEVTS=1) if your services do not query past events. (Note: BTCPay Server does not utilize past events and can safely use this flag).
• Skip Raw Transactions: Use --nomigraterawtxs (NBXPLORER_NOMIGRATERAWTXS=1) if preserving raw transaction bytes is nonessential. Warning: Raw transactions are typically required for signing with a non-segwit wallet.

In NBXplorer, a wallet is defined as a collection of wallets_descriptors and wallets_scripts.

Key behaviors include:

• Descriptor-to-Script mapping: If a descriptor is associated with a wallet, any entries in descriptors_scripts are automatically added to wallets_scripts via database triggers.
• Direct Scripting: Scripts can be added directly to wallets_scripts.
• Wallet Hierarchies: You can create parent-child relationships using the wallets_wallets table. When a child wallet is linked to a parent, any script belonging to the child wallet is automatically added to the parent wallet's scripts.

A Group is a tracked source that acts as a logical container for other tracked sources.

• Composition: You can add/remove derivation schemes, other groups, or standalone addresses to a group.
• Inheritance: Every address attached to a child tracked source is automatically included in the group, along with its UTXOs and transactions.
• Nesting: Groups can be children of other groups.
• Format: GROUP:groupid.

Warning: Avoid adding an excessive number of children to a single group, as this can degrade the performance of the Get a group API call.

NBXplorer does not index the entire blockchain. Instead, it monitors specific sets of addresses and their associated UTXOs, transactions, and balances. These sets are called Tracked Sources.

There are three types of tracked sources:

1. Derivation Schemes: Deterministic ways to generate addresses from a master public key (e.g., DERIVATIONSCHEME:xpub1).
2. Groups: Logical groupings of multiple tracked sources (e.g., GROUP:groupid). Groups can contain other groups or standalone addresses.
3. Standalone addresses: Monitoring a single specific address (e.g., ADDRESS:bc1...).

To extend NBXplorer to support a new altcoin, follow these steps:

1. Add Altcoin Support to NBitcoin: First, you must add support for your altcoin to the NBitcoin.Altcoins library.
2. Implement NBXplorer Network Provider: Once NBXplorer is updated to use the latest version of NBitcoin.Altcoins, implement a new network provider by following the pattern in NBXplorer.Client/NBXplorerNetworkProvider.Litecoin.cs.
3. Configure Test Environment: To verify your implementation, modify NBXplorer.Tests/ServerTester.Environment.cs to match your altcoin's parameters.
4. Run Tests: Execute the test suite to ensure everything is working correctly.

NBXplorer can be configured using three methods:

1. Command line arguments: e.g., --chains btc
2. Environment variables: e.g., NBXPLORER_CHAINS=btc
3. Configuration file: e.g., chains=btc

Configuration file locations:

• Windows: C:\Users\<user>\AppData\Roaming\NBXplorer\<network>\settings.config
• Linux/macOS: ~/.nbxplorer/<network>/settings.config

Important for developers using dotnet run: When running via dotnet run, you must pass settings after a -- separator to ensure they are passed to the application rather than the dotnet CLI. Otherwise, launch profiles meant for debugging might be used instead of your intended configuration.

dotnet run --no-launch-profile --no-build -c Release -p .\NBXplorer\NBXplorer.csproj -- --chains btc

To build a custom indexer on top of the NBXplorer schema, follow this typical workflow for processing blocks:

1. Insert Block: Insert the block into the blks table with confirmed='f'.
2. Match Transactions: Call the fetch_matches function using all inputs (ins) and outputs (outs) of the block. This populates temporary tables matched_outs, matched_ins, and matched_conflicts for inspection.
3. Persist Matches: Call save_matches to instruct the database to move the matched data into permanent tables.
4. Finalize Block: Set confirmed='t' for the block in the blks table.

Managing Descriptors: An indexer is also responsible for maintaining descriptors_scripts. You should monitor descriptors.gap; if the gap becomes too low, the indexer must insert the necessary scripts from the descriptor into the descriptors_scripts table.

Before installing or running NBXplorer, ensure the following are available:

• .NET SDK v10.0 or above
• Bitcoin Core instance (version 24.0 or higher) synced and running.
• PostgreSQL v13+ for data persistence.