Changeset View
Changeset View
Standalone View
Standalone View
doc/files.md
# Bitcoin ABC file system | |||||
**Contents** | |||||
- [Data directory location](#data-directory-location) | |||||
- [Data directory layout](#data-directory-layout) | |||||
- [Multi-wallet environment](#multi-wallet-environment) | |||||
- [GUI settings](#gui-settings) | |||||
- [Legacy subdirectories and files](#legacy-subdirectories-and-files) | |||||
- [Notes](#notes) | |||||
## Data directory location | |||||
The data directory is the default location where the Bitcoin ABC files are stored. | |||||
1. The default data directory paths for supported platforms are: | |||||
Platform | Data directory path | |||||
---------|-------------------- | |||||
Linux | `$HOME/.bitcoin/` | |||||
macOS | `$HOME/Library/Application Support/Bitcoin/` | |||||
Windows | `%APPDATA%\Bitcoin\` <sup>[\[1\]](#note1)</sup> | |||||
2. The non-default data directory path can be specified by `-datadir` option. | |||||
3. All content of the data directory, except for `bitcoin.conf` file, is chain-specific. This means the actual data directory paths for non-mainnet cases differ: | |||||
Chain option | Data directory path | |||||
--------------------|-------------------- | |||||
no option (mainnet) | *path_to_datadir*`/` | |||||
`-testnet` | *path_to_datadir*`/testnet3/` | |||||
`-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`<sup>[\[2\]](#note2)</sup> | Actual Bitcoin blocks (in network format, dumped in raw on disk, 128 MiB per file) | |||||
`blocks/` | `revNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Block undo data (custom format) | |||||
`chainstate/` | LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs and some metadata about the transactions they are from) | |||||
`indexes/txindex/` | LevelDB database | Transaction index; *optional*, used if `-txindex=1` | |||||
`wallets/` | | [Contains wallets](#multi-wallet-environment); can be specified by `-walletdir` option; if `wallets/` subdirectory does not exist, a wallet resides in the data directory | |||||
`./` | `banlist.dat` | Stores the IPs/subnets of banned nodes | |||||
`./` | `bitcoin.conf` | Contains [configuration settings](bitcoin-conf.md) for `bitcoind` or `bitcoin-qt`; 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 | |||||
`./` | `guisettings.ini.bak` | Backup of former [GUI settings](#gui-settings) after `-resetguisettings` option is used | |||||
`./` | `mempool.dat` | Dump of the mempool's transactions | |||||
`./` | `onion_private_key` | Cached Tor hidden service private key for `-listenonion` option | |||||
`./` | `peers.dat` | Peer IP address database (custom format) | |||||
`./` | `.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 Berkeley DB (BDB) databases: | |||||
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 (BDB) with keys and transactions | |||||
`./` | `.walletlock` | Wallet lock file | |||||
1. Each user-defined wallet named "wallet_name" resides in `wallets/wallet_name/` subdirectory. | |||||
2. The default (unnamed) wallet resides in `wallets/` subdirectory; if the latter does not exist, the wallet resides in the data directory. | |||||
3. A wallet database path can be specified by `-wallet` option. | |||||
## GUI settings | |||||
`bitcoin-qt` uses [`QSettings`](https://doc.qt.io/qt-5/qsettings.html) class; this implies platform-specific [locations where application settings are stored](https://doc.qt.io/qt-5/qsettings.html#locations-where-application-settings-are-stored). | |||||
## Legacy subdirectories and files | |||||
These subdirectories and files are no longer used by the Bitcoin ABC: | |||||
Path | Description | Repository notes | |||||
---------------|-------------|----------------- | |||||
`blktree/` | Blockchain index; replaced by `blocks/index/` in [0.8.0](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.8.0.md#improvements) | [PR #2231](https://github.com/bitcoin/bitcoin/pull/2231), [`8fdc94cc`](https://github.com/bitcoin/bitcoin/commit/8fdc94cc8f0341e96b1edb3a5b56811c0b20bd15) | |||||
`coins/` | Unspent transaction output database; replaced by `chainstate/` in 0.8.0 | [PR #2231](https://github.com/bitcoin/bitcoin/pull/2231), [`8fdc94cc`](https://github.com/bitcoin/bitcoin/commit/8fdc94cc8f0341e96b1edb3a5b56811c0b20bd15) | |||||
`blkindex.dat` | Blockchain index BDB database; replaced by {`chainstate/`, `blocks/index/`, `blocks/revNNNNN.dat`<sup>[\[2\]](#note2)</sup>} in 0.8.0 | [PR #1677](https://github.com/bitcoin/bitcoin/pull/1677) | |||||
`blk000?.dat` | Block data (custom format, 2 GiB per file); replaced by `blocks/blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> in 0.8.0 | [PR #1677](https://github.com/bitcoin/bitcoin/pull/1677) | |||||
`addr.dat` | Peer IP address BDB database; replaced by `peers.dat` in [0.7.0](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.7.0.md) | [PR #1198](https://github.com/bitcoin/bitcoin/pull/1198), [`928d3a01`](https://github.com/bitcoin/bitcoin/commit/928d3a011cc66c7f907c4d053f674ea77dc611cc) | |||||
## Notes | |||||
<a name="note1">1</a>. The `/` (slash, U+002F) is used as the platform-independent path component separator in this paper. | |||||
<a name="note2">2</a>. `NNNNN` matches `[0-9]{5}` regex. | |||||
* banlist.dat: stores the IPs/Subnets of banned nodes | |||||
* bitcoin.conf: contains configuration settings for bitcoind or bitcoin-qt | |||||
* bitcoind.pid: stores the process id of bitcoind while running | |||||
* blocks/blk000??.dat: block data (custom, 128 MiB per file); since 0.8.0 | |||||
* blocks/rev000??.dat; block undo data (custom); since 0.8.0 (format changed since pre-0.8) | |||||
* blocks/index/*; block index (LevelDB); since 0.8.0 | |||||
* chainstate/*; block chain state database (LevelDB); since 0.8.0 | |||||
* database/*: BDB database environment; only used for wallet since 0.8.0; moved to wallets/ directory on new installs since 0.18.7 | |||||
* db.log: wallet database log file; moved to wallets/ directory on new installs since 0.18.7 | |||||
* debug.log: contains debug information and general logging generated by bitcoind or bitcoin-qt | |||||
* indexes/txindex/*: optional transaction index database (LevelDB); since 0.19.7 | |||||
* mempool.dat: dump of the mempool's transactions; since 0.14.0. | |||||
* peers.dat: peer IP address database (custom format); since 0.7.0 | |||||
* wallet.dat: personal wallet (BDB) with keys and transactions; moved to wallets/ directory on new installs since 0.18.7 | |||||
* wallets/database/*: BDB database environment; used for wallets since 0.18.7 | |||||
* wallets/db.log: wallet database log file; since 0.18.7 | |||||
* wallets/wallet.dat: personal wallet (BDB) with keys and transactions; since 0.18.7 | |||||
* .cookie: session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0 | |||||
* onion_private_key: cached Tor hidden service private key for `-listenonion`: since 0.12.0 | |||||
* guisettings.ini.bak: backup of former GUI settings after `-resetguisettings` is used | |||||
Only used in pre-0.8.0 | |||||
--------------------- | |||||
* blktree/*; block chain index (LevelDB); since pre-0.8, replaced by blocks/index/* in 0.8.0 | |||||
* coins/*; unspent transaction output database (LevelDB); since pre-0.8, replaced by chainstate/* in 0.8.0 | |||||
Only used before 0.8.0 | |||||
--------------------- | |||||
* blkindex.dat: block chain index database (BDB); replaced by {chainstate/*,blocks/index/*,blocks/rev000??.dat} in 0.8.0 | |||||
* blk000?.dat: block data (custom, 2 GiB per file); replaced by blocks/blk000??.dat in 0.8.0 | |||||
Only used before 0.7.0 | |||||
--------------------- | |||||
* addr.dat: peer IP address database (BDB); replaced by peers.dat in 0.7.0 |