Full and archive nodes (#293)

* Difference between full node and archive node Include a section (in Pruning.md) about the difference between the two nodes and how to run them. Misc changes to the various pruning options and sync mode options. Signed-off-by: grantnoble <[email protected]> * Fix two self-induced markdown lint errors. Signed-off-by: grantnoble <[email protected]> * Fix incorrect link to CLI-Syntax.md Signed-off-by: grantnoble <[email protected]> * Updates based on @MadelineMurray feedback Included a "Fast Synchronization" section in Pruning.md Signed-off-by: grantnoble <[email protected]> * Updates to Full/Archive node details based on dev feedback Specifically: - Archive node is full sync and not pruned - Full node is fast sync and pruned - Pruning is default on for fast sync and off for full sync. Can turn pruning on/off explicitly if they so choose. - Full nodes have the current state, so can’t serve the network with any data request (i.e. balance of address X at block Y, where Y is old). You can guarantee the latest state for everything (and some older states, but not all). Signed-off-by: grantnoble <[email protected]> * Fixed broken links Signed-off-by: grantnoble <[email protected]> * Updates based on @NicolasMassart, @timbeiko, and @RatanRSur feedback Signed-off-by: grantnoble <[email protected]> * Some updated inadvertently missed in the last update. Signed-off-by: grantnoble <[email protected]>
hyperledger · Apr 4, 2020 · c67cdae · c67cdae
1 parent ce43a44
commit c67cdae
Show file tree

Hide file tree

Showing 4 changed files with 75 additions and 18 deletions.
diff --git a/docs/Concepts/Pruning.md b/docs/Concepts/Pruning.md
@@ -1,25 +1,66 @@
 ---
-description: Pruning
+description: Full and archive node types
 ---
 
-# Pruning
+# Full and archive node types
+
+Besu supports two node types, commonly referred to as _full nodes_ and _archive nodes_.
+
+Full nodes have the current state of the blockchain so cannot serve the network with all data
+requests (for example, the balance of an account as at an old block). Full nodes can guarantee the
+latest state for the blockchain (and some older states, but not all). You can check current
+balances, sign and send transactions, and look at current Dapp data.
+
+Archive nodes have all of this and they also store the intermediary state of every account and
+contract for every block since the genesis block. With an archive node you can do everything you
+do with a full node, as well as access historical state data.
+
+For Besu on MainNet, Archive nodes require significantly more disk space (approximately 3TB) than
+full nodes (approximately 750GB).
+
+!!! note
+
+    Besu running on other public testnets, such as Ropsten, and other Ethereum clients will have
+    different disk space requirements.
+
+To run an archive node, enable full synchronization using
+[`--sync-mode=FULL`](../Reference/CLI/CLI-Syntax.md#sync-mode), which by default also disables
+pruning ([`--pruning-enabled=false`](../Reference/CLI/CLI-Syntax.md#pruning-enabled)).
+
+To run a full node, enable fast synchronization using
+[`--sync-mode=FAST`](../Reference/CLI/CLI-Syntax.md#sync-mode), which by default also enables
+pruning ([`--pruning-enabled=true`](../Reference/CLI/CLI-Syntax.md#pruning-enabled)).
+
+## Fast synchronization
+
+Instead of a full synchronization ([`--sync-mode=FULL`](../Reference/CLI/CLI-Syntax.md#sync-mode)),
+which starts from the genesis block and reprocesses all transactions, fast synchronization
+([`--sync-mode=FAST`](../Reference/CLI/CLI-Syntax.md#sync-mode)) downloads the block headers and
+transaction receipts, and verifies the chain of block headers from the genesis block.
+
+!!! note
+
+    Fast synchronization enables pruning by default, but you can explicitly disable pruning
+    using [`--pruning-enabled=false`](../Reference/CLI/CLI-Syntax.md#pruning-enabled). Full
+    synchronization disables pruning by default.
+
+## Pruning
 
 !!! caution
+
     Do not use pruning in Hyperledger Besu v1.4.0. Pruning has a
     [known bug](https://github.com/hyperledger/besu/blob/master/CHANGELOG.md#known-issues).
 
-    If using fast sync in v1.4.0, explicitly disable pruning using
-    [`--pruning-enabled=false`](../Reference/CLI/CLI-Syntax.md#pruning-enabled).
+    If using fast synchronization
+    ([`--sync-mode=FAST`](../Reference/CLI/CLI-Syntax.md#sync-mode)) in v1.4.0, explicitly disable
+    pruning using [`--pruning-enabled=false`](../Reference/CLI/CLI-Syntax.md#pruning-enabled).
 
-Use pruning to reduce storage required for the world state. Pruning removes state trie nodes that
-are not required.
+In Besu, pruning reduces the storage required by removing state trie nodes that are unreachable
+from [recent blocks](../Reference/CLI/CLI-Syntax.md#pruning-blocks-retained).
 
 !!! Important
-    Using pruning with [private transactions](Privacy/Privacy-Overview.md) is not supported.
 
-Running a full sync to the Ethereum Mainnet with pruning enabled requires about 700GB of available
-disk space. To enable pruning, use the
-[`--pruning-enabled`](../Reference/CLI/CLI-Syntax.md#pruning-enabled) option.
+    Using pruning with [private transactions](Privacy/Privacy-Overview.md) is not supported.
 
 Pruning might increase block import times, but it does not affect the ability of nodes to stay in
 sync.
diff --git a/docs/HowTo/Get-Started/System-Requirements.md b/docs/HowTo/Get-Started/System-Requirements.md
@@ -50,12 +50,18 @@ to the chain head. Monitor your system to determine your actual JVM memory needs
     Do not use pruning in Hyperledger Besu v1.4.0. Pruning has a
     [known bug](https://github.com/hyperledger/besu/blob/master/CHANGELOG.md#known-issues).
 
-    If using fast sync in v1.4.0, explicitly disable pruning using
+    If using fast synchronization
+    ([`--sync-mode=FAST`](../../Reference/CLI/CLI-Syntax.md#sync-mode)) in v1.4.0, explicitly
+    disable pruning using
     [`--pruning-enabled=false`](../../Reference/CLI/CLI-Syntax.md#pruning-enabled).
 
-Syncing to the Ethereum Mainnet requires 3TB for a full sync. To reduce the disk space required,
-use [pruning](../../Concepts/Pruning.md). With pruning, we recommend approximately 750GB
-of available disk space.
+How you synchronize with the Ethereum MainNet and whether you
+[enable or disable pruning](../../Concepts/Pruning.md)) determines your disk space requirement.
+
+[Fast synchronization](../../Reference/CLI/CLI-Syntax.md#sync-mode), which enables
+[pruning](../../Concepts/Pruning.md) by default, requires approximately 750GB of disk space.
+[Full synchronization](../../Reference/CLI/CLI-Syntax.md#sync-mode), which disables
+[pruning](../../Concepts/Pruning.md) by default, requires approximately 3TB.
 
 ## VM requirements
 

diff --git a/docs/HowTo/Send-Transactions/Revert-Reason.md b/docs/HowTo/Send-Transactions/Revert-Reason.md
@@ -49,7 +49,8 @@ the revert reason as an ABI-encoded string.
     The revert reason is not included in the transactions receipts root hash. Not including the
     revert reason in the transactions receipts root hash means the revert reason is only available
     to nodes that execute the transaction when importing the block. That is, the revert reason is
-    not available if using fast sync.
+    not available if using fast synchronization
+    ([`--sync-mode=FAST`](../../Reference/CLI/CLI-Syntax.md#sync-mode)).
 
 !!! example
 

diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md
@@ -1422,7 +1422,9 @@ running.
     Do not use pruning in Hyperledger Besu v1.4.0. Pruning has a
     [known bug](https://github.com/hyperledger/besu/blob/master/CHANGELOG.md#known-issues).
 
-    If using fast sync in v1.4.0, explicitly disable pruning using `--pruning-enabled=false`.
+    If using fast synchronization
+    ([`--sync-mode=FAST`](#sync-mode)) in v1.4.0, explicitly disable pruning using
+    [`--pruning-enabled=false`](#pruning-enabled).
 
 ```bash tab="Syntax"
 --pruning-block-confirmations=<INTEGER>
@@ -1454,7 +1456,9 @@ nodes that cannot be pruned. The default is 10.
     Do not use pruning in Hyperledger Besu v1.4.0. Pruning has a
     [known bug](https://github.com/hyperledger/besu/blob/master/CHANGELOG.md#known-issues).
 
-    If using fast sync in v1.4.0, explicitly disable pruning using `--pruning-enabled=false`.
+    If using fast synchronization
+    ([`--sync-mode=FAST`](#sync-mode)) in v1.4.0, explicitly disable pruning using
+    [`--pruning-enabled=false`](#pruning-enabled).
 
 ```bash tab="Syntax"
 --pruning-blocks-retained=<INTEGER>
@@ -1485,7 +1489,9 @@ The minimum number of recent blocks to keep the entire world state for. The defa
     Do not use pruning in Hyperledger Besu v1.4.0. Pruning has a
     [known bug](https://github.com/hyperledger/besu/blob/master/CHANGELOG.md#known-issues).
 
-    If using fast sync in v1.4.0, explicitly disable pruning using `--pruning-enabled=false`.
+    If using fast synchronization
+    ([`--sync-mode=FAST`](#sync-mode)) in v1.4.0, explicitly disable pruning using
+    `--pruning-enabled=false`.
 
 ```bash tab="Syntax"
 --pruning-enabled
@@ -2130,6 +2136,9 @@ sync-mode="FAST"
 
 The synchronization mode. The options are `FAST` and `FULL`. The default is `FULL`.
 
+Full synchronization disables pruning ([`--pruning-enabled=false`](#pruning-enabled)) by default.
+Fast synchronization enables pruning ([`--pruning-enabled=true`](#pruning-enabled)) by default.
+
 !!! note
 
     If fast synchronization fails, usually because the node can't find enough valid peers, fast