assumeutxo.md
1 # Assumeutxo Usage 2 3 Assumeutxo is a feature that allows fast bootstrapping of a validating bitcoind 4 instance. 5 6 For notes on the design of Assumeutxo, please refer to [the design doc](/doc/design/assumeutxo.md). 7 8 ## Loading a snapshot 9 10 There is currently no canonical source for snapshots, but any downloaded snapshot 11 will be checked against a hash that's been hardcoded in source code. If there is 12 no source for the snapshot you need, you can generate it yourself using 13 `dumptxoutset` on another node that is already synced (see 14 [Generating a snapshot](#generating-a-snapshot)). 15 16 Once you've obtained the snapshot, you can use the RPC command `loadtxoutset` to 17 load it. 18 19 ``` 20 $ bitcoin-cli -rpcclienttimeout=0 loadtxoutset /path/to/input 21 ``` 22 23 After the snapshot has loaded, the syncing process of both the snapshot chain 24 and the background IBD chain can be monitored with the `getchainstates` RPC. 25 26 ### Pruning 27 28 A pruned node can load a snapshot. To save space, it's possible to delete the 29 snapshot file as soon as `loadtxoutset` finishes. 30 31 The minimum `-prune` setting is 550 MiB, but this functionality ignores that 32 minimum and uses at least 1100 MiB. 33 34 As the background sync continues there will be temporarily two chainstate 35 directories, each multiple gigabytes in size (likely growing larger than the 36 downloaded snapshot). 37 38 ### Indexes 39 40 Indexes work but don't take advantage of this feature. They always start building 41 from the genesis block and can only apply blocks in order. Once the background 42 validation reaches the snapshot block, indexes will continue to build all the 43 way to the tip. 44 45 46 For indexes that support pruning, note that these indexes only allow blocks that 47 were already indexed to be pruned. Blocks that are not indexed yet will also 48 not be pruned. 49 50 This means that, if the snapshot is old, then a lot of blocks after the snapshot 51 block will need to be downloaded, and these blocks can't be pruned until they 52 are indexed, so they could consume a lot of disk space until indexing catches up 53 to the snapshot block. 54 55 ## Generating a snapshot 56 57 The RPC command `dumptxoutset` can be used to generate a snapshot for the current 58 tip (using type "latest") or a recent height (using type "rollback"). A generated 59 snapshot from one node can then be loaded 60 on any other node. However, keep in mind that the snapshot hash needs to be 61 listed in the chainparams to make it usable. If there is no snapshot hash for 62 the height you have chosen already, you will need to change the code there and 63 re-compile. 64 65 Using the type parameter "rollback", `dumptxoutset` can also be used to verify the 66 hardcoded snapshot hash in the source code by regenerating the snapshot and 67 comparing the hash. 68 69 Example usage: 70 71 ``` 72 $ bitcoin-cli -rpcclienttimeout=0 dumptxoutset /path/to/output rollback 73 ``` 74 75 For most of the duration of `dumptxoutset` running the node is in a temporary 76 state that does not actually reflect reality, i.e. blocks are marked invalid 77 although we know they are not invalid. Because of this it is discouraged to 78 interact with the node in any other way during this time to avoid inconsistent 79 results and race conditions, particularly RPCs that interact with blockstorage. 80 This inconsistent state is also why network activity is temporarily disabled, 81 causing us to disconnect from all peers. 82 83 `dumptxoutset` takes some time to complete, independent of hardware and 84 what parameter is chosen. Because of that it is recommended to increase the RPC 85 client timeout value (use `-rpcclienttimeout=0` for no timeout).