CAP-0025 updates

core/cap-0025.md

@@ -31,7 +31,7 @@ by showing that they:
 
 1. Have a high storage cost.
 2. Significantly increase bucket merge latency.
-3. Are only valuable for a niche range of scenarios. Additionally, its usefulness degrades
+3. Are only valuable for a niche range of scenarios. Additionally, their usefulness degrades
 at lower levels.
 
 The changes proposed will not affect bucket semantics. It will merely change how buckets are merged,
@@ -64,7 +64,7 @@ same ledger entries continuously.
 
 ## Specification
 
-The ledger protocol number will be increased, to version TBD. This is a breaking change. The bucket
+The ledger protocol number will be increased, to version 12. This is a breaking change. The bucket
 list will produce buckets differing from buckets of previous protocols. This difference will affect
 the bucket list hash, which is used for consensus.
 
@@ -75,27 +75,30 @@ occurrences of `LIVEENTRY` types of bucket entries across multiple buckets for t
 
 ### Merge Algorithm Changes
 
-Under protocol TBD, bucket merge will not consider shadows, so less
-bucket entries will be elided.
+Under protocol 12, new style bucket merges will not consider shadows, so less bucket entries will be
+elided. In order to perform a new style merge, nodes will compare versions of the inputs.
+Specifically, a new style merge will be performed if the input snap is of ledger version 12 or
+higher. This implies that nodes will keep performing old style merges with shadows until input snaps
+are of the right version.
 
 ### Protocol Upgrade Changes
+
 To avoid delays while adding the new data to the bucket list, old buckets are merged in the
 background as early as possible. Some of those merges are completed long before they are needed.
-After protocol TBD upgrade, all existing in-progress or completed (but not yet needed) merges will
-become obsolete.  The implementation will discard those merges, and start the new ones with same
-inputs, but choosing the new merge logic. Note, inputs to future buckets remain stable and derivable
-from the current bucket list until the future bucket is promoted into the bucket list. Due to this
-property, it is possible to re-start merges at any ledger between the initial merge trigger and the
-completed merge promotion. It must also be ensured that only new buckets are produced after the
-protocol upgrade.
-
-Picking the right time to upgrade is also important. If, for example, the upgrade is done at a
-ledger before the lowest level spill, merges will be re-started, but might not have enough time to
-complete before they are needed (as larger buckets take minutes to merge). This would cause a delay
-in ledger close, and could make a node lose sync. To facilitate this, the upgrade should happen
-right after the lowest level spill, when merges at that level (and all other levels, since level
-sizes are proportional) are promoted. This approach is possible, because bucket list guarantees
-completely deterministic timeline for level spills.
+After the protocol 12 upgrade, all existing in-progress or completed (but not yet needed) merges
+will remain relevant. The implementation will use these merges at appropriate ledgers, then,
+depending on the input versions for each level, will start old style or new style merges.
+Eventually, all bucket list levels will be performing new style merges. Because new style merges are
+started gradually, letting merges of older versions finish, nodes may upgrade at any ledger without
+delays.
+
+### History Archive Changes
+
+Starting protocol 12, nodes will not publish inputs or outputs to new style merges. With shadows
+removed, inputs to bucket merges are completely reconstructible from the bucket list itself. Note,
+inputs to merges remain stable and derivable from the current bucket list until the future bucket is
+promoted into the bucket list. Due to this property, it is possible to re-start merges at any ledger
+between the initial merge trigger and the completed merge promotion.
 
 ## Design Rationale
 
@@ -120,8 +123,8 @@ appropriate merge technique based on the version number in the ledger header.
 
 ## Test Cases
 
-Thorough testing will accompany the implementation.
+Test cases were included in the implementation.
 
 ## Implementation
 
-None yet.
+https://github.com/stellar/stellar-core/pull/2205