From 3d902208f9ffe251234012fb00c4f3b110477f31 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Sun, 15 Mar 2026 21:36:47 -0400
Subject: [PATCH] Update documentation: clarify blockchain header sync
 requirement

Corrected previous misinformation:
- LBRY SDK DOES require blockchain header sync (not full blocks)
- First run: 5-10 minutes to download ~1.7M headers
- Added troubleshooting entry for BlockHeightEvent messages
- Users now understand what the sync process looks like
- Provided commands to stop the daemon

This addresses user concerns about the invasive blockchain sync
and ensures users know what to expect on first run.
---
 LINUX_SETUP.md | 57 +++++++++++++++++++++++++++++++++++++++++++-------
 README.md      |  8 ++++++-
 2 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/LINUX_SETUP.md b/LINUX_SETUP.md
index 3235949..cd11136 100644
--- a/LINUX_SETUP.md
+++ b/LINUX_SETUP.md
@@ -42,17 +42,29 @@ This script will:
 
 **Want to uninstall later?** Just run `./uninstall.py`
 
-### About LBRY SDK (lbrynet)
+### About LBRY SDK (lbrynet) - IMPORTANT
 
 **Q: Does this download the LBRY blockchain?**
 
-**A:** No! The LBRY SDK is a light client that:
-- Connects to LBRY's servers and peer network
-- Downloads only the content you request
-- Does **NOT** require blockchain synchronization (unlike Bitcoin)
-- Uses minimal disk space (just the downloaded content)
+**A:** The LBRY SDK downloads **blockchain headers** (not full blocks), which is required to function:
 
-The LBRY SDK acts like a specialized download manager for the LBRY network, not a full blockchain node.
+**First-time setup (one-time):**
+- Downloads ~1.7 million block headers
+- Takes approximately 5-10 minutes
+- Uses minimal storage space (headers only, not full blocks)
+- Shows progress like: `lbc_mainnet: added BlockHeightEvent(height=1663209, change=2001)`
+
+**Subsequent use:**
+- Near-instant startup after initial sync
+- Only downloads new headers since last run
+
+**What this means:**
+- The LBRY SDK needs this data to verify which content claims are valid
+- This is lighter than Bitcoin's full blockchain sync
+- But it IS required and will take time on first launch
+- You can stop it with `Ctrl+C` or `lbrynet stop`
+
+**Privacy note:** This connects to LBRY's network and syncs blockchain data to verify content. This is how the LBRY protocol works.
 
 ---
 
@@ -567,6 +579,37 @@ ss -tlnp | grep 5279
 sudo journalctl -u lbrynet -n 50
 ```
 
+### "lbc_mainnet: added BlockHeightEvent" - What's happening?
+
+**This is normal!** On first run, lbrynet syncs blockchain headers:
+
+```
+lbc_mainnet: added BlockHeightEvent(height=1663209, change=2001)
+lbc_mainnet: added BlockHeightEvent(height=1665210, change=2001)
+```
+
+**What this means:**
+- The LBRY SDK is downloading blockchain headers (not full blocks)
+- This is required to verify content claims
+- Takes 5-10 minutes on first run
+- Subsequent runs are instant
+
+**To stop it:**
+```bash
+# Stop the daemon
+lbrynet stop
+
+# Or kill the process
+pkill -f lbrynet
+```
+
+**To check sync progress:**
+```bash
+lbrynet status
+```
+
+**Note:** This is a one-time process. Once complete, the daemon starts instantly.
+
 ### "Permission denied" when running lbrynet
 
 ```bash
diff --git a/README.md b/README.md
index c7a07e1..25554cf 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,13 @@ The setup script will:
 - ✅ Set download limits
 - ✅ Create launcher scripts
 
-**Note:** The LBRY SDK is a light client - it connects to the network and downloads content **without** needing to sync the entire blockchain (unlike Bitcoin). It only downloads the content you request.
+**Important:** The LBRY SDK (lbrynet) requires syncing blockchain **headers** (not full blocks) to function. On first run:
+- Downloads ~1.7 million block headers (takes 5-10 minutes)
+- Uses minimal storage (headers only, not full blockchain)
+- Subsequent starts are instant
+- This is required to verify content claims on the network
+
+This is lighter than Bitcoin's full blockchain sync, but still necessary for the downloader to work.
 
 ### Manual Install