backport: assumeutxo M7 — params polish and docs rewrite (series complete)

doc/assumeutxo.md

@@ -1,85 +1,107 @@
-# Assumeutxo Usage
+# Using Assumeutxo
 
-Assumeutxo is a feature that allows fast bootstrapping of a validating dashd
-instance.
+Assumeutxo can make a new Dash Core node usable quickly by loading a recent
+chainstate snapshot. The node syncs forward from the snapshot immediately and,
+at the same time, validates every block from genesis in the background. For
+implementation details, see the [design document](/doc/design/assumeutxo.md).
 
-For notes on the design of Assumeutxo, please refer to [the design doc](/doc/design/assumeutxo.md).
+## Availability and trust
 
-## Loading a snapshot
+There is currently no canonical snapshot distribution service and this tree
+has no mainnet or testnet snapshot parameters. Built-in snapshots and the
+`-assumeutxodata` option are for regtest only until release builders generate
+and review production parameters.
 
-There is currently no canonical source for snapshots, but any downloaded snapshot
-will be checked against a hash that's been hardcoded in source code. If there is
-no source for the snapshot you need, you can generate it yourself using
-`dumptxoutset` on another node that is already synced (see
-[Generating a snapshot](#generating-a-snapshot)).
+A snapshot may be transported by an untrusted third party. For production
+parameters, Dash Core accepts it only when its network and base block match an
+authorized entry and both its UTXO hash and Dash evo-state hash match the
+hardcoded values. (Two built-in legacy regtest fixtures retain a test-only null
+evo-hash wildcard.) Dash Core also
+cross-checks the deterministic masternode list, quorum commitments, and credit
+pool against commitments in the base block's CbTx. Background validation then
+re-derives the UTXO set and canonical masternode state from genesis before the
+snapshot is considered fully validated.
 
-Once you've obtained the snapshot, you can use the RPC command `loadtxoutset` to
-load it.
+## Obtain or create a snapshot
 
-```
-$ dash-cli loadtxoutset /path/to/input
-```
-
-After the snapshot has loaded, the syncing process of both the snapshot chain
-and the background IBD chain can be monitored with the `getchainstates` RPC.
-
-### Pruning
-
-A pruned node can load a snapshot. To save space, it's possible to delete the
-snapshot file as soon as `loadtxoutset` finishes.
+Obtain a snapshot for an authorized base height from a source you choose, or
+create one on a normally synced node with `dumptxoutset`. A current-tip dump is:
 
-The minimum `-prune` setting is 550 MiB, but this functionality ignores that
-minimum and uses at least 1100 MiB.
+```text
+dash-cli -rpcclienttimeout=0 dumptxoutset /path/to/utxo.dat latest
+```
 
-As the background sync continues there will be temporarily two chainstate
-directories, each multiple gigabytes in size (likely growing larger than the
-downloaded snapshot).
+To dump a particular recent height (or block hash), temporarily roll the node
+back while writing the snapshot:
 
-### Indexes
+```text
+dash-cli -rpcclienttimeout=0 -named dumptxoutset /path/to/utxo.dat rollback=HEIGHT
+```
 
-Indexes work but don't take advantage of this feature. They always start building
-from the genesis block and can only apply blocks in order. Once the background
-validation reaches the snapshot block, indexes will continue to build all the
-way to the tip.
+The positional form `dumptxoutset /path/to/utxo.dat rollback` selects the
+latest base already authorized in chain parameters. A rollback dump requires
+all intervening block and undo data, so it can fail on a pruned node. Network
+activity is suspended and peers are disconnected during rollback; avoid other
+block-storage RPCs until the command finishes. The original tip is reconsidered
+after the dump. Use an unlimited or long RPC timeout because hashing and evo
+snapshot construction can take several minutes.
 
+The result includes `base_hash`, `base_height`, `txoutset_hash`, `evo_hash`,
+`nchaintx`, and the written path. Operators can reproduce an authorized dump at
+the same base and compare both hashes. Creating a dump at an arbitrary height
+does not authorize it for loading; authorization is supplied by chain
+parameters (or, on regtest, an exact `-assumeutxodata` entry).
 
-For indexes that support pruning, note that these indexes only allow blocks that
-were already indexed to be pruned. Blocks that are not indexed yet will also
-not be pruned.
+## Load and monitor a snapshot
 
-This means that, if the snapshot is old, then a lot of blocks after the snapshot
-block will need to be downloaded, and these blocks can't be pruned until they
-are indexed, so they could consume a lot of disk space until indexing catches up
-to the snapshot block.
+Wait for the destination node to learn the base block header, ensure its
+mempool is empty, and load the file:
 
-## Generating a snapshot
+```text
+dash-cli loadtxoutset /path/to/utxo.dat
+```
 
-The RPC command `dumptxoutset` can be used to generate a snapshot for the current
-tip (using type "latest") or a recent height (using type "rollback"). A generated
-snapshot from one node can then be loaded
-on any other node. However, keep in mind that the snapshot hash needs to be
-listed in the chainparams to make it usable. If there is no snapshot hash for
-the height you have chosen already, you will need to change the code there and
-re-compile.
+Relative paths are resolved under the network data directory. On success the
+result reports `coins_loaded`, `tip_hash`, `base_height`, and `path`. The input
+file can then be removed; Dash Core has copied its state into
+`chainstate_snapshot` and EvoDB.
 
-Using the type parameter "rollback", `dumptxoutset` can also be used to verify the
-hardcoded snapshot hash in the source code by regenerating the snapshot and
-comparing the hash.
+`loadtxoutset` is unavailable when Dash Core is running in masternode mode.
+Stop using `-masternodeblsprivkey` and restart as a regular node before loading
+a snapshot. Quorum signing is also refused whenever an unvalidated snapshot is
+active.
 
-Example usage:
+Monitor progress with:
 
-```
-$ dash-cli -rpcclienttimeout=0 dumptxoutset /path/to/output rollback
+```text
+dash-cli getchainstates
 ```
 
-For most of the duration of `dumptxoutset` running the node is in a temporary
-state that does not actually reflect reality, i.e. blocks are marked invalid
-although we know they are not invalid. Because of this it is discouraged to
-interact with the node in any other way during this time to avoid inconsistent
-results and race conditions, particularly RPCs that interact with blockstorage.
-This inconsistent state is also why network activity is temporarily disabled,
-causing us to disconnect from all peers.
-
-`dumptxoutset` takes some time to complete, independent of hardware and
-what parameter is chosen. Because of that it is recommended to increase the RPC
-client timeout value (use `-rpcclienttimeout=0` for no timeout).
+During background validation, `chainstates` normally contains two entries. The
+active snapshot entry has `snapshot_blockhash` and `validated: false`; the
+historical entry advances from genesis. The snapshot chain syncs to the network
+tip first, so normal wallet and mempool use can begin before background
+validation finishes.
+
+When the historical entry reaches the snapshot base, Dash Core recomputes the
+UTXO hash, compares the canonical masternode list and required reconstruction
+history, and completes any CbTx/evo checks deferred until the base block was
+available. The active entry then reports `validated: true`. Cleanup and
+promotion are crash-safe and may finish on the next restart, after which only
+one normal chainstate remains.
+
+If any required hash or derived-state comparison fails, Dash Core invalidates
+the snapshot and shuts down rather than continuing on it. Follow the reported
+recovery instruction; a reindex may be required for an EvoDB inconsistency.
+
+## Disk use, pruning, and indexes
+
+A pruned node can use Assumeutxo, but dual-chainstate operation can temporarily
+exceed the configured prune budget. The minimum block-file allowance is needed
+for each chainstate, the snapshot base is retained until deferred checks
+complete, and index builders retain blocks they have not processed.
+
+Indexes still build sequentially from genesis; they do not begin at the
+snapshot base. Expect extra download time and disk use until background
+validation and indexes catch up. Two chainstate databases also remain on disk
+until validation succeeds and cleanup completes.