From 750f5e59f6fe57f4b3c40c18df92d87aded4b9db Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 24 Jun 2017 18:35:25 +0000 Subject: [PATCH] BIP 8: Refactor back to wholly-contained spec This partially reverts 7f6a0f811cf27ab6d77e499afc81b97d6d11ced2 --- README.mediawiki | 2 +- bip-0008.mediawiki | 132 +++++++++++++++++++++++++++++++++++++++++--- bip-0008/states.png | Bin 6684 -> 20891 bytes bip-0008/states.svg | 51 +++++++++++++++++ 4 files changed, 176 insertions(+), 9 deletions(-) create mode 100644 bip-0008/states.svg diff --git a/README.mediawiki b/README.mediawiki index ca0138e5..d37d6fa0 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -30,7 +30,7 @@ Those proposing changes should consider that ultimately consent may rest with th |- | [[bip-0008.mediawiki|8]] | -| Version bits with guaranteed lock-in +| Version bits 2017 | Shaolin Fry | Informational | Draft diff --git a/bip-0008.mediawiki b/bip-0008.mediawiki index 3a1f2079..1409c63f 100644 --- a/bip-0008.mediawiki +++ b/bip-0008.mediawiki @@ -1,6 +1,6 @@ 
   BIP: 8
-  Title: Version bits with guaranteed lock-in
+  Title: Version bits 2017
   Author: Shaolin Fry 
   Comments-Summary: No comments yet.
   Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0008
@@ -13,7 +13,7 @@
 
 ==Abstract==
 
-This document specifies an extension to [[bip-0009.mediawiki|BIP9]] that introduces an additional activation parameter to guarantee activation of backward-compatible changes (further called "soft forks").
+This document specifies an alternative to [[bip-0009.mediawiki|BIP9]] that introduces an additional activation parameter to guarantee activation of backward-compatible changes (further called "soft forks").
 
 ==Motivation==
 
@@ -23,21 +23,105 @@ This specification provides a way to optionally guarantee lock-in at the end of
 
 ==Specification==
 
-This specification is the same as [[bip-0009.mediawiki|BIP9]] except from the STARTED state, there is no FAILED condition. The state transition from '''STARTED''' to '''LOCKED_IN''' will occur under two condition:
+Each soft fork deployment is specified by the following per-chain parameters (further elaborated below):
 
-The first is when the threshold  of blocks signalling is reached as per BIP9. The second is if the timeout is still '''STARTED'''.
+# The '''name''' specifies a very brief description of the soft fork, reasonable for use as an identifier. For deployments described in a single BIP, it is recommended to use the name "bipN" where N is the appropriate BIP number.
+# The '''bit''' determines which bit in the nVersion field of the block is to be used to signal the soft fork lock-in and activation. It is chosen from the set {0,1,2,...,28}.
+# The '''starttime''' specifies a minimum median time past of a block at which the bit gains its meaning.
+# The '''timeout''' specifies a time at which the deployment is considered failed. If the median time past of a block >= timeout and the soft fork has not yet locked in (including this block's bit state), the deployment is considered failed on all descendants of the block.
+# The '''lockinontimeout''' boolean if set to true, will transition state to '''LOCKED_IN''' at timeout if not already '''LOCKED_IN''' or '''ACTIVE'''.
+
+===Selection guidelines===
+
+The following guidelines are suggested for selecting these parameters for a soft fork:
+
+# '''name''' should be selected such that no two softforks, concurrent or otherwise, ever use the same name.
+# '''bit''' should be selected such that no two concurrent softforks use the same bit.
+# '''starttime''' should be set to some date in the future, approximately one month after a software release date including the soft fork.  This allows for some release delays, while preventing triggers as a result of parties running pre-release software.
+# '''timeout''' should be 1 year (31536000 seconds) after starttime.
+# '''lockinontimeout''' should be set to true for any softfork that isn't exclusively for miner benefit.
+
+A later deployment using the same bit is possible as long as the starttime is after the previous one's
+timeout or activation, but it is discouraged until necessary, and even then recommended to have a pause in between to detect buggy software.
+
+===States===
+
+With each block and soft fork, we associate a deployment state. The possible states are:
+
+# '''DEFINED''' is the first state that each soft fork starts out as. The genesis block is by definition in this state for each deployment.
+# '''STARTED''' for blocks past the starttime.
+# '''LOCKED_IN''' for one retarget period after the first retarget period with STARTED blocks of which at least threshold have the associated bit set in nVersion, or for one retarget period after the timeout when '''lockinontimeout''' is true.
+# '''ACTIVE''' for all blocks after the LOCKED_IN retarget period.
+# '''FAILED''' for all blocks after the timeout time, if LOCKED_IN was not reached and '''lockinontimeout''' is false.
+
+===Bit flags===
+
+The nVersion block header field is to be interpreted as a 32-bit little-endian integer (as present), and bits are selected within this integer as values (1 << N) where N is the bit number.
+
+Blocks in the STARTED state get an nVersion whose bit position bit is set to 1. The top 3 bits of such blocks must be
+001, so the range of actually possible nVersion values is [0x20000000...0x3FFFFFFF], inclusive.
+
+Due to the constraints set by BIP 34, BIP 66 and BIP 65, we only have 0x7FFFFFFB possible nVersion values available.
+This restricts us to at most 30 independent deployments. By restricting the top 3 bits to 001 we get 29 out of those
+for the purposes of this proposal, and support two future upgrades for different mechanisms (top bits 010 and 011).
+When a block nVersion does not have top bits 001, it is treated as if all
+bits are 0 for the purposes of deployments.
+
+Miners should continue setting the bit in LOCKED_IN phase so uptake is visible, though this has no effect on
+consensus rules.
+
+===New consensus rules===
+
+The new consensus rules for each soft fork are enforced for each block that has ACTIVE state.
 
 ===State transitions===
 
 
 
