feat: optional Bitcoin node + BTC wallet (bitcoind + BDK sidecar)

.env.example

@@ -87,6 +87,37 @@ PINATA_JWT=
 # Found in Pinata dashboard → Gateways. Looks like: yourname.mypinata.cloud
 PINATA_GATEWAY_URL=
 
+# ── Bitcoin node + BTC wallet (optional, profile: bitcoin) ──────────
+# Light wallet keys live in the bdk-wallet sidecar; bitcoind provides chain
+# data and broadcasts transactions. Enable with:
+#   docker compose --profile bitcoin up -d
+BITCOIN_ENABLED=false
+
+# Bitcoin network. Empty = follow NETWORK above (mainnet/testnet).
+# Valid values: mainnet, testnet, regtest, signet.
+BITCOIN_NETWORK=
+
+# Credentials for the bitcoind RPC (used by the bdk-wallet sidecar).
+BITCOIN_RPC_USERNAME=bitcoin_user
+BITCOIN_RPC_PASSWORD=bitcoin_password_change_me
+
+# Credentials the web GUI uses to reach the bdk-wallet sidecar's HTTP API.
+BITCOIN_WALLET_HTTP_USERNAME=btcwallet_user
+BITCOIN_WALLET_HTTP_PASSWORD=btcwallet_password_change_me
+
+# Advanced: transaction index and pruning for bitcoind.
+# txindex=1 (default) is required for full wallet history.
+# prune>0 saves disk but is incompatible with the wallet history sync
+# (mainnet chain data is ~700 GB with txindex=1).
+BITCOIN_TXINDEX=1
+BITCOIN_PRUNE=0
+
+# Block explorer used for tx/address links in the Bitcoin page.
+# Empty default: public networks link to mempool.space; regtest links to
+# the self-hosted btc-rpc-explorer sidecar (http://localhost:3002).
+# Set to any explorer base URL to override both.
+BITCOIN_EXPLORER_URL=
+
 # ── Watchtower (optional, profile: watchtower) ───────
 # Auto-updates Mintlayer Docker images daily at 04:00.
 # Start with: docker compose --profile watchtower up -d

.gitignore

@@ -37,3 +37,8 @@ Thumbs.db
 .idea/
 *.swp
 *.swo
+
+# Bitcoin (optional, profile: bitcoin)
+bitcoin-data/
+bitcoin-wallet-data/
+bdk-wallet/target/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: up down restart nuke restart-gui build logs dev dev-build dev-local wallet-cli nft-images-public pending-transactions list-utxos
+.PHONY: up down restart nuke restart-gui build logs dev dev-build dev-local wallet-cli bitcoin bitcoin-cli nft-images-public pending-transactions list-utxos
 
 ACCOUNT ?= 0
 
@@ -8,7 +8,7 @@ up:
 
 ## Stop and remove all containers (including optional profiles and orphaned run containers)
 down:
-	docker compose --profile indexer --profile wallet_cli down --remove-orphans
+	docker compose --profile indexer --profile wallet_cli --profile bitcoin down --remove-orphans
 
 ## Full clean restart: tear down everything, fix stuck networks, then bring up fresh
 ## Fixes "Network still in use" / "network not found" errors from dangling containers.
@@ -27,7 +27,7 @@ restart: down
 ## Nuclear option: remove ALL stopped containers and unused networks project-wide,
 ## then restart. Use when restart still fails.
 nuke:
-	docker compose --profile indexer --profile wallet_cli down --remove-orphans --volumes 2>/dev/null || true
+	docker compose --profile indexer --profile wallet_cli --profile bitcoin down --remove-orphans --volumes 2>/dev/null || true
 	docker container prune -f
 	docker network prune -f
 	docker compose up -d
@@ -62,6 +62,17 @@ dev-build:
 wallet-cli:
 	docker compose --profile wallet_cli run --rm wallet-cli
 
