update documentation in pruning/README.md and snapshots/README.md

pruning/README.md

@@ -0,0 +1,29 @@
+# Pruning
+
+## Overview
+
+Pruning is the mechanism for deleting old heights from the disk. Depending on the use case,
+nodes may require different pruning strategies. For example, archive nodes must keep all
+the states and prune nothing. On the other hand, a regular validator node may want to only keep 100 latest heights for performance reasons.
+
+## Strategies
+
+The strategies are configured in `app.toml`:
+pruning = "< strategy >" # where the options are:
+- `default`: only the last 100,000 states(approximately 1 week worth of state) are kept; pruning at 100 block intervals
+- `nothing`: all historic states will be saved, nothing will be deleted (i.e. archiving node)
+- `everything`: 10 latest states will be kept; pruning at 10 block intervals.
+- `custom`: allow pruning options to be manually specified through 'pruning-keep-recent', and 'pruning-interval'
+
+If no strategy is given to `Baseapp`, `nothing` is selected. However, we perform validation on the cli layer to require these to be always set in the config file.
+
+## Custom Pruning
+
+These are applied if and only if the pruning strategy is custom:
+- `pruning-keep-recent`: N means to keep all of the last N states
+- `pruning-interval`: N means to delete old states from disk every Nth block.
+
+## Relationship to Snapshots
+
+Snapshot settings are optional. However, if set, they have an effect on how pruning is done by
+persisting the heights that are multiples of `state-sync.snapshot-interval` until after the snapshot is complete. See the "Relationship to Pruning" section in `snapshots/README.md` for more details.

server/config/toml.go

@@ -22,7 +22,7 @@ minimum-gas-prices = "{{ .BaseConfig.MinGasPrices }}"
 
 # default: only the last 100,000 states(approximately 1 week worth of state) are kept; pruning at 100 block intervals
 # nothing: all historic states will be saved, nothing will be deleted (i.e. archiving node)
-# everything: all saved states will be deleted, storing only the current state; pruning at 10 block intervals.
+# everything: 10 latest states will be kept; pruning at 10 block intervals.
 # custom: allow pruning options to be manually specified through 'pruning-keep-recent', and 'pruning-interval'
 pruning = "{{ .BaseConfig.Pruning }}"
 

snapshots/README.md

@@ -49,9 +49,9 @@ can be trivially forged by an adversary. This was considered out of scope for
 the initial implementation, but can be added later without changes to the
 ABCI state sync protocol.
 
-## Relationship to pruning
+## Relationship to Pruning
 
-Snapshot settings are optional. However, if set, they have an effect on how pruning is going to be done by
+Snapshot settings are optional. However, if set, they have an effect on how pruning is done by
 persisting the heights that are multiples of `state-sync.snapshot-interval` until after the snapshot is complete.
 
 If pruning is enabled (not `pruning = "nothing"`), we avoid pruning heights that are multiples of