₿ Bitcoin Core
Full bitcoin node. Pruned by default.
Enabled unless an external full node is configured.
To enable fast-sync, set
TRUSTED_FASTSYNC=1. This will download a recent pruned datadir snapshot from prunednode.today and start syncing from that instead of from scratch.
This can get your node synced up 5-60 minutes, but requires ⚠ trusting the distributor of the snapshot. A malicious distributor could feed you with invalid chain history and lead you to accept fake coins. Please consider waiting some more for a full sync to avoid taking this risk.
A fast-synced node is not able to scan for historical wallet transactions and can therefore only be used with newly created wallets.
You'll need 10G of free space during the setup to store both the snapshot
.zipfile and the files extracted from it. It will shrink down to <5GB when the process completes.
Using existing full node
If you already have a Bitcoin Core instance running on the same machine, you can connect eznode to it using cookie authentication by mounting the datadir into
docker run -v ~/.bitcoin:/bitcoin:ro -it ... eznode/eznode
On Linux, you'll also need to add
--add-host host.docker.internal:host-gatewayto make the host's address discoverable from within the container. On Windows, change
Instructions for modifying bitcoind's
rpcallowip config will be shown on startup. If you're running into trouble with Docker's virtual networking, you can try with
--net host (this should ideally be avoided).
If your node is running remotely, you can configure its URL and RPC credentials with
Accessing managed full node
To issue RPC commands against eznode's managed Bitcoin Core instance, use
docker exec ez bitcoin-cli <command> (see Node management) or the web RPC console available in BTC RPC Explorer (public demo).
To connect to the Bitcoin Core RPC from your host, set
BITCOIND_RPC_ACCESS=<user:pwd> to open the RPC server for external access using password-based authentication.
On macOS/Windows, you'll also need to publish the RPC port with
-p 127.0.0.1:8332:8332 to make it available through
localhost. On Linux you can access it directly through the container's IP address or using the
ez alias (see Connecting Locally).
Options for managed full node
PRUNE=550(prune size, set to
0to disable pruning)
PRUNE_UNTIL=<off>(keep blocks after the given height/date)
TXINDEX=0(enable txindex, requires pruning to be disabled)
BITCOIND_LISTEN=0(accept incoming connections on the bitcoin p2p network)
BITCOIND_TOR=0(connect to the bitcoin network through tor)
BITCOIND_RPC_ACCESS(expose the bitcoind rpc with password-based auth)
BITCOIND_RPC_ONION=0(expose the bitcoind rpc over onion)
BITCOIND_OPTS=<none>(custom cli options for bitcoind)
BITCOIND_LOGS=0(display bitcoind's logs in the
A config file may also be provided at
/data/bitcoin/bitcoin.conf, but the options above will take priority over it.
Options for fast-sync
/bitcoin(mount the bitcoind datadir from the host to enable cookie authentication)
/data/bitcoin(managed bitcoind data directory)
🔍 Bitcoin Wallet Tracker
BWT keeps an index of your wallet transactions only. To make your wallet activity available, you'll need to configure your
DESC_* if you have multiple, e.g.
With pruning enabled (the default), starting with a new wallet is the easiest. A new wallet is also recommended for privacy reasons if your addresses were previously exposed to public Electrum servers. To use an existing wallet, refer to the instructions here.
Electrum wallet setup
If you're creating a new wallet, make sure you don't connect to public servers while doing it to avoid exposing your addresses. You can start Electrum with
--offline to ensure that.
Grab your xpub from
Information and add it to your config file (
~/eznode/config) as a new line with
Restart eznode, wait for BWT to start up and run
electrum $(docker exec ez electrum-args) to start Electrum and connect it with your local node. Or you can do this manually:
electrum --oneserver --server ez:50001:t --skipmerklecheck
If you don't have the
ezhostname set up, replace
ezwith the container's IP address (shown on startup) on Linux or with
127.0.0.1on macOS/Windows (
electrum-argsdoes this automatically).
To configure Electrum to use eznode by default, run
docker exec ez electrum-cfg | sh -x. This will issue
electrum setconfig commands (you can run without
| sh to see them).
You may also configure Electrum through the GUI, by setting the server address to
127.0.0.1:50001:t on macOS/Windows). However, setting
skipmerklecheck is not possible using the GUI, and the latter is required if pruning is enabled (the default).
If you're connecting remotely, you'll need to setup Tor Onion or an SSH tunnel for secure access.
Electrum wallet setup - with the BWT plugin
Alternatively, you can also setup Electrum desktop to connect with eznode using the BWT Electrum plugin. The plugin will run a separate BWT instance that connects directly to Bitcoin Core and automatically detects your wallet(s) xpub(s).
BWT=1(enabled by default, set to
0to turn off)
XPUB_*(xpubs/ypubs/zpubs to track)
DESC_*(script descriptors to track)
RESCAN_SINCE=now(date to begin rescanning for historical wallet transactions in
YYYY-MM-DDformat. rescan is disabled by default.)
BITCOIND_WALLET=ez-bwt(bitcoind wallet to use)
GAP_LIMIT=300(the gap limit for tracking derived addresses)
FORCE_RESCAN=0(force rescanning for historical transactions, even if the addresses were already previously imported)
HTTP_CORS=<none>(allowed cross-origins for the http api server)
WEBHOOK_URLS=<none>(URLs to notify with real-time wallet events)
AUTH_TOKEN=<none>(enable authentication with the specified token)
BWT_LOGS=1(display bwt's logs in the
The full list of BWT's config options is available here.
/data/track-addresses.txt(optional file with standalone addresses to track)
🗺️ BTC RPC Explorer
Automatically connects with the BWT Electrum server, to enable exploration of your wallet addresses (but not of arbitrary addresses).
When pruning is enabled or if
txindex is disabled (the default), some functionality will be limited:
- Pruned blocks will display basic header information, without the list of transactions.
- Transactions in pruned blocks will not be available, unless they're wallet-related.
- The address and amount of previous transaction outputs will not be shown, only the
- Mining fees will only be shown for unconfirmed transactions.
- You will only be able to search for wallet, mempool and recently confirmed transactions by their
txid. Searching for non-wallet transactions that were confirmed over 3 blocks ago is only possible if you provide the confirmed block height in addition to the
<txid>@<height>in the search box.
To enable full block explorer functionality, set
EXPLORER=1(enabled by default, set to
0to turn off)
EXPLORER_LOGS=0(display btc-rpc-explorer's logs in the
Plus all of btc-rpc-explorer's options.
👻 Specter Desktop
Specter Desktop is a wallet GUI for Bitcoin Core with a focus on hardware and multi-sig setups.
SPECTER=1 to enable and access using a web browser (e.g. http://ez:25441 if the
ez host alias is setup).
For your security, using a separate browser profile without extensions is highly recommended.
Using Specter with USB hardware wallets requires setting up udev rules on the host and starting docker with
--device /dev/<usb-device-id>. If you're unsure what the device id is, you could also (less ideally) use
--privileged -v /dev:/dev to give the container full access to all host devices.
SPECTER=0(disabled by default, set to
SPECTER_LOGS=0(display spectr's logs in the
AUTH_TOKEN=<none>(sets the password for the admin account)
Additional configuration options are available through Specter's web interface.
/data/specter(wallets, devices and other configuration)