Skip to content

Configuration

Jump to bottom
Alessandro Siniscalchi edited this page Feb 2, 2026 · 6 revisions

Configuration

Configuration Sources

brc721 resolves configuration in three layers, with later entries overriding earlier ones:

  1. Built-in defaults compiled into the binary (start block 923580, data dir .brc721/, API 127.0.0.1:8083, etc.).
  2. Environment variables that already exist in your shell or CI job.
  3. CLI flags that you pass to cargo run -- ... or the compiled binary.

Before clap parses any arguments, the process loads a dotenv file: it looks for DOTENV_PATH and falls back to .env. Keys in that file behave exactly like real environment variables but do not overwrite values that are already exported in the shell. This makes it easy to keep per-network defaults in .env.mainnet, .env.testnet, etc., and choose one at runtime via DOTENV_PATH=.env.testnet cargo run -- ....

CLI Flags

All global flags can be combined with any subcommand. CLI flags always win over environment variables.

Flag Env binding Default What it controls
-s, --start <HEIGHT> BRC721_START_BLOCK 923580 First block height to scan when no prior state exists. Once the index is primed, brc721 resumes from the last stored block regardless of this flag.
-c, --confirmations <N> - 3 How many confirmations to wait before considering a block final. Higher values trade latency for safety.
-b, --batch-size <SIZE> - 1 Number of blocks requested from Bitcoin Core per RPC round-trip. Increase if your node can handle more throughput.
--reset - false Drop the SQLite index (brc721.sqlite) before starting. Wallet files remain untouched.
--data-dir <DIR> - .brc721/ Base directory for all persistent files. The detected network name (bitcoin/testnet/regtest/signet) is appended automatically.
--rpc-url <URL> BITCOIN_RPC_URL http://127.0.0.1:8332 Bitcoin Core RPC endpoint. Must match the network you want to scan.
--rpc-user <USER> BITCOIN_RPC_USER dev Basic-auth username forwarded to Bitcoin Core.
--rpc-pass <PASS> BITCOIN_RPC_PASS dev Basic-auth password. Use shell or env overrides to avoid storing secrets in history.
--log-file <PATH> BRC721_LOG_FILE unset Optional secondary sink for logs. Logs always go to stderr; this flag adds a file sink (directories are created automatically).
--api-listen <ADDR> BRC721_API_LISTEN 127.0.0.1:8083 Bind address for the REST API (daemon mode). Accepts host:port.

Subcommands

If you run brc721 with no subcommand, it starts the scanner and REST API. The subcommands below are one-shot actions.

  • wallet <generate|init|address|addresses|balance|rescan|info|load|unload|assets> - manages the local descriptor wallet stored under the data directory.
  • tx <register-collection|register-ownership|send-amount|send-assets|mix> - builds and broadcasts protocol transactions using the encrypted master key.

Environment Variables

