Update Bip300 for consistency with latest code

1 files changed, 100 insertions, 109 deletions

diff --git a/bip-0300.mediawiki b/bip-0300.mediawiki
index 3cecd85..03802aa 100644
--- a/bip-0300.mediawiki
+++ b/bip-0300.mediawiki
@@ -15,7 +15,7 @@
 
 ==Abstract==
 
-In Bip300, txns are not signed via cryptographic key. Instead, they are "signed" by the accumulation of hashpower over time.
+In Bip300, txns are not signed via cryptographic key. Instead, they are "signed" by hashpower, over time. Like a big multisig, 13150-of-26300, where each block is a new "signature".
 
 Bip300 emphasizes slow, transparent, auditable transactions which are easy for honest users to get right and very hard for dishonest users to abuse. The chief design goal for Bip300 is ''partitioning'' -- users may safely ignore Bip300 txns if they want to (or Bip300 entirely).
 
@@ -27,7 +27,7 @@ See [http://www.drivechain.info/ this site] for more information.
 
 As Reid Hoffman [https://blockstream.com/2015/01/13/en-reid-hoffman-on-the-future-of-the-bitcoin-ecosystem/ wrote in 2014]: "Sidechains allow developers to add features and functionality to the Bitcoin universe without actually modifying the Bitcoin Core code...Consequently, innovation can occur faster, in more flexible and distributed ways, without losing the synergies of a common platform with a single currency."
 
-Coins such as Namecoin, Monero, ZCash, and Sia, offer features that Bitcoiners cannot access -- not without selling their BTC to invest in a rival monetary unit. According to [https://coinmarketcap.com/charts/#dominance-percentage coinmarketcap.com], there is now more value *outside* the BTC protocol than within it. According to [https://cryptofees.info/ cryptofees.info], 10x more txn fees are paid outside the BTC protocol, than within it.
+Today, coins such as Namecoin, Monero, ZCash, and Sia, offer features that Bitcoiners cannot access -- not without selling their BTC to invest in a rival monetary unit. According to [https://coinmarketcap.com/charts/#dominance-percentage coinmarketcap.com], there is now more value *outside* the BTC protocol than within it. According to [https://cryptofees.info/ cryptofees.info], 15x more txn fees are paid outside the BTC protocol, than within it.
 
 Software improvements to Bitcoin rely on developer consensus -- BTC will pass on a good idea if it is even slightly controversial. Development is slow: we are now averaging one major feature every 5 years.
 
@@ -37,7 +37,9 @@ BTC can copy every useful technology, as soon as it is invented; scamcoins lose
 
 ==Specification==
 
-Bip300 allows for six new blockchain messages:
+===Overview===
+
+Bip300 allows for six new blockchain messages (these have consensus significance):
 
 * M1. "Propose New Sidechain"
 * M2. "ACK Proposal"
@@ -48,22 +50,12 @@ Bip300 allows for six new blockchain messages:
 
 Nodes organize those messages into two caches:
 
-* D1. "Escrow_DB" -- tracks the 256 Hashrate Escrows (Escrows slots that a sidechain can live in).
-* D2. "Withdrawal_DB" -- tracks the withdrawal-Bundles (coins leaving a Sidechain).
-
-We will cover:
-
-# Adding Sidechains (D1, M1, M2)
-# Approving Withdrawals (D2, M3, M4)
-# Depositing and Withdrawing (M5, M6)
-
-=== Adding Sidechains (D1, M1, M2) ===
-
-
-==== D1 -- "Escrow_DB" ====
+* D1. "The Sidechain List", which tracks the 256 Hashrate Escrows (Escrows are slots that a sidechain can live in).
+* D2. "The Withdrawal List", which tracks the withdrawal-Bundles (coins leaving a Sidechain).
 
-The table below enumerates the new database fields, their size in bytes, and their purpose. A sidechain designer is free to choose any value for these.
+==== D1 (The Sidechain List) ====
 
+D1 is a list of active sidechains. D1 is updated via M1 and M2.
 
 {| class="wikitable"
 |- style="font-weight:bold; text-align:center; vertical-align:middle;"
@@ -133,10 +125,61 @@ The table below enumerates the new database fields, their size in bytes, and the
 | Of the CTIP, the second element of the pair: the Index. See #11 above.
 |}
 
-D1 is updated via M1 and M2.
 
+==== D2 (The Withdrawal List) ====
+
+D2 lists withdrawal-attempts. If these attempts succeed, they will pay coins "from" a Bip300-locked UTXO, to new UTXOs controlled by the withdrawing-user. Each attempt pays out many users, so we call these withdrawal-attempts "Bundles".
+
+D2 is driven by M3, M4, M5, and M6. Those messages enforce the following principles:
+
+# The Bundles have a canonical order (first come first serve).
+# From one block to the next, every "Blocks Remaining" field decreases by 1.
+# When "Blocks Remaining" reaches zero the Bundle is removed.
+# From one block to the next, the value in "ACKs" may either increase or decrease, by a maximum of 1 (see M4).
+# If a Bundle's "ACKs" reach 13150 or greater, it "succeeds" and its corresponding M6 message can be included in a block.
+# If the M6 of a Bundle is paid out, it is also removed.
+# If a Bundle cannot possibly succeed ( 13500 - "ACKs"  >  "Blocks Remaining" ), it is removed immediately.
+
+
+{| class="wikitable"
+! Field No.
+! Label
+! Type
+! Description / Purpose
+|-
+| 1
+| Sidechain Number
+| uint8_t
+| Links the withdrawal-request to a specific hashrate escrow.
+|-
+| 2
+| Bundle Hash
+| uint256
+| A withdrawal attempt. Specifically, it is a "blinded transaction id" (ie, the double-Sha256 of a txn that has had two fields zeroed out, see M6) of a txn which could withdraw funds from a sidechain.
+|-
+| 3
+| ACKs (Work Score)
+| uint16_t
+| The current ACK-counter, which is the total number of ACKs (the PoW that has been used to validate the Bundle).
+|-
+| 4
+| Blocks Remaining (Age)
+| uint16_t
+| The number of blocks which this Bundle has remaining to accumulate ACKs
+|}
+
+
+
+
+
+
+=== The Six New Bip300 Messages ===
+
+First, how are new sidechains created?
+
+They are first proposed (with M1), and later acked (with M2). This process resembles Bip9 soft fork activation.
 
-==== M1 -- "Propose New Sidechain" ====
+==== M1 and M2 (Adding a new sidechain) ====
 
 Examples:
 
@@ -159,140 +202,93 @@ M1 is a coinbase OP Return output containing the following:
       32-byte hashID1
       20-byte hashID2
 
-M1 is used in conjunction with M2.
-
-==== M2 -- "ACK Sidechain Proposal" ====
+M2 is a coinbase OP Return output containing the following:
 
     1-byte - OP_RETURN (0x6a)
     4-byte - Message header (0xD6E1C5BF)
     32-byte - sha256D hash of sidechain's serialization
 
-==== M1/M2 Validation Rules ====
+The new M1/M2 validation rules are:
 
 # Any miner can propose a new sidechain at any time. This procedure resembles BIP 9 soft fork activation: the network must see a properly-formatted M1, followed by "acknowledgment" of the sidechain in 90% of the following 2016 blocks.
 # It is possible to "overwrite" a sidechain. This requires more ACKs -- 50% of the following 26300 blocks must contain an M2. The possibility of overwrite, does not change the security assumptions (because we already assume that users perform extra-protocolic validation at a rate of 1 bit per 26300 blocks).
 
 
-=== Approving Withdrawals (D2, M3, M4) ===
+==== M3 and M4 (Withdrawing Coins) ====
 
 Withdrawals in Bip300 (ie, "M6"), are very significant. So, we will first discuss how these are approved/rejected -- a process involving M3, M4, and D2.
 
-==== What are Bundles? ====
-
-All Bip300 withdrawals take the form of “Bundles” (formerly known as “WT^s”) -- named because they "bundle up" many individual withdrawal-requests into one single rare layer1 transaction.
-
-This bundle either pays all of the withdrawals out, or else it fails (and pays nothing out). Bip300 / layer 1 does not assemble Bundles (the sidechain developer does this in a manner of their choosing).
-
-Bundles are identified by a 32-byte hash, which aspires to be the TxID of M6. Unfortunately, the Bundle-hash and M6-TxID cannot match exactly, since the first input to M6 is a CTIP which is constantly changing. So, we must accomplish a task, which is conceptually similar to AnyPrevOut (BIP 118). We define a "blinded TxID" as a way of hashing a txn, in which some bytes are first overwritten with zeros. In our case, these bytes are the first input and the first output.
-
-D2 controls Bundles, and is driven by M3, M4, M5, and M6.
-
-
-==== D2 -- "Withdrawal_DB" ====
-
-
-{| class="wikitable"
-! Field No.
-! Label
-! Type
-! Description / Purpose
-|-
-| 1
-| Sidechain Number
-| uint8_t
-| Links the withdrawal-request to a specific hashrate escrow.
-|-
-| 2
-| Bundle Hash
-| uint256
-| A withdrawal attempt. Specifically, it is a "blinded transaction id" (ie, the double-Sha256 of a txn that has had two fields zeroed out, see M6) of a txn which could withdraw funds from a sidechain.
-|-
-| 3
-| ACKs (Work Score)
-| uint16_t
-| The current ACK-counter, which is the total number of ACKs (the PoW that has been used to validate the Bundle).
-|-
-| 4
-| Blocks Remaining (Age)
-| uint16_t
-| The number of blocks which this Bundle has remaining to accumulate ACKs
-|}
-
-A hash of D2 exists in each coinbase txn, and has consensus-significance.
+===== What are Bundles? =====
 
-==== D2 Validation Rules ====
+All Bip300 withdrawals take the form of “Bundles” -- named because they "bundle up" many individual withdrawal-requests into one single rare layer1 transaction.
 
-# The D2 hash commitment must be in each block (unless D2 is blank).
-# The Bundles must be listed in a canonical order (so that the hashes match).
-# From one block to the next, "Age" fields must increase by exactly 1 (ie, Blocks Remaining decreases by 1).
-# Bundles are stored in D2 until they fail (which occurs at "Age" = "MaxAge"), or they succeed (Bundle is paid out).
-# From one block to the next, the value in the ACKs field (ACK-counter) can increase or decrease by a maximum of 1 (see below).
+This bundle either pays all of the withdrawals out, or else it fails (and pays nothing out). Bip300 / layer 1 does not assemble Bundles (the sidechain developer does this, in a manner of their choosing).
 
-If a Bundle succeeds (in D2), it "becomes" an M6 message and is included in a block.
+Bundles are identified by a 32-byte hash, which aspires to be the TxID of M6. Unfortunately, the Bundle-hash and M6-TxID cannot match exactly, since the first input to M6 is a CTIP which is constantly changing. So, we must accomplish a task, which is conceptually similar to AnyPrevOut (BIP 118). We define a "blinded TxID" as a way of hashing a txn, in which some bytes are first overwritten with zeros. In our case, the precise "overwritten bytes" are: the first input and the first output.
 
-So, first: how do we add a Bundle to D2?
+===== M3 (Propose a Bundle) =====
 
-==== M3 -- "Propose Bundle" ====
-
-
-Nodes will add an entry to D2 if there is a coinbase output with the following:
+M3 is a coinbase OP Return output containing the following:
 
     1-byte - OP_RETURN (0x6a)
     4-byte - Commitment header (0xD45AA943)
     32-byte - The Bundle hash, to populate a new D2 entry
 
 
-==== M3 Validation Rules ====
+The new validation rules pertaining to M3 are:
 
-# If the network detects a properly-formatted M3, it must add an entry to D2 in the very next block. The starting Blocks Remaining value is 26,299. The starting ACKs count is 1.
+# If the network detects a properly-formatted M3, it must add an entry to D2 in the very next block. The starting "Blocks Remaining" value is 26,299. The starting ACKs count is 1.
 # Each block can only contain one M3 per sidechain.
 
 Once a Bundle is in D2, how can we give it enough ACKs to make it valid?
 
-==== M4 -- "ACK Withdrawal" ====
+===== M4 (ACK Withdrawals) =====
 
-From one block to the next, "ACKs" can only change as follows:
+M4 is a coinbase OP Return output containing the following:
 
-* The ACK-counter of any Bundle can only change by (-1,0,+1).
-* Within a sidechain-group, upvoting one Bundle ("+1") requires you to downvote all other Bundles in that group. However, the minimum ACK-counter is zero.
-* While only one Bundle can be upvoted at once; the whole group can all be unchanged at once ("abstain"), and they can all be downvoted at once ("alarm").
+    1-byte - OP_RETURN (0x6a)
+    4-byte - Commitment header (0xD77D1776)
+    1-byte - Version
+    n-byte - The vector describing the "upvoted" bundle-choice, for each sidechain.
 
-M4 does not need to be explicitly transmitted. It can simply be inferred from the new state of D2. M4 can therefore be improved over time, without affecting consensus.
+Version 0x01 uses one byte per sidechain, and applies in most cases. Version 0x02 uses two bytes per sidechain and applies in unusual situations where at least one sidechain has more than 256 distinct withdrawal-bundles in progress at one time. If a sidechain has no pending bundles, then it is skipped over when M4 is created and parsed.
 
-Nonetheless, one option for explicit transmission of M4 is [https://github.com/drivechain-project/mainchain/blob/8901d469975752d799b6a7a61d4e00a9a124028f/src/validation.cpp#L3735-L3790  in our code].
+The upvote vector will code "abstain" as 0xFF (or 0xFFFF); it will code "alarm" as 0xFE (or 0xFFFE). Otherwise it simply indicates which withdrawal-bundle in the list, is the one to be "upvoted". For example, if there are two sidechains, and we wish to upvote the 7th bundle on sidechain #1 plus the 4th bundle on sidechain #2, then the vector would be 0x0704.
 
-Often, M4 does not need to be transmitted at all. If there are n Sidechains and m Withdrawals-per-sidechain, then there are (m+2)^n total candidates for the next D2. So, when m and n are low, all of the possible D2s can be trivially computed in advance.
+The M4 message will be invalid (and invalidate the block), if it tries to upvote a Bundle that doesn't exist (for example, trying to upvote the 7th bundle on sidechain #2, when sidechain #2 has only three bundles). If there are no Bundles at all (no one is trying to withdraw from any sidechain), then *any* M4 message present in the coinbase will be invalid. If M4 is NOT present in a block, then it is treated as "abstain".
 
-Miners can impose a "soft limit" on m, blocking new withdrawal-attempts until previous ones expire. Even if they fail to do this, a a worst-case scenario of n=200 and m=1,000, honest nodes can communicate the M4 with ~25 KB per block [4+1+1+(200\*(1000+1+1)/8)]. 
+The ACKed withdrawal will gain one point for its ACK field. Therefore, the ACK-counter of any Bundle can only change by (-1,0,+1).
 
-Finally, we give Deposits and Withdrawals.
+Within a sidechain-group, upvoting one Bundle ("+1") requires you to downvote all other Bundles in that group. However, the minimum ACK-counter is zero. While only one Bundle can be upvoted at once; the whole group can all be unchanged at once ("abstain"), and they can all be downvoted at once ("alarm").
 
-=== Deposits and Withdrawals (M5, M6) ===
+Finally, we describe Deposits and Withdrawals.
 
-Both M5 and M6 are regular Bitcoin txns. They are identified, as Deposits/Withdrawals, when they select one of the special CTIP UTXOs as one of their inputs (see D1).
+==== M5 and M6 (User's Deposits and Withdrawals) ====
 
+Both M5 and M6 are regular Bitcoin txns. They are identified, as Deposits/Withdrawals, when they select one of the special CTIP UTXOs as one of their inputs (see D1).
 
 All of a sidechain’s coins, are stored in one UTXO. (Deposits/Withdrawals never cause UTXO bloat.) So, each Deposit/Withdrawal must select a CTIP, and generate a new CTIP (this is tracked in D1, above).
 
-If the from-CTIP-to-CTIP quantity of coins goes '''up''', (ie, if the user is adding coins), then the txn is treated as a Deposit (M5). Else it is treated as a Withdrawal (M6). See [https://github.com/drivechain-project/mainchain/blob/8901d469975752d799b6a7a61d4e00a9a124028f/src/validation.cpp#L668-L781 here].
+If the from-CTIP-to-CTIP quantity of coins goes '''up''', (ie, if the user is adding coins), then the txn is treated as a Deposit (M5). Else it is treated as a Withdrawal (M6). See [https://github.com/drivechain-project/mainchain/blob/e37b008fafe0701b8313993c8b02ba41dc0f8a29/src/validation.cpp#L667-L780 here].
 
 
-==== M5. "Make a Deposit" -- a transfer of BTC from-main-to-side ====
+===== M5 (Make a Deposit) -- a transfer of BTC from-main-to-side =====
 
 As far as mainchain consensus is concerned, all deposits to a sidechain are always valid.
 
-==== M6. "Execute Withdrawal" -- a transfer of BTC from-side-to-main ====
+===== M6 (Execute a Withdrawal) -- a transfer of BTC from-side-to-main =====
 
 We come, finally, to the critical matter: where users can take their money *out* of the sidechain.
 
 In each block, a Bundle in D2 is considered "approved" if its "ACK-counter" value meets the threshold (13,150).
 
+If a Bundle is approved, then its associated M6 can be included in a block.
 
-The Bundle must meet all these criteria:
+An M6 must meet all these criteria, else it be invalid:
 
-# "Be ACKed" -- The "blinded TxID" of this txn must be a member of the "approved candidate" set in the D2 of this block.
-# "Return Change to Account" -- TxOut0 must pay coins back to the sidechain's CTIP.
-# "Return *all* Change to Account" -- Sum of inputs must equal the sum of outputs. No traditional tx fee is possible.
+# "Be ACKed" -- The "blinded TxID" of the M6 must match an approved Bundle. In other words, an M6 can only be included in a block, after the 3+ month (13150 block) ceremony.
+# "Return Change to Account" -- TxOut0 must be paid back to the sidechain's Bip300 script. In other words, since we select the UTXO with *all* of the money, we must make sure we pay all of the non-withdrawn money back into the sidechain.
+# "Return *all* Change to Account" -- Sum of all inputs must equal the sum of all outputs. No traditional tx fee is possible. (The txn fee is paid via an OP TRUE output in the Bundle -- this allows the withdraw-ers to set the fee via the Bundle, and ACK it over 3 months like everything else.)
 
 
 ==Backward compatibility==
@@ -304,25 +300,20 @@ As a soft fork, older software will continue to operate without modification. No
 
 ==Deployment==
 
+This BIP will be deployed via UASF-style block height activation.
 
-This BIP will be deployed by "version bits" BIP9 with the name "hrescrow" and using bit 4.
 
-<pre>
-// Deployment of Drivechains (BIPX, BIPY)
-consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].bit = 4;
-consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nStartTime = 1642276800; // January 15th, 2022.
-consensus.vDeployments[Consensus::DEPLOYMENT_DRIVECHAINS].nTimeout = 1673812800; // January 15th, 2023.
-</pre>
 ==Reference Implementation==
 
+See: https://github.com/drivechain-project/mainchain
 
-See: https://github.com/DriveNetTESTDRIVE/DriveNet
-
-Also, for interest, see an example sidechain here: https://github.com/drivechain-project/bitcoin/tree/sidechainBMM
+Also, for interest, see an example sidechain here: https://github.com/drivechain-project/sidechains/tree/testchain
 
 
 ==References==
 
+https://github.com/drivechain-project/mainchain
+https://github.com/drivechain-project/sidechains/tree/testchain
 See http://www.drivechain.info/literature/index.html