mirror of
https://github.com/dashpay/dash.git
synced 2024-12-26 04:22:55 +01:00
460ed06315
c1e07423083cd2a7e3f2b28f69a573ea1837af4d doc: Warn about wallet.dat re-use and backups (Albert) Pull request description: Following discussion in #18205, this PR adds a warning against re-use of the same wallet file on two different nodes, as that can cause problems due to race conditions between nodes (eg: both nodes using the same addresses at the same time for different things because they are not aware of the other node). I've also included the rationale behind the warning but I've kept it short to make it clearer to users, not sure if I should have written a longer explanation instead. Also, while this PR may help some users avoid problems, the changes are largely inconsequential, so feel free to close it if it's not worth the effort. On an unrelated note, I've also set up [this site](https://corollari.github.io/bitcoin-core-docs/), which periodically pulls bitcoin core and turns its docs into a webpage. Browsing the docs can also be done locally or on github, so this doesn't add much value, but I personally find that more comfortable and it makes them more searchable. Top commit has no ACKs. Tree-SHA512: 5ce06026176917304932714470be8c3410d35698f925875b0955ecd3b1756ef52793feb469dd4bdac4921f1a24daf59001e9911f1f096f559fb28c250baae378
113 lines
7.7 KiB
Markdown
113 lines
7.7 KiB
Markdown
# Dash Core 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 Dash Core files are stored.
|
|
|
|
1. The default data directory paths for supported platforms are:
|
|
|
|
Platform | Data directory path
|
|
---------|--------------------
|
|
Linux | `$HOME/.dashcore/`
|
|
macOS | `$HOME/Library/Application Support/Dashcore/`
|
|
Windows | `%APPDATA%\Dashcore\` <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 `dash.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 Dash 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`
|
|
`indexes/blockfilter/basic/db/` | LevelDB database | Blockfilter index LevelDB database for the basic filtertype; *optional*, used if `-blockfilterindex=basic`
|
|
`indexes/blockfilter/basic/` | `fltrNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Blockfilter index filters for the basic filtertype; *optional*, used if `-blockfilterindex=basic`
|
|
`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
|
|
`evodb/` | |special txes and quorums database
|
|
`llmq/` | |quorum signatures database
|
|
`./` | `banlist.dat` | Stores the IPs/subnets of banned nodes
|
|
`./` | `dash.conf` | User-defined [configuration settings](dash-conf.md) for `dashd` or `dash-qt`. File is not written to by the software and must be created manually. Path can be specified by `-conf` option
|
|
`./` | `dashd.pid` | Stores the process ID (PID) of `dashd` or `dash-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 `dashd` or `dash-qt`; can be specified by `-debuglogfile` option
|
|
`./` | `governance.dat` | stores data for governance objects
|
|
`./` | `mncache.dat` | stores data for masternode list
|
|
`./` | `netfulfilled.dat` | stores data about recently made network requests
|
|
`./` | `fee_estimates.dat` | Stores statistics used to estimate minimum transaction fees and priorities required for confirmation
|
|
`./` | `guisettings.ini.bak` | Backup of former [GUI settings](#gui-settings) after `-resetguisettings` option is used
|
|
`./` | `mempool.dat` | Dump of the mempool's transactions
|
|
`./` | `onion_v3_private_key` | Cached Tor hidden service private key for `-listenonion` option
|
|
`./` | `peers.dat` | Peer IP address database (custom format)
|
|
`./` | `settings.json` | Read-write settings set through GUI or RPC interfaces, augmenting manual settings from [dash.conf](dash-conf.md). 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 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.
|
|
|
|
4. `wallet.dat` files must not be shared across different node instances, as that can result in key-reuse and double-spends due the lack of synchronization between instances.
|
|
|
|
5. Any copy or backup of the wallet should be done through a `backupwallet` call in order to update and lock the wallet, preventing any file corruption caused by updates during the copy.
|
|
|
|
## GUI settings
|
|
|
|
`dash-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 Dash Core:
|
|
|
|
Path | Description | Repository notes
|
|
---------------|-------------|-----------------
|
|
`blktree/` | Blockchain index; replaced by `blocks/index/` in [0.8.0](https://github.com/dash/dash/blob/master/doc/release-notes/release-notes-0.8.0.md#improvements) | [PR #2231](https://github.com/dash/dash/pull/2231), [`8fdc94cc`](https://github.com/dash/dash/commit/8fdc94cc8f0341e96b1edb3a5b56811c0b20bd15)
|
|
`coins/` | Unspent transaction output database; replaced by `chainstate/` in 0.8.0 | [PR #2231](https://github.com/dash/dash/pull/2231), [`8fdc94cc`](https://github.com/dash/dash/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/dash/dash/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/dash/dash/pull/1677)
|
|
`addr.dat` | Peer IP address BDB database; replaced by `peers.dat` in [0.7.0](https://github.com/dash/dash/blob/master/doc/release-notes/release-notes-0.7.0.md) | [PR #1198](https://github.com/dash/dash/pull/1198), [`928d3a01`](https://github.com/dash/dash/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.
|
|
|