From f052d00de5552a9b2e58ff0698a10ae9f04471ca Mon Sep 17 00:00:00 2001 From: Stavros Vlachakis <89769224+svlachakis@users.noreply.github.com> Date: Sat, 5 Sep 2026 00:41:58 +0300 Subject: [PATCH 1/4] docs: flat-history retention is an explicit mode Claude-Session: https://claude.ai/code/session_01HgBnLgVkLh1qRZV51SY5gQ --- docs/fundamentals/archive-nodes.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/fundamentals/archive-nodes.md b/docs/fundamentals/archive-nodes.md index df593475a..24a3e94d5 100644 --- a/docs/fundamentals/archive-nodes.md +++ b/docs/fundamentals/archive-nodes.md @@ -13,7 +13,7 @@ Two independent groups of configuration options compose: ## Archive shapes - **Full archive** answers every historical query at every height, state and receipts, from genesis. -- **Windowed archive** answers everything a full archive does, but only for the last [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) blocks. Older queries are refused with a pruned-history error - never answered wrongly from live state. Disk stays bounded: the pruner reclaims continuously as the window rolls. +- **Windowed archive** answers everything a full archive does, but only for the last [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) blocks, with [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) set to `Rolling`. Older queries are refused with a pruned-history error - never answered wrongly from live state. Disk stays bounded: the pruner reclaims continuously as the window rolls. - **Address-slice archive** is a windowed node whose named contracts additionally answer to their full slice depth - state, logs, and transactions - while everything else rolls with the window. ## Configuration @@ -24,7 +24,8 @@ Each option is documented in its own section of the [configuration reference](./ |---|---|---|---|---| | [`FlatDb.Enabled`](./configuration.md#flatdb-enabled) | `true` | `true` | `true` | The flat database itself. | | [`FlatDb.HistoryEnabled`](./configuration.md#flatdb-historyenabled) | `true` | `true` | `true` | Captures the per-block state changesets. | -| [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) | `0` (default) | the window size, in blocks | the window size, in blocks | The state-history window; `0` keeps state history from genesis. | +| [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) | `None` (default) | `Rolling` | `Rolling` | Whether flat history is kept unbounded or in a rolling window. | +| [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) | - | the window size, in blocks | the window size, in blocks | Size of the rolling window. Required with `Rolling`, rejected otherwise. | | [`FlatDb.HistorySliceAddresses`](./configuration.md#flatdb-historysliceaddresses) | unset | unset | the sliced addresses | Contracts kept queryable beyond the general window. | | [`History.Pruning`](./configuration.md#history-pruning) | `Disabled` (default) | `Rolling` | `Rolling` | Block-and-receipt expiry; see [History pruning](./history-pruning.md). | | [`History.RetentionEpochs`](./configuration.md#history-retentionepochs) | - | the retention window, in epochs | the retention window, in epochs | How much block-and-receipt history the rolling pruner keeps. | @@ -36,7 +37,7 @@ Each option is documented in its own section of the [configuration reference](./ Every archive setting is default-off: a node that configures none of them behaves exactly as before. :::warning Important -Setting `FlatDb.HistoryRetentionBlocks` to a non-zero value selects the windowed row format and requires fresh flat history: enabling it on an existing unwindowed flat-history database is refused, and there is no in-place conversion. Start with a fresh sync. +`FlatDb.HistoryRetention=Rolling` selects the windowed row format and requires fresh flat history: enabling it on an existing unwindowed flat-history database is refused, and there is no in-place conversion. Start with a fresh sync. ::: :::warning Important From 1e96f06fa8cdd4c17d86cbcb6ebe97cd15342309 Mon Sep 17 00:00:00 2001 From: Stavros Vlachakis <89769224+svlachakis@users.noreply.github.com> Date: Sat, 5 Sep 2026 01:51:40 +0300 Subject: [PATCH 2/4] docs: since-block archive shape Claude-Session: https://claude.ai/code/session_01HgBnLgVkLh1qRZV51SY5gQ --- docs/fundamentals/archive-nodes.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/archive-nodes.md b/docs/fundamentals/archive-nodes.md index 24a3e94d5..d49f93539 100644 --- a/docs/fundamentals/archive-nodes.md +++ b/docs/fundamentals/archive-nodes.md @@ -15,6 +15,7 @@ Two independent groups of configuration options compose: - **Full archive** answers every historical query at every height, state and receipts, from genesis. - **Windowed archive** answers everything a full archive does, but only for the last [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) blocks, with [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) set to `Rolling`. Older queries are refused with a pruned-history error - never answered wrongly from live state. Disk stays bounded: the pruner reclaims continuously as the window rolls. - **Address-slice archive** is a windowed node whose named contracts additionally answer to their full slice depth - state, logs, and transactions - while everything else rolls with the window. +- **Since-block archive** keeps everything from a fixed block onward, forever: set [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) to `SinceBlock` and [`FlatDb.HistoryRetentionSinceBlock`](./configuration.md#flatdb-historyretentionsinceblock) to that block. Nothing below it is captured and queries there fail closed; nothing above it is ever pruned. For blocks and receipts from the same point, use `History.Pruning=UseAncientBarriers` with the ancient barriers set to that block; see [History pruning](./history-pruning.md). This suits operators whose indexers only need history from a known starting point that never moves. ## Configuration @@ -24,8 +25,9 @@ Each option is documented in its own section of the [configuration reference](./ |---|---|---|---|---| | [`FlatDb.Enabled`](./configuration.md#flatdb-enabled) | `true` | `true` | `true` | The flat database itself. | | [`FlatDb.HistoryEnabled`](./configuration.md#flatdb-historyenabled) | `true` | `true` | `true` | Captures the per-block state changesets. | -| [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) | `None` (default) | `Rolling` | `Rolling` | Whether flat history is kept unbounded or in a rolling window. | +| [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) | `None` (default) | `Rolling` | `Rolling` | Whether flat history is kept unbounded, in a rolling window, or from a fixed block onward (`SinceBlock`, see below). | | [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) | - | the window size, in blocks | the window size, in blocks | Size of the rolling window. Required with `Rolling`, rejected otherwise. | +| [`FlatDb.HistoryRetentionSinceBlock`](./configuration.md#flatdb-historyretentionsinceblock) | - | - | - | First block to keep. Required with `SinceBlock`, rejected otherwise. | | [`FlatDb.HistorySliceAddresses`](./configuration.md#flatdb-historysliceaddresses) | unset | unset | the sliced addresses | Contracts kept queryable beyond the general window. | | [`History.Pruning`](./configuration.md#history-pruning) | `Disabled` (default) | `Rolling` | `Rolling` | Block-and-receipt expiry; see [History pruning](./history-pruning.md). | | [`History.RetentionEpochs`](./configuration.md#history-retentionepochs) | - | the retention window, in epochs | the retention window, in epochs | How much block-and-receipt history the rolling pruner keeps. | @@ -37,7 +39,7 @@ Each option is documented in its own section of the [configuration reference](./ Every archive setting is default-off: a node that configures none of them behaves exactly as before. :::warning Important -`FlatDb.HistoryRetention=Rolling` selects the windowed row format and requires fresh flat history: enabling it on an existing unwindowed flat-history database is refused, and there is no in-place conversion. Start with a fresh sync. +`FlatDb.HistoryRetention=Rolling` or `SinceBlock` selects the windowed row format and requires fresh flat history: enabling it on an existing unwindowed flat-history database is refused, and there is no in-place conversion. Start with a fresh sync. ::: :::warning Important From 71301914d2d2963e9b4e229380e8062f375522c5 Mon Sep 17 00:00:00 2001 From: Stavros Vlachakis <89769224+svlachakis@users.noreply.github.com> Date: Sat, 5 Sep 2026 02:19:50 +0300 Subject: [PATCH 3/4] docs: slices are not accepted with SinceBlock Claude-Session: https://claude.ai/code/session_01HgBnLgVkLh1qRZV51SY5gQ --- docs/fundamentals/archive-nodes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/archive-nodes.md b/docs/fundamentals/archive-nodes.md index d49f93539..586936c9d 100644 --- a/docs/fundamentals/archive-nodes.md +++ b/docs/fundamentals/archive-nodes.md @@ -15,7 +15,7 @@ Two independent groups of configuration options compose: - **Full archive** answers every historical query at every height, state and receipts, from genesis. - **Windowed archive** answers everything a full archive does, but only for the last [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) blocks, with [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) set to `Rolling`. Older queries are refused with a pruned-history error - never answered wrongly from live state. Disk stays bounded: the pruner reclaims continuously as the window rolls. - **Address-slice archive** is a windowed node whose named contracts additionally answer to their full slice depth - state, logs, and transactions - while everything else rolls with the window. -- **Since-block archive** keeps everything from a fixed block onward, forever: set [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) to `SinceBlock` and [`FlatDb.HistoryRetentionSinceBlock`](./configuration.md#flatdb-historyretentionsinceblock) to that block. Nothing below it is captured and queries there fail closed; nothing above it is ever pruned. For blocks and receipts from the same point, use `History.Pruning=UseAncientBarriers` with the ancient barriers set to that block; see [History pruning](./history-pruning.md). This suits operators whose indexers only need history from a known starting point that never moves. +- **Since-block archive** keeps everything from a fixed block onward, forever: set [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) to `SinceBlock` and [`FlatDb.HistoryRetentionSinceBlock`](./configuration.md#flatdb-historyretentionsinceblock) to that block. Nothing below it is captured and queries there fail closed; nothing above it is ever pruned. For blocks and receipts from the same point, use `History.Pruning=UseAncientBarriers` with the ancient barriers set to that block; see [History pruning](./history-pruning.md). Slices (`FlatDb.HistorySliceAddresses`) are not accepted in this mode: nothing is ever pruned, so a slice would add nothing. This suits operators whose indexers only need history from a known starting point that never moves. ## Configuration From 37f95cea3a75e839325f4288b579bc6f16abffa1 Mon Sep 17 00:00:00 2001 From: Stavros Vlachakis <89769224+svlachakis@users.noreply.github.com> Date: Sun, 6 Sep 2026 12:30:38 +0300 Subject: [PATCH 4/4] docs: slices with SinceBlock keep their receipt retention Claude-Session: https://claude.ai/code/session_01HgBnLgVkLh1qRZV51SY5gQ --- docs/fundamentals/archive-nodes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/archive-nodes.md b/docs/fundamentals/archive-nodes.md index 586936c9d..d39d81172 100644 --- a/docs/fundamentals/archive-nodes.md +++ b/docs/fundamentals/archive-nodes.md @@ -15,7 +15,7 @@ Two independent groups of configuration options compose: - **Full archive** answers every historical query at every height, state and receipts, from genesis. - **Windowed archive** answers everything a full archive does, but only for the last [`FlatDb.HistoryRetentionBlocks`](./configuration.md#flatdb-historyretentionblocks) blocks, with [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) set to `Rolling`. Older queries are refused with a pruned-history error - never answered wrongly from live state. Disk stays bounded: the pruner reclaims continuously as the window rolls. - **Address-slice archive** is a windowed node whose named contracts additionally answer to their full slice depth - state, logs, and transactions - while everything else rolls with the window. -- **Since-block archive** keeps everything from a fixed block onward, forever: set [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) to `SinceBlock` and [`FlatDb.HistoryRetentionSinceBlock`](./configuration.md#flatdb-historyretentionsinceblock) to that block. Nothing below it is captured and queries there fail closed; nothing above it is ever pruned. For blocks and receipts from the same point, use `History.Pruning=UseAncientBarriers` with the ancient barriers set to that block; see [History pruning](./history-pruning.md). Slices (`FlatDb.HistorySliceAddresses`) are not accepted in this mode: nothing is ever pruned, so a slice would add nothing. This suits operators whose indexers only need history from a known starting point that never moves. +- **Since-block archive** keeps everything from a fixed block onward, forever: set [`FlatDb.HistoryRetention`](./configuration.md#flatdb-historyretention) to `SinceBlock` and [`FlatDb.HistoryRetentionSinceBlock`](./configuration.md#flatdb-historyretentionsinceblock) to that block. Nothing below it is captured and queries there fail closed; nothing above it is ever pruned. For blocks and receipts from the same point, use `History.Pruning=UseAncientBarriers` with the ancient barriers set to that block; see [History pruning](./history-pruning.md). Slices (`FlatDb.HistorySliceAddresses`) keep their block-and-receipt retention in this mode; their flat-history side has nothing to keep, since nothing is ever pruned. This suits operators whose indexers only need history from a known starting point that never moves. ## Configuration