This repository provides a local development environment for learning about Bitcoin through hands-on experimentation. By running a local Bitcoin signet network and Mempool explorer, you can interact with Bitcoin's functionality in a controlled environment without using real funds.
This project consists of:
- Bitcoin Signet - A sandboxed Bitcoin test network where blocks can be mined locally
- Esplora Explorer - A web interface for visualizing transactions and blocks
- Mempool Dashboard - A comprehensive visualization of Bitcoin's mempool, transactions, and blocks
By connecting various Bitcoin applications to this local environment, you can learn about:
- Bitcoin transactions and the UTXO model
- Block mining and confirmation
- Transaction fees and mempool dynamics
- Bitcoin scripting and smart contracts
- Wallet integration and development
- Docker and Docker Compose
- Git
There are two ways to set up the environment:
This single docker-compose file manages both Bitcoin Signet and Esplora services with proper networking:
-
Clone this repository:
git clone <repository-url> cd <repository-directory>
-
Start all services with one command:
docker-compose up -d
This will:
- Create a Bitcoin Signet miner node
- Create a Bitcoin Signet full node (optional, connects to the miner)
- Start the Esplora block explorer connected to the Bitcoin Signet miner
- Start the Mempool Dashboard with database and API components
- Set up proper networking between all services
- Map all required ports to the host
-
Access the explorers:
- Esplora: http://localhost:3001
- Mempool UI: http://localhost:3002
Important: On first start, it may take some time (1-2 minutes) for all services to initialize and connect to each other. Esplora needs to index the blockchain and Mempool API needs to sync with both Bitcoin and Esplora.
To access from a remote host, replace
localhostwith your server's public IP address:- Esplora: http://YOUR_SERVER_IP:3001
- Mempool UI: http://YOUR_SERVER_IP:3002
Make sure these ports are open in your firewall if accessing remotely:
sudo ufw allow 3001/tcp sudo ufw allow 3002/tcp
Once your services are running, you can interact with them:
docker-compose ps# View logs for all services
docker-compose logs
# View logs for a specific service
docker-compose logs bitcoin-miner
docker-compose logs esplora
# Follow logs in real-time
docker-compose logs -fYou can trigger block mining on the Bitcoin signet miner node:
docker exec bitcoin-miner bitcoin-cli -rpcuser=bitcoin -rpcpassword=bitcoin -rpcport=38332 getblockchaininfoThe mining process runs automatically in the background in signet mode. The miner will create blocks approximately every 30 seconds (as configured by BLOCKPRODUCTIONDELAY). You can watch new blocks appear in both Esplora and Mempool explorers.
If mining isn't progressing, check the miner process:
docker exec bitcoin-miner ps aux | grep mineYou should see the Python miner script running.
You can use RPC commands to interact with the Bitcoin signet node. Here are some examples:
Get blockchain information:
curl --user bitcoin:bitcoin --data-binary '{"jsonrpc":"1.0","method":"getblockchaininfo","params":[]}' -H 'content-type:text/plain;' http://127.0.0.1:38332Get a new address:
curl --user bitcoin:bitcoin --data-binary '{"jsonrpc":"1.0","method":"getnewaddress","params":[]}' -H 'content-type:text/plain;' http://127.0.0.1:38332Send coins to an address (replace
and ):curl --user bitcoin:bitcoin --data-binary '{"jsonrpc":"1.0","method":"sendtoaddress","params":["<address>", <amount>]}' -H 'content-type:text/plain;' http://127.0.0.1:38332List unspent transaction outputs:
curl --user bitcoin:bitcoin --data-binary '{"jsonrpc":"1.0","method":"listunspent","params":[]}' -H 'content-type:text/plain;' http://127.0.0.1:38332The Mempool API provides rich data about blocks, transactions, and the mempool state. Here are some examples:
Get recommended fees:
curl http://localhost:3002/api/v1/fees/recommendedGet mempool statistics:
curl http://localhost:3002/api/mempoolGet information about a block by height:
curl http://localhost:3002/api/block/<height>Get information about a transaction:
curl http://localhost:3002/api/tx/<txid>Full API documentation can be found at the Mempool GitHub repository.
docker-compose downTo completely reset the environment (this will delete all blockchain data):
docker-compose down -v
docker-compose up -d-
Clone this repository:
git clone <repository-url> cd <repository-directory>
-
Start the Bitcoin signet node:
cd bitcoin_signet docker-compose up -d -
Start the Mempool explorer:
cd ../esplora/contrib # Before running, update the docker-compose.yml to use signet instead of regtest # Change the command line from: # - '/srv/explorer/run.sh bitcoin-regtest explorer nonverbose' # to: # - '/srv/explorer/run.sh bitcoin-signet explorer nonverbose' docker-compose up -d
Alternatively, run directly with Bitcoin signet configuration:
docker run -p 50001:50001 -p 8084:80 \ --volume $PWD/data_bitcoin_signet:/data \ --rm -i -t blockstream/esplora \ bash -c "/srv/explorer/run.sh bitcoin-signet explorer" -
Access the Mempool explorer at http://localhost:80 or http://localhost:8084 (if using the direct docker run command)
Note: If you're using Option 1 (root-level docker-compose.yml), the connection between Bitcoin Signet and Esplora is already configured and you can skip this section.
To ensure that Esplora can connect to your Bitcoin signet node when setting up components separately, you need to make sure they can communicate with each other:
-
Network configuration:
- If using Docker Compose for both services, create a shared network:
docker network create bitcoin-network
- Update both docker-compose files to use this network:
networks: default: external: name: bitcoin-network
- If using Docker Compose for both services, create a shared network:
-
Update Esplora's configuration to point to the Bitcoin signet RPC:
-
If using Docker Compose, add environment variables to Esplora's service:
environment: - BITCOIND_URI=http://bitcoin:bitcoin@bitcoin-signet:38332
-
Make sure your Bitcoin signet node has RPC enabled and is accessible:
rpcbind=0.0.0.0 rpcallowip=0.0.0.0/0
-
You can connect various Bitcoin applications to your local signet:
Configure Bitcoin Core to connect to your local signet:
signet=1
signetchallenge=<your-signet-challenge>
addnode=127.0.0.1:38333
Most wallet applications that support signet can be configured to connect to your local node:
- RPC Endpoint: http://127.0.0.1:38332
- RPC Username: bitcoin
- RPC Password: bitcoin
This setup provides two different explorer interfaces, each with unique features:
Esplora Explorer (http://localhost:3001)
Esplora is a lightweight block explorer that provides:
- Clean, minimalist interface
- Basic transaction and block viewing
- Address balance and history
- Support for Segwit and Bech32 addresses
- Advanced transaction view with script details
- Mobile-friendly design
Mempool Dashboard (http://localhost:3002)
Mempool offers a more comprehensive view of the Bitcoin network:
- Real-time mempool visualization
- Fee estimation graphs
- Block explorer with detailed statistics
- Transaction acceleration
- Lightning Network statistics (not applicable for signet)
- Rich API for developers
- Transaction tracking
- Advanced visualization of blockchain data
Both explorers complement each other and provide different perspectives on the same blockchain data.
Contributions to improve the learning environment are welcome! Please feel free to submit pull requests or create issues with suggestions.
This typically happens when Esplora is trying to sync with the public signet chain instead of your local one:
-
Ensure docker-compose.yml uses the correct network mode for Esplora:
command: - bash - -c - '/srv/explorer/run.sh bitcoin-signet explorer nonverbose' # Use signet, not regtest
-
Check Bitcoin RPC connection:
curl --user bitcoin:bitcoin --data-binary '{"jsonrpc":"1.0","method":"getblockchaininfo","params":[]}' -H 'content-type:text/plain;' http://127.0.0.1:38332
-
Inspect Esplora logs:
docker logs esplora
Mempool requires properly configured RPC connections to both Bitcoin and Esplora:
-
Check whether Mempool API is connecting to Bitcoin:
docker logs mempool-api | grep "mempool is now in sync"
-
Look for Electrum connection errors:
docker logs mempool-api | grep "Electrum error"
-
Ensure all required environment variables are set in docker-compose.yml:
MEMPOOL_BITCOIN_NETWORK: "signet" # Match your Bitcoin node's network DATABASE_ENABLED: "true" MEMPOOL_BITCOIN_RPC_HOST: "bitcoin-miner" MEMPOOL_BITCOIN_RPC_PORT: "38332"
-
Restart Mempool API after configuration changes:
docker restart mempool-api
- Bitcoin Signet Node: Provides the blockchain and accepts transactions
- Esplora: Indexes the blockchain and provides an Electrum server API on port 50001
- Mempool UI: Consists of:
- Database (MariaDB): Stores indexed data about blocks and transactions
- Backend API: Connects to both Bitcoin (for mempool data) and Esplora (for blockchain data)
- Frontend: Web interface that visualizes the data
Proper network connectivity between all components is crucial. The docker-compose.yml in this repository uses a shared network to ensure all services can communicate properly.
This project is licensed under the MIT License - see the LICENSE file for details.