README.md revised and sync theory rewritten.

eynhaender · eynhaender · commit 7b55f5cfb225 · 2026-01-07T21:58:23.000-05:00
diff --git a/README.md b/README.md
@@ -14,19 +14,19 @@
 </div>
 
 ## tl;dr
-This is the **server component of libbitcoin v4**. It integrates the basic components and offers a **high performance Bitcoin full node** with a comprehensive set of client-server interfaces like **bitcoind, electrum and stratum** as well as an intergrated **block explorer**. It makes heavy use of the available hardware, internet connection and availabe RAM and CPU so you can sync the Bitcoin blockchain from genesis, today and in the future.
+This is the **server component of libbitcoin v4**. It integrates the basic components and offers a **high performance Bitcoin full node** with a comprehensive set of client-server interfaces like **bitcoind, electrum and stratum** as well as an intergrated **block explorer**. It makes full use of the available hardware, internet connection and availabe RAM and CPU so you can sync the Bitcoin blockchain from genesis, today and in the future.
 
 If you follow this README you will be able to build, run and monitor your own libbitcoin server (bs). Libbitcoin is a multi platform software that works on Linux, Windows and OSX (Intel and ARM).
 
 Now, If you want to see how fast your setup can sync the Bitcoin Blockchain, read on and get your libbitcoin server running today. It's pretty easy actually.
 
 **License Overview**
 
-All files in this repository fall under the license specified in [COPYING](COPYING). The project is licensed as [AGPL with a lesser clause](https://wiki.unsystem.net/en/index.php/Libbitcoin/License). It may be used within a proprietary project, but the core library and any changes to it must be published online. Source code for this library must always remain free for everybody to access.
+All files in this repository fall under the license specified in [COPYING](COPYING). The project is licensed under the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.en.html). It may be used within a proprietary project, but the core library and any changes to it must be published online. Source code for this library must always remain free for everybody to access.
 
 **About libbitcoin**
 