-During the STARTED state if the '''lockinontimeout''' is set to true, the state will transition to LOCKED_IN when '''timeout''' is reached.
+The genesis block has state DEFINED for each deployment, by definition.
+
+    State GetStateForBlock(block) {
+        if (block.height == 0) {
+            return DEFINED;
+        }
+
+All blocks within a retarget period have the same state. This means that if
+floor(block1.height / 2016) = floor(block2.height / 2016), they are guaranteed to have the same state for every
+deployment.
+
+        if ((block.height % 2016) != 0) {
+            return GetStateForBlock(block.parent);
+        }
+
+Otherwise, the next state depends on the previous state:
+
+        switch (GetStateForBlock(GetAncestorAtHeight(block, block.height - 2016))) {
+
+We remain in the initial state until either we pass the start time or the timeout. GetMedianTimePast in the code below
+refers to the median nTime of a block and its 10 predecessors. The expression GetMedianTimePast(block.parent) is
+referred to as MTP in the diagram above, and is treated as a monotonic clock defined by the chain.
+
+        case DEFINED:
+            if (GetMedianTimePast(block.parent) >= timeout) {
+                return (lockinontimeout == true) ? LOCKED_IN : FAILED;
+            }
+            if (GetMedianTimePast(block.parent) >= starttime) {
+                return STARTED;
+            }
+            return DEFINED;
+
+After a period in the STARTED state, if we're past the timeout, we switch to LOCKED_IN or FAILED. If not, we tally the bits set,
+and transition to LOCKED_IN if a sufficient number of blocks in the past period set the deployment bit in their
+version numbers. The threshold is ≥1916 blocks (95% of 2016), or ≥1512 for testnet (75% of 2016).
+The transition to FAILED takes precendence, as otherwise an ambiguity can arise.
+There could be two non-overlapping deployments on the same bit, where the first one transitions to LOCKED_IN while the
+other one simultaneously transitions to STARTED, which would mean both would demand setting the bit.
+
+Note that a block's state never depends on its own nVersion; only on that of its ancestors.
 
         case STARTED:
-            // BIP8/9 specification follows
             if (GetMedianTimePast(block.parent) >= timeout) {
-                // implementation detail: if flag set, BIP8 workflow, else BIP9 workflow.
-                return (fLockInOnTimeout == true) ? THRESHOLD_LOCKED_IN : THRESHOLD_FAILED
+                return (lockinontimeout == true) ? LOCKED_IN : FAILED;
             }
             int count = 0;
             walk = block;
@@ -52,6 +136,38 @@ During the STARTED state if the '''lockinontimeout''' is set to true, the state
             }
             return STARTED;
 
+After a retarget period of LOCKED_IN, we automatically transition to ACTIVE.
+
+        case LOCKED_IN:
+            return ACTIVE;
+
+And ACTIVE and FAILED are terminal states, which a deployment stays in once they're reached.
+
+        case ACTIVE:
+            return ACTIVE;
+
+        case FAILED:
+            return FAILED;
+        }
+    }
+
+'''Implementation'''
+It should be noted that the states are maintained along block chain
+branches, but may need recomputation when a reorganization happens.
+
+Given that the state for a specific block/deployment combination is completely determined by its ancestry before the
+current retarget period (i.e. up to and including its ancestor with height block.height - 1 - (block.height % 2016)),
+it is possible to implement the mechanism above efficiently and safely by caching the resulting state of every multiple-of-2016
+block, indexed by its parent.
+
+===Warning mechanism===
+
+To support upgrade warnings, an extra "unknown upgrade" is tracked, using the "implicit bit" mask = (block.nVersion & ~expectedVersion) != 0. Mask will be non-zero whenever an unexpected bit is set in nVersion.  Whenever LOCKED_IN for the unknown upgrade is detected, the software should warn loudly about the upcoming soft fork. It should warn even more loudly after the next retarget period (when the unknown upgrade is in the ACTIVE state).
+
+===getblocktemplate changes===
+
+BIP 8 is compatible with and reuses the GBT changes from BIP 9.
+
 === Reference implementation ===
 
 https://github.com/bitcoin/bitcoin/compare/master...shaolinfry:bip-uaversionbits
diff --git a/bip-0008/states.png b/bip-0008/states.png
index 8d3ca71156cc4b124ae915375251892e724c455b..828757365d9b63398812aba25b54713dd17e9112 100644
GIT binary patch
literal 20891
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

diff --git a/bip-0008/states.svg b/bip-0008/states.svg
new file mode 100644
index 00000000..56afd154
--- /dev/null
+++ b/bip-0008/states.svg
@@ -0,0 +1,51 @@
+
+	
+		
+		
+			
+		
+	
+
+	
+	DEFINED
+	
+	
+		starttime <= MTP < timeout
+	
+	STARTED
+	
+	
+		(lockinontimeout == false) AND (MTP < timeout) AND (threshold reached)
+		OR
+		(lockinontimeout == true) AND ((MTP >= timeout) OR (threshold reached))
+	
+	LOCKED_IN
+	
+		Always
+	
+	ACTIVE
+	
+
+	
+	FAILED
+	
+	
+		timeout <= MTP
+	
+		(lockinontimeout == false) AND (timeout <= MTP)
+