Most users keep frequently repeated values in a dotenv file and override the rest inline. Relevant variables:

  • BITCOIN_RPC_URL - RPC endpoint including scheme and port (http://127.0.0.1:8332, http://localhost:18332, http://127.0.0.1:18443, etc.).
  • BITCOIN_RPC_USER, BITCOIN_RPC_PASS - Basic-auth credentials that Bitcoin Core expects.
  • BRC721_START_BLOCK - Mirrors --start for automation. Only used when no prior chain state exists.
  • BRC721_API_LISTEN - Mirrors --api-listen. Useful when running multiple instances behind different ports.
  • BRC721_LOG_FILE - Mirrors --log-file. Use absolute paths (for example, /var/log/brc721/mainnet.log) when running under systemd or Docker.
  • DOTENV_PATH - Points to the dotenv file to load before parsing the CLI. Defaults to .env.
  • RUST_LOG - Standard tracing_subscriber filter. Example: RUST_LOG=brc721=debug,hyper=warn,tokio=info.

Tip: store per-network values in .env.mainnet, .env.testnet, .env.regtest, etc., add them to .gitignore, and point DOTENV_PATH at the one you need for a given run.

Data Directory Layout

The daemon appends the detected Bitcoin network name to the base --data-dir, ensuring you can run multiple networks side by side without collisions. Example tree for regtest:

.brc721/regtest/
|-- brc721.sqlite        # Chain state + collection index (rusqlite)
|-- master-key.age       # Encrypted BIP39 master Xpriv (age + passphrase)
|-- wallet.sqlite        # BDK descriptor wallet + address cursors
|-- wallet.sqlite-shm    # SQLite WAL sidecar (auto-created)
`-- wallet.sqlite-wal    # SQLite WAL sidecar (auto-created)
  • brc721.sqlite holds chain_state, collections, and ownership ranges. --reset only deletes this file.
  • wallet.sqlite tracks descriptors, derivation indices, and cache for the local wallet commands.
  • master-key.age stores the encrypted extended private key protected by the passphrase you supply to wallet init.

When you set a custom data dir (for example, /var/lib/brc721), the network suffix is still appended (/var/lib/brc721/testnet, etc.). Backups and restores are easiest if you treat each network directory as a unit.

Logging and Tracing

brc721 wires the log crate into tracing_subscriber. By default it emits human-readable logs to stderr at info level.

  • Set RUST_LOG to raise or lower verbosity per module (RUST_LOG=brc721=debug,hyper=warn).
  • Use --log-file /path/to/brc721.log (or BRC721_LOG_FILE) to tee logs to disk. The directory is created automatically; logs are appended and not rotated, so rely on logrotate or journald for pruning.
  • The same tracing stack is reused by the REST server and the scanner, so a single RUST_LOG filter covers the whole process.

Example:

RUST_LOG=brc721=debug,tokio=info \
DOTENV_PATH=.env.mainnet \
cargo run --release -- \
  --batch-size 25 \
  --confirmations 6 \
  --log-file /var/log/brc721/mainnet.log

Security-Sensitive Values

  • RPC credentials: keep .env* files outside version control and limit file permissions. Prefer a secrets manager or shell exports over typing --rpc-pass inline.
  • Wallet secrets: master-key.age contains your master extended private key encrypted with the passphrase supplied during wallet init. Use a strong passphrase and avoid committing the file.
  • Passphrases in automation: the --passphrase flag on wallet and tx subcommands is for non-interactive environments but will leak into shell history. Use env vars or process substitutions if you must automate it.
  • Logs: when BRC721_LOG_FILE is configured, logs may contain addresses, RPC URLs, and failure details. Treat log directories as sensitive.
  • Reset does not wipe wallets: --reset only clears brc721.sqlite. Manually remove the wallet files if you need a clean slate.

Configuration Examples

Mainnet scanner (.env.mainnet)

# ~/.config/brc721/.env.mainnet
BITCOIN_RPC_URL=http://127.0.0.1:8332
BITCOIN_RPC_USER=brc721
BITCOIN_RPC_PASS=change-me
BRC721_LOG_FILE=/var/log/brc721/mainnet.log

Run the daemon with stricter confirmations and a dedicated data directory:

DOTENV_PATH=~/.config/brc721/.env.mainnet \
cargo run --release -- \
  --confirmations 6 \
  --batch-size 25 \
  --data-dir /var/lib/brc721 \
  --api-listen 0.0.0.0:8083

Testnet watcher (.env.testnet)

# ~/.config/brc721/.env.testnet
BITCOIN_RPC_URL=http://127.0.0.1:18332
BITCOIN_RPC_USER=test
BITCOIN_RPC_PASS=test
BRC721_START_BLOCK=0
BRC721_API_LISTEN=127.0.0.1:8084

Useful command while experimenting with smaller confirmations:

DOTENV_PATH=~/.config/brc721/.env.testnet \
cargo run -- \
  --data-dir .brc721-testnet \
  --confirmations 2

Regtest / Docker (.env.regtest)

# project/.env.regtest
BITCOIN_RPC_URL=http://127.0.0.1:18443
BITCOIN_RPC_USER=dev
BITCOIN_RPC_PASS=dev
BRC721_START_BLOCK=0
BRC721_LOG_FILE=.brc721/regtest/brc721.log

After docker compose up -d (or bitcoind -regtest ...), run:

DOTENV_PATH=.env.regtest \
cargo run -- \
  --reset \
  --batch-size 10 \
  --api-listen 127.0.0.1:8083

This configuration wipes and rebuilds the SQLite index each time, making it ideal for integration tests and CI jobs.

Clone this wiki locally