docs: add optional chainstore fallback section

0xDevNinja · web-flow · commit 91ef7b238578 · 2026-01-08T08:41:31.000-08:00
Add documentation for the FOREST_ENABLE_CHAINSTORE_FALLBACK environment variable and describe how to enable the fallback blockstore via Bitswap. Part of issue #6353.
diff --git a/README.md b/README.md
@@ -29,6 +29,19 @@ Have questions? Feel free to post them in [Forest Q&A]!
 
 ## Run with Docker
 
+## Optional Chainstore Fallback
+
+Forest supports an experimental fallback blockstore to fetch missing blocks from the network via Bitswap when they are not available locally. This behavior is disabled by default.
+
+To  enable fallback, set the environment variable:
+
+    FOREST_ENABLE_CHAINSTORE_FALLBACK=1
+
+When enabled, Forest will attempt to retrieve missing blocks via Bitswap during chain sync. If the block is successfully retrieved, it will be stored locally and chain sync will continue. If the block cannot be fetched from the network, chain sync will return an error as usual.
+
+Note: This feature is inspired by Lotus's `LOTUS_ENABLE_CHAINSTORE_FALLBACK` and is considered experimental. Use with caution in production.
+
+
 No need to install Rust toolchain or other dependencies, you will need only
 Docker - works on Linux, macOS and Windows.
 
