mirror of
https://github.com/bitcoin/bitcoin
synced 2025-10-06 06:02:59 +02:00
431a076ae6
The index originally stored cumulative values in a CAmount type but this allowed for potential overflow issues which were observed on Signet. Fix this by storing the values that are in danger of overflowing in a arith_uint256. Also turns an unnecessary copy into a reference in RevertBlock and CustomAppend and gets rid of the explicit total unspendable tracking which can be calculated by adding the four categories of unspendables together.
14 KiB
14 KiB
Bitcoin Core file system
Contents
Data directory location
The data directory is the default location where the Bitcoin Core files are stored.
- The default data directory paths for supported platforms are:
| Platform | Data directory path |
|---|---|
| Linux | $HOME/.bitcoin/ |
| macOS | $HOME/Library/Application Support/Bitcoin/ |
| Windows | %LOCALAPPDATA%\Bitcoin\ [1] |
-
A custom data directory path can be specified with the
-datadiroption. -
All content of the data directory, except for
bitcoin.conffile, is chain-specific. This means the actual data directory paths for non-mainnet cases differ:
| Chain option | Data directory path |
|---|---|
-chain=main (default) |
path_to_datadir/ |
-chain=test or -testnet |
path_to_datadir/testnet3/ |
-chain=testnet4 or -testnet4 |
path_to_datadir/testnet4/ |
-chain=signet or -signet |
path_to_datadir/signet/ |
-chain=regtest or -regtest |
path_to_datadir/regtest/ |
Data directory layout
| Subdirectory | File(s) | Description |
|---|---|---|
blocks/ |
Blocks directory; can be specified by -blocksdir option (except for blocks/index/) |
|
blocks/index/ |
LevelDB database | Block index; -blocksdir option does not affect this path |
blocks/ |
blkNNNNN.dat[2] |
Actual Bitcoin blocks (dumped in network format, 128 MiB per file) |
blocks/ |
revNNNNN.dat[2] |
Block undo data (custom format) |
blocks/ |
xor.dat |
Rolling XOR pattern for block and undo data files |
chainstate/ |
LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs (UTXOs) and metadata about the transactions they are from) |
indexes/txindex/ |
LevelDB database | Transaction index; optional, used if -txindex=1 |
indexes/blockfilter/basic/db/ |
LevelDB database | Blockfilter index LevelDB database for the basic filtertype; optional, used if -blockfilterindex=basic |
indexes/blockfilter/basic/ |
fltrNNNNN.dat[2] |
Blockfilter index filters for the basic filtertype; optional, used if -blockfilterindex=basic |
indexes/coinstatsindex/db/ |
LevelDB database | Coinstats index; optional, used if -coinstatsindex=1 |
wallets/ |
Contains wallets; can be specified by -walletdir option; if wallets/ subdirectory does not exist, wallets reside in the data directory |
|
./ |
anchors.dat |
Anchor IP address database, created on shutdown and deleted at startup. Anchors are last known outgoing block-relay-only peers that are tried to re-connect to on startup |
./ |
banlist.json |
Stores the addresses/subnets of banned nodes. |
./ |
bitcoin.conf |
User-defined configuration settings for bitcoind or bitcoin-qt. File is not written to by the software and must be created manually. Path can be specified by -conf option |
./ |
bitcoind.pid |
Stores the process ID (PID) of bitcoind or bitcoin-qt while running; created at start and deleted on shutdown; can be specified by -pid option |
./ |
debug.log |
Contains debug information and general logging generated by bitcoind or bitcoin-qt; can be specified by -debuglogfile option |
./ |
fee_estimates.dat |
Stores statistics used to estimate minimum transaction fees required for confirmation |
./ |
guisettings.ini.bak |
Backup of former GUI settings after -resetguisettings option is used |
./ |
ip_asn.map |
IP addresses to Autonomous System Numbers (ASNs) mapping used for bucketing of the peers; path can be specified with the -asmap option |
./ |
mempool.dat |
Dump of the mempool's transactions |
./ |
onion_v3_private_key |
Cached Tor onion service private key for -listenonion option |
./ |
i2p_private_key |
Private key that corresponds to our I2P address. When -i2psam= is specified the contents of this file is used to identify ourselves for making outgoing connections to I2P peers and possibly accepting incoming ones. Automatically generated if it does not exist. |
./ |
peers.dat |
Peer IP address database (custom format) |
./ |
settings.json |
Read-write settings set through GUI or RPC interfaces, augmenting manual settings from bitcoin.conf. File is created automatically if read-write settings storage is not disabled with -nosettings option. Path can be specified with -settings option |
./ |
.cookie |
Session RPC authentication cookie; if used, created at start and deleted on shutdown; can be specified by -rpccookiefile option |
./ |
.lock |
Data directory lock file |
Multi-wallet environment
Wallets are SQLite databases.
-
Each user-defined wallet named "wallet_name" resides in the
wallets/wallet_name/subdirectory. -
The default (unnamed) wallet resides in
wallets/subdirectory; if the latter does not exist, the wallet resides in the data directory. -
A wallet database path can be specified with the
-walletoption. -
wallet.datfiles must not be shared across different node instances, as that can result in key-reuse and double-spends due to the lack of synchronization between instances. -
Any copy or backup of the wallet should be done through a
backupwalletcall in order to update and lock the wallet, preventing any file corruption caused by updates during the copy.
SQLite database based wallets
| Subdirectory | File | Description |
|---|---|---|
./ |
wallet.dat |
Personal wallet (a SQLite database) with keys and transactions |
./ |
wallet.dat-journal |
SQLite Rollback Journal file for wallet.dat. Usually created at start and deleted on shutdown. A user must keep it as safe as the wallet.dat file. |
GUI settings
bitcoin-qt uses QSettings class; this implies platform-specific locations where application settings are stored.
Legacy subdirectories and files
These subdirectories and files are no longer used by Bitcoin Core:
| Path | Description | Repository notes |
|---|---|---|
banlist.dat |
Stores the addresses/subnets of banned nodes; superseded by banlist.json in 22.0 and completely ignored in 23.0 |
PR #20966, PR #22570 |
blktree/ |
Blockchain index; replaced by blocks/index/ in 0.8.0 |
PR #2231, 8fdc94cc |
coins/ |
Unspent transaction output database; replaced by chainstate/ in 0.8.0 |
PR #2231, 8fdc94cc |
blkindex.dat |
Blockchain index BDB database; replaced by {chainstate/, blocks/index/, blocks/revNNNNN.dat[2]} in 0.8.0 |
PR #1677 |
blk000?.dat |
Block data (custom format, 2 GiB per file); replaced by blocks/blkNNNNN.dat[2] in 0.8.0 |
PR #1677 |
addr.dat |
Peer IP address BDB database; replaced by peers.dat in 0.7.0 |
PR #1198, 928d3a01 |
onion_private_key |
Cached Tor onion service private key for -listenonion option. Was used for Tor v2 services; replaced by onion_v3_private_key in 0.21.0 |
PR #19954 |
Berkeley DB database based wallets
| Subdirectory | File(s) | Description |
|---|---|---|
database/ |
BDB logging files | Part of BDB environment; created at start and deleted on shutdown; a user must keep it as safe as personal wallet wallet.dat |
./ |
db.log |
BDB error file |
./ |
wallet.dat |
Personal wallet (a BDB database) with keys and transactions |
./ |
.walletlock |
BDB wallet lock file |
Notes
1. The / (slash, U+002F) is used as the platform-independent path component separator in this document.
2. NNNNN matches [0-9]{5} regex.
Installed Files
This table describes the files installed by Bitcoin Core across different platforms.
| Path | Description |
|---|---|
| README.md or readme.txt | Project information and instructions |
| bitcoin.conf | Generated configuration file |
| bin/bitcoin | Command-line tool for interacting with Bitcoin. Calls other binaries below. |
| bin/bitcoin-cli | Tool for making node and wallet RPC calls. |
| bin/bitcoin-qt | Bitcoin node and wallet GUI |
| bin/bitcoin-tx | Tool for creating and modifying transactions |
| bin/bitcoin-util | Miscellaneous utilities |
| bin/bitcoin-wallet | Bitcoin wallet tool |
| bin/bitcoind | Bitcoin node and wallet daemon |
| lib/libbitcoinkernel.so | Shared library containing core consensus and validation code |
| lib/pkgconfig/libbitcoinkernel.pc | Pkg-config metadata for linking to libbitcoinkernel |
| libexec/bench_bitcoin | Benchmarking tool for measuring node performance |
| libexec/bitcoin-chainstate | Tool to validate and connect blocks |
| libexec/bitcoin-gui | IPC-enabled alternative to bitcoin-qt |
| libexec/bitcoin-node | IPC-enabled alternative to bitcoind |
| libexec/test_bitcoin | Unit test binary |
| libexec/test_bitcoin-qt | GUI-specific unit tests |
| share/man/man1/ | Man pages for command-line tools like bitcoin-cli, bitcoind, and others |
| share/rpcauth/ | Documentation and scripts for RPC authentication setup |
Notes
- Italicized files are only installed in source builds if relevant CMake options are enabled. They are not included in binary releases.
- README and bitcoin.conf files are included in binary releases but not installed in source builds.
- On Windows, binaries have a
.exesuffix (e.g.,bitcoin-cli.exe).
Filesystem recommendations
When choosing a filesystem for the data directory (datadir) or blocks directory (blocksdir) on macOS,the exFAT filesystem should be avoided.
There have been multiple reports of database corruption and data loss when using this filesystem with Bitcoin Core, see Issue #31454 for more details.