-The libbitcoin toolkit is a set of cross platform C++ libraries for building Bitcoin applications. The toolkit consists of several libraries, most of which depend on the foundational [libbitcoin-system](https://github.com/libbitcoin/libbitcoin-system) library. Each library's repository can be cloned and built separately. There are no packages yet in distribution, however each library includes an installation script (described below) which is regularly verified via [github actions](https://github.com/features/actions).
+The libbitcoin toolkit is a set of cross platform C++ libraries for building Bitcoin applications. The toolkit consists of several libraries, most of which depend on the foundational [libbitcoin-system](https://github.com/libbitcoin/libbitcoin-system) library. Each library's repository can be cloned and built separately. There are no packages yet in distribution, however each library includes an installation script (described below) which is regularly verified via [GitHub Actions](https://github.com/features/actions).
 
 ## Contents
 - [libbitcoin-server](#libbitcoin-server)
@@ -48,15 +48,15 @@ The libbitcoin toolkit is a set of cross platform C++ libraries for building Bit
       - [Kernel VM Tuning Parameters](#kernel-vm-tuning-parameters)
 
 ## Installation
-Depending on what operating system you use, the build process will be different. Detailed instructions are provided below.
+The build process is essentially the same on Linux, macOS, and other Unix-like systems. It differs significantly on Windows due to the use of native Visual Studio projects and solutions. Detailed instructions are provided below.
 
 - [Linux (Ubuntu)](#linux)
 - [macOS](#macos)
 - [Windows](#windows)
 
 ### Linux
 
-Linux users build libbitcoin node with the provided installation script `install.sh` that uses Autotools and pkg-config to first build the needed dependencies (boost, libpsec256) and then fetches the latest libbitcoin projects (libbitcoin-system, libbitcoin-database, libbitcoin-network, libbitcoin-node) from github and builds the stack bottom up to the libbitcoin-server executable - `bs`.
+Linux users can build libbitcoin node with the provided installation script `install.sh` that uses Autotools and pkg-config to first build the needed dependencies (boost, libpsec256) and then fetches the latest libbitcoin projects (libbitcoin-system, libbitcoin-database, libbitcoin-network, libbitcoin-node and libbitcoin-server) from GitHub and builds the stack bottom up to the libbitcoin-server executable - `bs`.
 
 You can issue the following command to check for further parameterization of the install script:
 
@@ -111,7 +111,7 @@ $ sudo apt install build-essential curl git autoconf automake pkg-config libtool
 ```
 
 #### Build
-Create a new directory (e.g. `/home/user/libbitcoin`), then use git to fetch the latest repository from github by issuing the following command from within this directory:
+Create a new directory (e.g. `/home/user/libbitcoin`), then use git to fetch the latest repository from GitHub by issuing the following command from within this directory:
 
 ```bash
 git clone https://github.com/libbitcoin/libbitcoin-server
@@ -142,7 +142,7 @@ This will build the libbitcoin-server executable as a static release with no [CP
 ~/bitcoin/libbitcoin/build/release_static/share/doc/libbitcoin-system/
 ~/bitcoin/libbitcoin/libbitcoin-node
 ```
-Now enter the bin directory and [fire up](#running-libbitcoin) your libbitcoin server.
+Now enter the bin directory and [fire up](#running-bs) your libbitcoin server.
 
 #### CPU Extensions
 CPU Extensions are specific optimizations your CPU might or might not have. libbitcoin(-server) can be built with support for the following CPU extensions if your architecture supports them:
@@ -155,14 +155,14 @@ CPU Extensions are specific optimizations your CPU might or might not have. libb
 To build libbitcoin-server with these extensions use the `--enable-feature` parameters like:
 
 - --enable-shani
-- --enable-avx2
 - --enable-sse41
+- --enable-avx2
 - --enable-avx512
 
 This command will create a static release build with all supported CPU extensions (if supported by the system). Building libbitcoin with unsupported CPU extensions might work but will lead to crashes at runtime.
 
 ```bash
-$ CFLAGS="-O3" CXXFLAGS="-O3" ./install.sh --prefix=/home/user/libbitcoin/build/release_static/ --build-dir=/home/user/libbitcoin/build/temp --build-secp256k1 --build-boost --disable-shared --enable-ndebug --enable-shani --enable-avx2 --enable-sse41 --enable-avx512 --enable-isystem
+$ CFLAGS="-O3" CXXFLAGS="-O3" ./install.sh --prefix=/home/user/libbitcoin/build/release_static/ --build-dir=/home/user/libbitcoin/build/temp --build-secp256k1 --build-boost --disable-shared --enable-ndebug --enable-shani --enable-avx2 --enable-sse41 --enable-isystem
 ```
 
 You can check if the optimizations have been built in your binary with the following command:
diff --git a/docs/theory-of-operation.md b/docs/theory-of-operation.md
@@ -2,7 +2,7 @@
 
 ## Architecture Overview
 
-Libbitcoin is a full-stack C++ development framework for Bitcoin. It includes everything from basic hash functions (in libbitcoin-system) up to a high performance full node (libbitcoin-node) and a comprehensive client-server connection layer on top (libbitcoin-server)
+Libbitcoin is a full-stack C++ development toolkit for Bitcoin. It includes everything from basic hash functions (in libbitcoin-system) up to a high performance full node (libbitcoin-node) and a comprehensive client-server connection layer on top (libbitcoin-server)
 
 ## Components
 
@@ -32,15 +32,13 @@ TBD
 libbitcoin-node distinguishes between two different methods for the initial block download (IBD).
 
 ### Milestone Sync
-Milestone Sync (the default mode) is optimized for speed. Up to a configured milestone (a specific block in the past considered trustworthy), certain expensive validation steps are skipped.
+Milestone Sync (the default mode) is optimized for speed. If the user has previously fully validated the chain up to the configured milestone hash, expensive block validation steps below that height are skipped on subsequent synchronizations.
 
-Specifically: Blocks at or below the highest checkpoint/milestone are not fully validated. This primarily means that signature verifications (script validation) in old blocks are skipped or performed in a reduced manner.
+Specifically: For blocks at or below the milestone height, all validation except identity checks (block hash, Merkle root, and witness commitment) is skipped. Block headers are always fully validated. Unlike Bitcoin Core's AssumeValid (which skips only signature verification), Libbitcoin skips nearly all block-level checks below the milestone.
 
-Other checks (e.g. Proof-of-Work, basic block rules) are still performed, but resource-intensive operations like full ECDSA verifications are avoided.
+Starting from the milestone (and for all new blocks), full validation is applied. There are no trust assumptions — milestone optimization is secure only because the user has previously validated to that point themselves. If the user has not previously validated the chain, they should perform a full validation sync from genesis and record a new milestone for future use.
 
-Starting from the milestone (and for all new blocks), full validation is applied. As the chain height progresses, the current milestone is updated upward every 50,000 blocks. The most recent milestone is currently block 900,000.
-
-This approach aligns with the security model of Bitcoin Core's "AssumeValid." It assumes the chain up to that point is correct (based on prior validation or community consensus). This makes the IBD significantly faster while providing practically the same level of security for most users.
+There is only one level of security: full independent validation. Milestone Sync provides the same security as full validation for users who have previously validated the chain themselves, while significantly accelerating subsequent synchronizations.
 
 The following diagram shows the runtime behaviour of `bs` in milestone sync mode on a 256GB RAM, 64 Cores computer running Ubuntu:
 
@@ -55,13 +53,9 @@ The following diagram shows the runtime behaviour of `bs` in milestone sync mode
 As the CPU load is significantly lower compared to a full validation sync, one can see clearly how the network performace is the bottleneck. In other words, the faster the network, the faster the sync - until the bottleneck moves to validation power again.
 
 ### Full Validation Sync
-In full validation mode, the entire blockchain is fully validated from the genesis block onward, without any optimizations or shortcuts. This means every block is checked against all consensus rules: Proof-of-Work, block header validity, Merkle root, timestamp rules, etc.
-
-Every transaction in every block is fully validated, including complete script and signature verification (ECDSA signatures for all inputs).
-
-There are no trust assumptions for historical blocks—everything is independently verified.
+In full validation mode, the entire blockchain is fully validated from the genesis block onward, without any optimizations or shortcuts. Every block and transaction is checked against all consensus rules, including complete script and signature verification.
 
-This is the mode with the highest security, as no part of the chain is assumed to be "pre-validated." However, it is slower and more CPU-intensive.
+There are never any trust assumptions — everything is independently verified. This is recommended for the initial synchronization or whenever the user has not previously validated the chain themselves. Once complete, a milestone can be recorded for faster future synchronizations while maintaining the same single level of security.
 
 The following diagram shows the runtime behaviour of `bs` in full validation sync mode on a 256GB RAM, 64 Cores computer running Ubuntu (same system as above):
 
@@ -73,24 +67,22 @@ The following diagram shows the runtime behaviour of `bs` in full validation syn
 
 </div>
 
-## Checkpoints and Milestone
-**Checkpoints** are a list of fixed block hashes at specific heights (e.g., genesis plus others). They primarily protect against reorganization attacks. The node rejects any alternative chain that violates a checkpoint, enforcing acceptance of the canonical chain up to those points.
+## Checkpoints and Milestones
 
-The **milestone** is a special (highest) checkpoint that additionally controls validation optimization: Up to this block, full validation is skipped.
+**Checkpoints** are fixed block hashes at specific heights that represent activated consensus rules (soft forks). They are required consensus points: the node rejects any chain that violates a checkpoint, enforcing the canonical chain up to those heights.
 
-In the default configuration, there are multiple checkpoints and one milestone at a relatively recent height (currently block 900,000).
+**Milestones** are distinct from checkpoints. A milestone is an optional optimization point (not a consensus requirement) that allows skipping full block validation below its height — but only if the user has previously validated the chain to that milestone hash themselves.
 
-To perform a full validation sync, set both values in the [config](configuration.md#) file to the genesis block (hash: 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f, height 0):
+In the default configuration, multiple checkpoints are defined (as consensus rules), along with one milestone at a relatively recent height (currently block 900,000).
+
+To perform a full validation sync (disabling milestone optimization while preserving consensus checkpoints), set only the milestone value in the configuration file to the genesis block::
 
 ```
 [bitcoin]
-checkpoint = 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f:0
 milestone = 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f:0
 ```
 
-This disables all optimizations. Everything is fully validated.
-
-Checkpoints and milestones rely on trust in the developers/community (they are hardcoded or configurable), but they don't prevent real attacks on old blocks—they only accelerate syncing. For maximum sovereignty, Full Validation is recommended. For everyday use, Milestone Sync is usually sufficient.
+Checkpoints are consensus rules and should not be disabled. Milestones introduce no trust assumptions — they rely solely on the user's prior independent validation. For maximum sovereignty on first use or after potential compromise, perform a full validation sync from genesis. For subsequent synchronizations or everyday use (after initial full validation), Milestone Sync provides the same security with significantly faster performance.
 
 ## Linux Dirty Page Writeback Tuning Notes
 While standard Ubuntu installations adhere to the upstream Linux kernel defaults (`vm.dirty_bytes=0` and `vm.dirty_background_bytes=0`), enabling percentage-based control via `vm.dirty_ratio=20` and `vm.dirty_background_ratio=10`, some Ubuntu-based derivatives (e.g., Pop!_OS, Kubuntu) override these in their default sysctl configuration with fixed byte thresholds (commonly `vm.dirty_bytes=268435456` or similar values around 256 MiB).
