docs: describe behavior without duplicating defaults; rolling pruning reclaims in background

Author: svlachakis

docs/fundamentals/archive-nodes.md

@@ -22,10 +22,10 @@ Two independent groups of configuration options compose:
 |---|---|---|---|---|
 | [`FlatDb.Enabled`](./configuration.md#flatdb-enabled) | `true` | `true` | `true` | The flat database; everything below builds on it. |
 | [`FlatDb.HistoryEnabled`](./configuration.md#flatdb-historyenabled) | `true` | `true` | `true` | Captures per-block state changesets - historical state queries answer from these. |
-| [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) | `0` (default) | e.g. `450000` | e.g. `450000` | The state-history window, in blocks below the tip. `0` keeps state history from genesis. |
-| [`FlatDb.HistorySliceAddresses`](./configuration.md#flatdb-historysliceaddresses) | unset | unset | e.g. `0xC02a...,0xA0b8...:2000000` | Contracts kept queryable beyond the general window: their state rows survive pruning, and every block one of these addresses appears in keeps its receipts and full body, so logs and transactions stay answerable. `addr` retains forever; `addr:N` retains while a height is within `N` blocks of the head. |
+| [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) | `0` (default) | the window size, in blocks | the window size, in blocks | The state-history window, in blocks below the tip. `0` keeps state history from genesis. |
+| [`FlatDb.HistorySliceAddresses`](./configuration.md#flatdb-historysliceaddresses) | unset | unset | the sliced addresses | Contracts kept queryable beyond the general window: their state rows survive pruning, and every block one of these addresses appears in keeps its receipts and full body, so logs and transactions stay answerable. `address` retains forever; `address:N` retains while a height is within `N` blocks of the head. |
 | [`History.Pruning`](./configuration.md#history-pruning) | `Disabled` (default) | `Rolling` | `Rolling` | Block-and-receipt expiry. Independent of state history, but a windowed node normally rolls both. |
-| [`History.RetentionEpochs`](./configuration.md#history-retentionepochs) | - | default `82125` | default `82125` | How many epochs (32 blocks each) of bodies and receipts the rolling pruner keeps. Must be at least the chain's `minHistoryRetentionEpochs` chainspec parameter. |
+| [`History.RetentionEpochs`](./configuration.md#history-retentionepochs) | - | the retention window, in epochs | the retention window, in epochs | How many epochs of bodies and receipts the rolling pruner keeps. Must be at least the chain's `minHistoryRetentionEpochs` chainspec parameter. |
 | [`LogIndex.Enabled`](./configuration.md#logindex-enabled) | recommended | recommended | recommended | The address/topic to block-number index behind fast `eth_getLogs`. Builds over whatever receipts the node stores. |
 | [`Receipt.TxLookupLimit`](./configuration.md#receipt-txlookuplimit) | `0` | `0` | `0` | `0` keeps the transaction-hash lookup index for every stored height; retained sliced heights keep their entries either way. |
 | [`Receipt.DeriveFromState`](./configuration.md#receipt-derivefromstate) | optional | - | - | The receiptless variant: receipts are derived from state instead of persisted. See [Receiptless archive](#receiptless-archive). |
@@ -59,5 +59,5 @@ On an address-slice node, reads below the general window serve only the sliced a
 ## Notes
 
 - A slice retention shallower than the general window is refused at startup, because it would delete an address's rows inside the advertised window.
-- The state-history pruner paces itself with [`FlatDb.HistoryPruneIntervalBlocks`](./configuration.md#flatdb-historypruneintervalblocks) (default `1024`) and [`FlatDb.HistoryPrunePassBudgetSeconds`](./configuration.md#flatdb-historyprunepassbudgetseconds) (default `5`). The pass budget must exceed the longest historical query the node serves, since deletes wait for in-flight historical reads.
+- The state-history pruner paces itself with [`FlatDb.HistoryPruneIntervalBlocks`](./configuration.md#flatdb-historypruneintervalblocks) and [`FlatDb.HistoryPrunePassBudgetSeconds`](./configuration.md#flatdb-historyprunepassbudgetseconds). The pass budget must exceed the longest historical query the node serves, since deletes wait for in-flight historical reads.
 - [`FlatDb.HistoryVerifyEveryBlock`](./configuration.md#flatdb-historyverifyeveryblock) (default off) runs a one-shot background proof on unwindowed archives: it rebuilds the state root from history rows at every covered block and compares it against the node's own headers. Memory usage follows state size.

docs/fundamentals/history-pruning.md

@@ -19,6 +19,8 @@ Removing history that is already stored is a separate, opt-in step controlled by
 - `UseAncientBarriers` — removes stored block bodies and receipts below the lower of the two ancient barriers.
 - `Rolling` — keeps a moving window of the most recent [`History.RetentionEpochs`](./configuration.md#history-retentionepochs) epochs and prunes below it as the head advances. The configured window must be at least the `minHistoryRetentionEpochs` chainspec parameter of the network, and a node that has just synced only starts pruning once its stored history grows past the window.
 
+Pruning publishes the new retention boundary first and reclaims the space below it in the background, in bounded passes that do not block block processing. Disk space returns gradually as the database rewrites its files.
+
 Pruning never removes the genesis block or anything at or above the sync pivot. Use [`History.PruningInterval`](./configuration.md#history-pruninginterval) and [`History.PruningTimeoutSeconds`](./configuration.md#history-pruningtimeoutseconds) to control how often it runs and how long a single pass may take.
 
 Blocks in which an address listed in [`FlatDb.HistorySliceAddresses`](./configuration.md#flatdb-historysliceaddresses) appears keep their receipts and bodies beyond the rolling window, so logs and transactions for those contracts stay answerable; see [Archive nodes](./archive-nodes.md).