A modern Bitcoin full node built in Rust, powered by libbitcoinkernel for byte-for-byte consensus compatibility with Bitcoin Core.
BitcoinWolfe pairs Bitcoin Core's own consensus engine (extracted as a C library) with a clean Rust stack for networking, storage, mempool policy, wallet, Lightning, and Nostr functionality. The result is a node that validates exactly like Core but is built from the ground up with modern Rust tooling.
Note: BitcoinWolfe is open-source software in active development. Use at your own risk. Contributions, bug reports, and feedback are welcome.
+------------------+
| wolfe-node |
| (CLI binary) |
+--------+---------+
|
+--------+--------+---------+---------+---------+--------+
| | | | | | |
+---+----+ +-+------+ +-+------+ +------+-+ +------+-+ +---+-----+
| wolfe- | | wolfe- | | wolfe- | | wolfe- | | wolfe- | | wolfe- |
| consen | | p2p | | mempl | | wallet | | lightn | | nostr |
| (kern) | | (tokio)| | (pol.) | | (BDK) | | (LDK) | | (sdk) |
+---+----+ +---+----+ +---+----+ +---+----+ +---+----+ +---+-----+
| | | | | |
+----+-----+-----------+----------+----------+-----------+
| | |
+-------+-------+ +------+------+ +------+------+
| wolfe-store | | wolfe-types | | wolfe-rpc |
| (redb) | | (config) | | (axum) |
+--------------+ +-------------+ +-------------+
| Crate | Purpose |
|---|---|
wolfe-consensus |
libbitcoinkernel FFI via the bitcoinkernel 0.2 crate -- consensus validation identical to Bitcoin Core |
wolfe-store |
Block headers, peers, and node metadata stored in redb (pure Rust, ACID, zero-copy reads) |
wolfe-p2p |
Async P2P networking on Tokio with Bitcoin protocol message serialization (rust-bitcoin 0.32), BIP324 v2 transport |
wolfe-mempool |
Configurable policy engine (OP_RETURN limits, fee floors, RBF, ancestor/descendant limits) + concurrent transaction pool |
wolfe-wallet |
BDK 1.1 descriptor wallet with SQLite persistence, PSBT support, and coin selection |
wolfe-lightning |
Lightning Network integration via LDK 0.2 -- peer connections, channels, invoices, payments |
wolfe-nostr |
Nostr integration via nostr-sdk -- block announcements, fee oracle, NIP-98 RPC auth |
wolfe-rpc |
axum REST API + Bitcoin Core-compatible JSON-RPC server with Prometheus metrics |
wolfe-types |
TOML configuration, shared types, and error definitions |
wolfe-node |
Main binary (wolfe) that wires everything together |
- Rust 1.85+ (edition 2021)
- cmake and a C++ compiler (required to build libbitcoinkernel)
git clone https://github.com/refined-element/BitcoinWolfe.git
cd BitcoinWolfe
cargo build --releaseThe binary is at target/release/wolfe.
# Start the node with default settings (mainnet)
./target/release/wolfe start
# Start on a different network
./target/release/wolfe --network signet start
# Use a custom config file
./target/release/wolfe --config my-config.toml startwolfe [OPTIONS] [COMMAND]
Commands:
start Start the node (default if no command given)
default-config Print the default TOML configuration to stdout
info Print version and build info
Options:
-c, --config <PATH> Path to config file [default: wolfe.toml]
-n, --network <NETWORK> Override the Bitcoin network (mainnet, testnet, signet, regtest)
-d, --datadir <PATH> Override the data directory
# Dump a starter config, then customize it
wolfe default-config > wolfe.toml
# Check the build
wolfe infoBitcoinWolfe is configured via TOML. Run wolfe default-config to generate a starting point.
[p2p]
listen = "0.0.0.0:8333"
max_inbound = 125
max_outbound = 10
prefer_v2_transport = true # BIP324 encrypted transport
dns_seeds = [] # Empty = built-in defaults
connect = [] # Manual peers (bypasses DNS)
ban_duration_secs = 86400[mempool]
max_size_mb = 300
min_fee_rate = 1.0 # sat/vB
max_datacarrier_bytes = 80 # OP_RETURN limit
datacarrier = true # Accept OP_RETURN outputs
full_rbf = true # Full Replace-By-Fee
max_ancestors = 25
max_descendants = 25
expiry_hours = 336[rpc]
enabled = true
listen = "127.0.0.1:8332"
rest_enabled = true
user = "rpcuser" # HTTP Basic auth
password = "rpcpassword"
cors_origins = [][wallet]
enabled = false # Opt-in
db_path = "wallet.sqlite3"[lightning]
enabled = false # Opt-in
listen_port = 9735
alias = "BitcoinWolfe"
color = "ff9900"
accept_inbound_channels = true
min_channel_size_sat = 20000
max_channel_size_sat = 16777215
# rapid_gossip_sync_url = "https://rapidsync.lightningdevkit.org/snapshot"[nostr]
enabled = false
relays = ["wss://relay.damus.io", "wss://nos.lol"]
block_announcements = true
fee_oracle = true
fee_oracle_interval_secs = 60
nip98_auth = false # NIP-98 Nostr auth for RPC
# allowed_pubkeys = ["npub1..."][storage]
prune_target_mb = 0 # 0 = full node, no pruning
db_cache_mb = 450
[metrics]
enabled = true
listen = "127.0.0.1:9332" # Prometheus scrape endpoint| Method | Path | Description |
|---|---|---|
| GET | /api/info |
Node version, chain, block height, mempool size, uptime |
| GET | /api/blockchain |
Chain tip height, best block hash, sync status |
| GET | /api/mempool |
Mempool size, byte count, active policy settings |
| GET | /api/peers |
Connected peers with user agents, versions, transport info |
| GET | /api/lightning/info |
Lightning node ID, channel count, peer count |
| GET | /api/lightning/channels |
Lightning channel list with capacities and status |
POST to / with standard JSON-RPC 2.0 payloads.
| Method | Description |
|---|---|
getblockchaininfo |
Chain, block height, best block hash, IBD status |
getblockcount |
Current block height |
getbestblockhash |
Hash of the chain tip |
getblock |
Block data by hash (raw hex or parsed, by verbosity) |
| Method | Description |
|---|---|
getnetworkinfo |
Version, user agent, protocol version, connection count |
getpeerinfo |
Per-peer address, user agent, version, direction |
| Method | Description |
|---|---|
getmempoolinfo |
Mempool loaded status, size, bytes, minimum fee |
getrawmempool |
List of transaction IDs in the mempool |
getrawtransaction |
Raw transaction data by txid (mempool lookup) |
sendrawtransaction |
Submit a raw transaction to the mempool |
| Method | Description |
|---|---|
getbalance |
Confirmed wallet balance in BTC |
getwalletinfo |
Balance breakdown (confirmed, unconfirmed, immature) |
getnewaddress |
Generate a new receiving address |
listtransactions |
List wallet transactions |
walletcreatefundedpsbt |
Create a funded PSBT for sending |
walletprocesspsbt |
Sign a PSBT with the wallet's keys |
| Method | Params | Description |
|---|---|---|
ln_getinfo |
Node ID, channel/peer counts | |
ln_listchannels |
Channel list with capacities and status | |
ln_listpeers |
Connected Lightning peers | |
ln_connect |
["pubkey@host:port"] |
Connect to a Lightning peer |
ln_openchannel |
["pubkey", amount_sat, push_msat?] |
Open a channel |
ln_invoice |
[amount_msat?, description?, expiry_secs?] |
Create a BOLT11 invoice |
ln_pay |
["lnbc..."] |
Pay a BOLT11 invoice |
| Method | Description |
|---|---|
uptime |
Node uptime in seconds |
stop |
Initiate graceful shutdown |
# Get blockchain info
curl -s http://127.0.0.1:8332/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"getblockchaininfo"}' | jq
# Connect to a Lightning peer
curl -s http://127.0.0.1:8332/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"ln_connect","params":["02abc...@host:9735"]}' | jq
# Create a Lightning invoice for 50 sats
curl -s http://127.0.0.1:8332/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"ln_invoice","params":[50000,"coffee"]}' | jq- Workspace structure with 10 crates
- libbitcoinkernel integration for consensus validation
- redb-based persistent storage (headers, metadata, peers)
- P2P version handshake and message serialization
- BIP324 v2 encrypted transport support
- Header-first initial block download (IBD)
- Full block download and validation
- Block pruning (configurable target size)
- Mempool with configurable policy engine (fees, OP_RETURN, RBF, ancestor limits)
- BDK descriptor wallet with SQLite backend
- PSBT workflow (create, sign)
- REST API and Bitcoin Core-compatible JSON-RPC
- RPC authentication (HTTP Basic + NIP-98 Nostr auth)
- Lightning Network via LDK (peer connect, channels, invoices, payments)
- Nostr integration (block announcements, fee oracle)
- TOML configuration with CLI overrides
- Prometheus metrics endpoint
- Structured logging (text and JSON formats)
- Graceful shutdown handling
- Transaction relay and fee estimation
- Compact block relay (BIP152)
- Lightning channel funding (FundingGenerationReady event handling)
- Lightning BOLT12 offers
- Rapid Gossip Sync
- Wallet
apply_block()chain feeding from node - Configuration hot-reload
- Peer scoring and eviction logic
- Grafana dashboard templates
BitcoinWolfe builds on the work of several excellent projects:
- libbitcoinkernel -- Bitcoin Core's consensus engine, extracted as a standalone C library.
- rust-bitcoin (0.32) -- Bitcoin data structures, script types, and protocol serialization.
- BDK (1.1) -- Descriptor-based wallet with coin selection, PSBT, and SQLite persistence.
- LDK (0.2) -- Lightning Development Kit for channel management, routing, and payments.
- nostr-sdk (0.39) -- Nostr protocol client for decentralized event publishing.
- redb -- Pure Rust, ACID-compliant, zero-copy embedded database.
- Tokio -- Async runtime powering the P2P, Lightning, and RPC layers.
- axum -- HTTP framework for the REST and JSON-RPC server.
MIT -- see LICENSE.