mirrors/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-02-22 15:04:44 +01:00
Code Issues Projects Releases Wiki Activity

docs: update assumeutxo.md

Browse source 
Include notes about the `chainstate_snapshot` rename as well as
updates for the included code.
This commit is contained in:
James O'Beirne 2022-04-13 18:42:21 -04:00
parent 87a1108c81
commit 2b373fe49d
1 changed files with 29 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
doc/design/assumeutxo.md
View file

@ -3,9 +3,9 @@
Assumeutxo is a feature that allows fast bootstrapping of a validating bitcoind Assumeutxo is a feature that allows fast bootstrapping of a validating bitcoind
instance with a very similar security model to assumevalid. instance with a very similar security model to assumevalid.
The RPC commands `dumptxoutset` and `loadtxoutset` are used to respectively generate The RPC commands `dumptxoutset` and `loadtxoutset` (yet to be merged) are used to
and load UTXO snapshots. The utility script `./contrib/devtools/utxo_snapshot.sh` may respectively generate and load UTXO snapshots. The utility script
be of use. `./contrib/devtools/utxo_snapshot.sh` may be of use.
## General background ## General background
@ -22,10 +22,6 @@ be of use.
chainstate running asynchronously in the background. We also use this flag to control chainstate running asynchronously in the background. We also use this flag to control
which index entries are added to setBlockIndexCandidates during LoadBlockIndex(). which index entries are added to setBlockIndexCandidates during LoadBlockIndex().
- Indexing implementations via BaseIndex can no longer assume that indexation happens
sequentially, since background validation chainstates can submit BlockConnected
events out of order with the active chain.
- The concept of UTXO snapshots is treated as an implementation detail that lives - The concept of UTXO snapshots is treated as an implementation detail that lives
behind the ChainstateManager interface. The external presentation of the changes behind the ChainstateManager interface. The external presentation of the changes
required to facilitate the use of UTXO snapshots is the understanding that there are required to facilitate the use of UTXO snapshots is the understanding that there are
@ -76,9 +72,15 @@ original chainstate remains in use as active.
Once the snapshot chainstate is loaded and validated, it is promoted to active Once the snapshot chainstate is loaded and validated, it is promoted to active
chainstate and a sync to tip begins. A new chainstate directory is created in the chainstate and a sync to tip begins. A new chainstate directory is created in the
datadir for the snapshot chainstate called `chainstate_snapshot`. When this directory datadir for the snapshot chainstate called `chainstate_snapshot`.
is present in the datadir, the snapshot chainstate will be detected and loaded as
active on node startup (via `DetectSnapshotChainstate()`). When this directory is present in the datadir, the snapshot chainstate will be detected
and loaded as active on node startup (via `DetectSnapshotChainstate()`).
A special file is created within that directory, `base_blockhash`, which contains the
serialized `uint256` of the base block of the snapshot. This is used to reinitialize
the snapshot chainstate on subsequent inits. Otherwise, the directory is a normal
leveldb database.
| | | | | |
| ---------- | ----------- | | ---------- | ----------- |
@ -88,7 +90,7 @@ active on node startup (via `DetectSnapshotChainstate()`).
The snapshot begins to sync to tip from its base block, technically in parallel with The snapshot begins to sync to tip from its base block, technically in parallel with
the original chainstate, but it is given priority during block download and is the original chainstate, but it is given priority during block download and is
allocated most of the cache (see `MaybeRebalanceCaches()` and usages) as our chief allocated most of the cache (see `MaybeRebalanceCaches()` and usages) as our chief
consideration is getting to network tip. goal is getting to network tip.
**Failure consideration:** if shutdown happens at any point during this phase, both **Failure consideration:** if shutdown happens at any point during this phase, both
chainstates will be detected during the next init and the process will resume. chainstates will be detected during the next init and the process will resume.
@ -107,33 +109,32 @@ sequentially.
### Background chainstate hits snapshot base block ### Background chainstate hits snapshot base block
Once the tip of the background chainstate hits the base block of the snapshot Once the tip of the background chainstate hits the base block of the snapshot
chainstate, we stop use of the background chainstate by setting `m_disabled` (not yet chainstate, we stop use of the background chainstate by setting `m_disabled`, in
committed - see #15606), in `CompleteSnapshotValidation()`, which is checked in `CompleteSnapshotValidation()`, which is checked in `ActivateBestChain()`). We hash the
`ActivateBestChain()`). We hash the background chainstate's UTXO set contents and background chainstate's UTXO set contents and ensure it matches the compiled value in
ensure it matches the compiled value in `CMainParams::m_assumeutxo_data`. `CMainParams::m_assumeutxo_data`.
The background chainstate data lingers on disk until shutdown, when in
`ChainstateManager::Reset()`, the background chainstate is cleaned up with
`ValidatedSnapshotShutdownCleanup()`, which renames the `chainstate_[hash]` datadir as
`chainstate`.
| | | | | |
| ---------- | ----------- | | ---------- | ----------- |
| number of chainstates | 2 (ibd has `m_disabled=true`) | | number of chainstates | 2 (ibd has `m_disabled=true`) |
| active chainstate | snapshot | | active chainstate | snapshot |
**Failure consideration:** if bitcoind unexpectedly halts after `m_disabled` is set on The background chainstate data lingers on disk until the program is restarted.
the background chainstate but before `CompleteSnapshotValidation()` can finish, the
need to complete snapshot validation will be detected on subsequent init by
`ChainstateManager::CheckForUncleanShutdown()`.
### Bitcoind restarts sometime after snapshot validation has completed ### Bitcoind restarts sometime after snapshot validation has completed
When bitcoind initializes again, what began as the snapshot chainstate is now After a shutdown and subsequent restart, `LoadChainstate()` cleans up the background
indistinguishable from a chainstate that has been built from the traditional IBD chainstate with `ValidatedSnapshotCleanup()`, which renames the `chainstate_snapshot`
process, and will be initialized as such. datadir as `chainstate` and removes the now unnecessary background chainstate data.
| | | | | |
| ---------- | ----------- | | ---------- | ----------- |
| number of chainstates | 1 | | number of chainstates | 1 |
| active chainstate | ibd | | active chainstate | ibd (was snapshot, but is now fully validated) |
What began as the snapshot chainstate is now indistinguishable from a chainstate that
has been built from the traditional IBD process, and will be initialized as such.
A file will be left in `chainstate/base_blockhash`, which indicates that the
chainstate, even though now fully validated, was originally started from a snapshot
with the corresponding base blockhash.