+## Start the optional Bitcoin stack (bitcoind + BTC wallet sidecar) alongside core services
+bitcoin:
+	docker compose --profile bitcoin up -d
+	@echo "Bitcoin node + BTC wallet started. First sync can take a long time on mainnet."
+	@echo "Open the Bitcoin page in the web UI to create your BTC wallet."
+
+## bitcoin-cli shell inside the Bitcoin node container
+## Usage: make bitcoin-cli CMD='getblockchaininfo'
+bitcoin-cli:
+	docker compose --profile bitcoin exec bitcoind bitcoin-cli -rpcport=8332 -rpcuser=$$(grep '^BITCOIN_RPC_USERNAME=' .env | cut -d= -f2) -rpcpassword=$$(grep '^BITCOIN_RPC_PASSWORD=' .env | cut -d= -f2) $(CMD)
+
 ## List pending transactions for account ACCOUNT (default 0) via wallet RPC.
 ## Usage: make pending-transactions  or  make pending-transactions ACCOUNT=1
 pending-transactions:

README.md

@@ -57,6 +57,8 @@ A `Makefile` wraps the most common Docker Compose commands:
 | `make dev-indexer` | Dev mode + full indexer stack |
 | `make dev-build` | Rebuild the dev image (run after adding npm packages) |
 | `make wallet-cli` | Open an interactive wallet-cli session |
+| `make bitcoin` | Start the optional Bitcoin node + BTC wallet |
+| `make bitcoin-cli CMD='getblockchaininfo'` | Run bitcoin-cli inside the node |
 
 ---
 
@@ -130,6 +132,33 @@ The REST API is available at <http://localhost:3000> (configurable via `API_WEB_
 
 ---
 
+## Optional: Bitcoin node + BTC wallet
+
+Adds a Bitcoin Core node and a built-in BTC wallet (balance, receive, send) to the web UI.
+
+```bash
+docker compose --profile bitcoin up -d      # or: make bitcoin
+```
+
+How it works:
+
+- **`bitcoind`** provides chain data and broadcasts transactions. It needs no host ports.
+- **`bdk-wallet`** is a light-wallet sidecar (BDK, BIP84) that holds the BTC keys and signs
+  transactions locally. The web GUI talks to it over the internal Docker network.
+- The wallet seed is generated in the web UI and **shown exactly once** — back it up when prompted.
+- All BTC API routes require a logged-in session; the sidecar is not reachable from outside.
+
+**Requirements and warnings**
+
+- Mainnet chain data is roughly **700 GB** with the default `txindex=1`. The first sync can
+  take days. Use `BITCOIN_NETWORK=testnet` (or `regtest`) to try it out cheaply.
+- The BTC wallet is a **hot wallet** — keep only spending amounts on it.
+- Pruning (`BITCOIN_PRUNE`) is incompatible with the wallet's history sync; leave it off.
+- Bitcoin Core is pinned to **25.x**: the BDK rpc backend cannot parse the `warnings`
+  format used by Core 26+. Override only if you know what you are doing (`BITCOIND_IMAGE`).
+
+---
+
 ## Useful commands
 
 ```bash
@@ -170,6 +199,7 @@ docker compose pull && docker compose up -d
 | Staking | `/staking` | Staking status and instructions |
 | Token Management | `/token-management` | Issue and manage tokens — **requires indexer** |
 | Trading | `/trading` | DEX trading — **requires indexer** |
+| Bitcoin | `/bitcoin` | BTC balance, receive and send — **requires bitcoin profile** |
 | Wallet setup | `/setup` | Create or open a wallet |
 
 > **Token Management** and **Trading** are hidden when `INDEXER_ENABLED=false` in `.env`.

app/package.json

@@ -25,13 +25,15 @@
     "astro": "^7.2.0",
     "better-sqlite3": "^12.9.0",
     "clsx": "^2.1.1",
+    "cookie": "^1.1.1",
     "es-module-lexer": "^1.7.0",
     "qrcode": "^1.5.4",
     "qrcode.react": "^4.2.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^3.4.0",
+    "ethers": "^6.17.0",
     "ws": "^8.20.0",
     "zod": "^4.4.3"
   },