From f4fe4e5e3c4f4e79a9487b67c08d2220aad6f0be Mon Sep 17 00:00:00 2001
From: Martin Tomazic <martin.tomazic97@gmail.com>
Date: Tue, 4 Nov 2025 11:34:33 +0100
Subject: [PATCH] docs/node/run-your-node/advanced: Add new pruning section

---
 docs/node/run-your-node/advanced/pruning.md | 77 +++++++++++++++++++++
 sidebarNode.ts                              |  3 +-
 2 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 docs/node/run-your-node/advanced/pruning.md

diff --git a/docs/node/run-your-node/advanced/pruning.md b/docs/node/run-your-node/advanced/pruning.md
new file mode 100644
index 0000000000..1d654ef5f0
--- /dev/null
+++ b/docs/node/run-your-node/advanced/pruning.md
@@ -0,0 +1,77 @@
+# Pruning State
+
+To reduce hardware requirements and improve the overall latency of the node,
+operators are encouraged to prune their state (unless they are archivers or
+historical nodes).
+
+As will be explained in the following sections, pruning should be configured from
+the start, i.e. late changes to the pruning configuration may not be optimal for
+the node's health.
+
+## Consensus Pruning
+
+To configure pruning of the consensus data amend your node's configuration with:
+
+```yaml
+# ... sections not relevant are omitted ...
+consensus:
+    # ... sections not relevant are omitted ...
+    prune:
+        strategy: "keep_n"
+        num_kept:  <n>
+```
+
+where `<n>` is the number of blocks and state versions that will be kept.
+
+### Suggested Pruning Configuration
+
+For normal node operation, the minimum requirements is `n=250_000`. However,
+it is recommended to set it to `n=400_000`. Assuming blocks are produced every 6
+seconds, the latter corresponds to preserving 1 month of the consensus data.
+
+Operators that are not resouce-restrained and want to contribute to the overall
+network health are encouraged to set `n=5_000_000` (approximately 1 year of data).
+
+### Late Pruning
+
+Due to the [LSM Tree][] design of the underlying databases, enabling pruning after
+your node has been runing for a while, or possibly changing configuration to retain
+less data, may may not work as expected.
+
+To change pruning configuration operators must follow this steps:
+1. Gracefuly shutdown the node (validators should take [special care][graceful shutdown]).
+2. Configure pruning as described in [Consensus Pruning](#consensus-pruning).
+3. Run offline pruning (TODO insert link).
+4. Run the [compaction command][].
+5. Start the node again.
+
+[LSM tree]: https://en.wikipedia.org/wiki/Log-structured_merge-tree
+[graceful shutdown]: ../maintenance/shutting-down-a-node.md
+[compaction command]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/oasis-node/cli.md#compact-experimental
+
+## Paratime Pruning
+
+
+To configure pruning of the paratime data ammend your node's configuration with:
+
+```yaml
+# ... sections not relevant are omitted ...
+runtime:
+    # ... sections not relevant are omitted ...
+    prune:
+        strategy: "keep_last"
+        num_kept:  <n>
+```
+
+where `<n>` is the number of paratime's state versions that will be kept.
+
+### Suggested Pruning Configuration
+
+Paratime state is much larger than the consensus state. As a consequence, as the
+number of versions in the state database grows, pruning becomes slower and slower.
+ For this reason **paratime state pruning must be configured
+from the start or not configured at all**.
+
+To configure pruning it is recommended to set `n=250_000`. The maximum value is
+`n=400_000`. If you need to preserve more data (e.g. nodes serving historical
+state) you will have to keep the entire state from the genesis.
diff --git a/sidebarNode.ts b/sidebarNode.ts
index b9514cdab6..8220e3e071 100644
--- a/sidebarNode.ts
+++ b/sidebarNode.ts
@@ -106,6 +106,7 @@ export const sidebarNode: SidebarsConfig = {
           },
           items: [
             'node/run-your-node/advanced/sync-node-using-state-sync',
+            'node/run-your-node/advanced/pruning',
             'node/run-your-node/advanced/copy-state-from-one-node-to-the-other',
             'node/run-your-node/advanced/remote-signer',
           ],
@@ -165,7 +166,7 @@ export const sidebarNode: SidebarsConfig = {
               label: 'Mainnet',
             },
             {
-              type: 'doc', 
+              type: 'doc',
               id: 'node/reference/upgrade-logs/testnet',
               label: 'Testnet',
             },