From d23ef421bdcc9db3020cf710a74d9b205c7e8e5a Mon Sep 17 00:00:00 2001 From: Fabian Jahr Date: Sat, 16 Mar 2024 21:36:28 +0100 Subject: [PATCH] doc: Improve guide for usage of assumeutxo --- doc/assumeutxo.md | 66 ++++++++++++++++++++++++++++++++++++++++ doc/design/assumeutxo.md | 43 ++------------------------ src/rpc/blockchain.cpp | 3 +- 3 files changed, 70 insertions(+), 42 deletions(-) create mode 100644 doc/assumeutxo.md diff --git a/doc/assumeutxo.md b/doc/assumeutxo.md new file mode 100644 index 00000000000000..615c94f34656c7 --- /dev/null +++ b/doc/assumeutxo.md @@ -0,0 +1,66 @@ +# Assumeutxo Usage + +Assumeutxo is a feature that allows fast bootstrapping of a validating bitcoind +instance. + +For notes on the design of Assumeutxo, please refer to [the design doc](/doc/assumeutxo.md). + +## Loading a snapshot + +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)). + +Once you've obtained the snapshot, you can use the RPC command `loadtxoutset` to +load it. + +``` +$ bitcoin-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. + +The minimum `-prune` setting is 550 MiB, but this functionality ignores that +minimum and uses at least 1100 MiB. + +As the background sync continues there will be temporarily two chainstate +directories, each multiple gigabytes in size (likely growing larger than the +downloaded snapshot). + +### Indexes + +Indexes work but don't take advantage of this feature. They always start building +from the genesis block. Once the background validation reaches the snapshot block, +indexes will continue to build all the way to the tip. + +For indexes that support pruning, note that no pruning will take place between +the snapshot and the tip, until the background sync has completed - after which +everything is pruned. Depending on how old the snapshot is, this may temporarily +use a significant amount of disk space. + +## Generating a snapshot + +The RPC command `dumptxoutset` can be used to generate a snapshot for the current +tip or a recent height. 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. + +Using the height parameter, `dumptxoutset` can also be used to verify the +hardcoded snapshot hash in the source code by regenerating the snapshot and +comparing the hash. + +Example usage (with testnet height): + +``` +$ bitcoin-cli dumptxoutset /path/to/output 2500000 +``` diff --git a/doc/design/assumeutxo.md b/doc/design/assumeutxo.md index 91bc96b57f6d4a..e835fecd6962ec 100644 --- a/doc/design/assumeutxo.md +++ b/doc/design/assumeutxo.md @@ -1,45 +1,6 @@ -# assumeutxo +# Assumeutxo Design -Assumeutxo is a feature that allows fast bootstrapping of a validating bitcoind -instance. - -## Loading a snapshot - -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. - -Once you've obtained the snapshot, you can use the RPC command `loadtxoutset` to -load it. - -### Pruning - -A pruned node can load a snapshot. To save space, it's possible to delete the -snapshot file as soon as `loadtxoutset` finishes. - -The minimum `-prune` setting is 550 MiB, but this functionality ignores that -minimum and uses at least 1100 MiB. - -As the background sync continues there will be temporarily two chainstate -directories, each multiple gigabytes in size (likely growing larger than the -downloaded snapshot). - -### Indexes - -Indexes work but don't take advantage of this feature. They always start building -from the genesis block. Once the background validation reaches the snapshot block, -indexes will continue to build all the way to the tip. - -For indexes that support pruning, note that no pruning will take place between -the snapshot and the tip, until the background sync has completed - after which -everything is pruned. Depending on how old the snapshot is, this may temporarily -use a significant amount of disk space. - -## Generating a snapshot - -The RPC command `dumptxoutset` can be used to generate a snapshot for the current -tip or a recent height. This can be used -to create a snapshot on one node that you wish to load on another node. -It can also be used to verify the hardcoded snapshot hash in the source code. +For notes on the usage of Assumeutxo, please refer to [the usage doc](/doc/assumeutxo.md). ## General background diff --git a/src/rpc/blockchain.cpp b/src/rpc/blockchain.cpp index 32d0226bb06ab3..7e42592ff013bf 100644 --- a/src/rpc/blockchain.cpp +++ b/src/rpc/blockchain.cpp @@ -2672,7 +2672,8 @@ static RPCHelpMan dumptxoutset() { return RPCHelpMan{ "dumptxoutset", - "Write the serialized UTXO set to a file.", + "Write the serialized UTXO set to a file. This can be used in loadtxoutset afterwards if this snapshot height is supported in the chainparams as well.\n\n" + "Unless the requested height is the current tip, the node will roll back to the requested height and network activity will be suspended during this process.", { {"path", RPCArg::Type::STR, RPCArg::Optional::NO, "Path to the output file. If relative, will be prefixed by datadir."}, {"height", RPCArg::Type::NUM, RPCArg::DefaultHint{"the latest valid snapshot height"},