clearer, more failure details, + use OP_TRUE

1 files changed, 176 insertions, 63 deletions

diff --git a/bip-0300.mediawiki b/bip-0300.mediawiki
index 20d1936..6ee0760 100644
--- a/bip-0300.mediawiki
+++ b/bip-0300.mediawiki
@@ -75,54 +75,44 @@ D1 is a list of active sidechains. D1 is updated via M1 and M2.
 | Version number.
 |-
 | 3
-| String KeyID
-| string
-| Used to derive all sidechain deposit addresses.
-|-
-| 4<br />
-| Sidechain Private Key
-| string
-| The private key of the sidechain deposit script.
-|- style="vertical-align:middle;"
-| 5<br />
-| ScriptPubKey
-| CScript
-| Where the sidechain coins go. This always stays the same, even though the CTIP (UTXO) containing the coins is always changing.
-|- style="vertical-align:middle;"
-| 6
 | Sidechain Name
 | string
 | A human-readable name of the sidechain.
 |- style="vertical-align:middle;"
-| 7
+| 4
 | Sidechain Description
 | string
 | A human-readable name description of the sidechain.
 |- style="vertical-align:middle;"
-| 8
+| 5
 | Hash1 - tarball hash
 | uint256
 | Intended as the sha256 hash of the tar.gz of the canonical sidechain software. (This is not enforced anywhere by Bip300, and is for human purposes only.)
 |- style="vertical-align:middle;"
-| 9
+| 6
 | Hash2 - git commit hash
 | uint160
 | Intended as the git commit hash of the canonical sidechain node software. (This is not enforced anywhere by Bip300, and is for human purposes only.)
 |-
-| 10
+| 7
 | Active
 | bool
 | Does this sidechain slot contain an active sidechain?<br />
 |- style="vertical-align:middle;"
-| 11
-| "CTIP" -- Part 1 "TxID"
+| 8
+| Activation Status
+| int , int
+| The age of the proposal (in blocks); and the number of "fails" (a block that does NOT ack the sidechain). This is discarded after the sidechain activates.
+|- style="vertical-align:middle;"
+| 9
+| "CTIP" -- "TxID"
 | uint256
-| The CTIP, or "Critical (TxID, Index) Pair" is a variable for keeping  track of where the sidechain's money is (ie, which member of the UTXO set).
+| A UTXO that holds the sidechain's money. (Part 1 of 2).
 |- style="vertical-align:middle;"
-| 12
-| "CTIP" -- Part 2 "Index"
+| 10
+| "CTIP" -- "vout"
 | int32_t
-| Of the CTIP, the second element of the pair: the Index. See #11 above.
+| A UTXO that holds the sidechain's money. (Part 2 of 2).
 |}
 
 
@@ -138,7 +128,7 @@ D2 is driven by M3, M4, M5, and M6. Those messages enforce the following princip
 # 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.
+# If a Bundle cannot possibly succeed ( 13150 - "ACKs"  >  "Blocks Remaining" ), it is removed immediately.
 
 
 {| class="wikitable"
@@ -158,19 +148,21 @@ D2 is driven by M3, M4, M5, and M6. Those messages enforce the following princip
 | 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)
+| Work Score (ACKs)
 | uint16_t
-| The current ACK-counter, which is the total number of ACKs (the PoW that has been used to validate the Bundle).
+| How many miner upvotes a withdrawal has. Starts at 0. Fastest possible rate of increase is 1 per block.
 |-
 | 4
-| Blocks Remaining (Age)
+| Blocks Remaining
 | uint16_t
-| The number of blocks which this Bundle has remaining to accumulate ACKs
+| How long this bundle has left to live (measured in blocks). Starts at 26,300 and counts down.
 |}
 
+D1, with all 256 slots active, reaches a maximum size of: 256 * ( 1 (map index) + 36 (outpoint) + 8 (amount) ) = 11,520 bytes.
 
+D2, under normal conditions, would reach a size of: (38 bytes per withdrawal * 256 sidechains) = 9,728 bytes.
 
-
+It is possible to spam D2. A miner can add the max M3s (256) every block, forever. This costs 9,728 on-chain bytes per block, an opportunity cost of about 43 txns. It results in no benefit to the miner whatsoever. D2 will eventually hit a ceiling at 124.5568 MB. (By comparison, the Bitcoin UTXO set is about 7,000 MB.) When the attacker stops, D2 will eventually shrink back down to 9,728 bytes.
 
 
 === The Six New Bip300 Messages ===
@@ -188,19 +180,22 @@ M1 is a coinbase OP Return output containing the following:
     N-byte - The serialization of the sidechain.
       1-byte nSidechain
       4-byte nVersion
-      x-byte strKeyID
-      x-byte strPrivKey
-      x-byte scriptPubKey
       x-byte title
       x-byte description
       32-byte hashID1
       20-byte hashID2
 
-===== Examples =====
 
-<img src="bip-0300/m1-gui.jpg?raw=true" align="middle"></img>
+M1 is invalid if:
+
+* It would add a duplicate entry to D1.
+* There is already an M1 in this block.
+* The sidechain serialization does not parse.
+
+Otherwise:
+
+* A new entry is added to D1, whose initial Activation Status is (age=0, fails=0).
 
-<img src="bip-0300/m1-cli.png?raw=true" align="middle"></img>
 
 ==== M2 -- ACK Sidechain Proposal ====
 
@@ -208,14 +203,30 @@ 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
+    32-byte - the sha256D hash of sidechain's serialization
+
+
+M2 is ignored if it doesn't parse, or if it is for a sidechain that doesn't exist.
+
+M2 is invalid if:
+
+* An M2 is already in this block.
+* It tries to ACK two different M1s for the same slot.
 
-===== Notes =====
+Otherwise: 
 
-The new M1/M2 validation rules are:
+* The sidechain is "ACK"ed and does NOT get a "fail" for this block. (As it otherwise would.)
 
-# Any miner can propose a new sidechain (M1) 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 (M2) in 90% of the following 2016 blocks.
-# Bip300 comes with only 256 sidechain-slots. If all are used, it is possible to "overwrite" a sidechain. This requires vastly more M2 ACKs -- 50% of the following 26300 blocks must contain an M2. The possibility of overwrite, does not change the Bip300 security assumptions (because we already assume that the sidechain is vulnerable to miners, at a rate of 1 catastrophe per 13150 blocks).
+A sidechain fails to activate if:
+
+* If the slot is unused: during the next 2016 blocks, it accumulates 201 fails. (Ie, 90% threshold).
+* If the slot is in use: during the next 26,300 blocks, it accumulates 13,150 fails. (Ie, 50% threshold).
+
+( Thus we can overwrite a used sidechain slot. Bip300 sidechains are already vulnerable to one catastrophe per 13150 blocks (the invalid withdrawal) so this slot-overwrite option does not change the security assumptions. )
+
+Otherwise, the sidechain activates (Active is set to TRUE).
+
+In the block in which the sidechain activates, the coinbase MUST include at least one 0-valued OP_TRUE. This output becomes the initial CTIP for the sidechain.
 
 
 
@@ -227,7 +238,7 @@ For an M6 to be valid, it must be first "prepped" by one M3 and then 13,150+ M4s
 
 ===== What are Bundles? =====
 
-Sidechain withdrawals take the form of “Bundles” -- named because they "bundle up" many individual withdrawal-requests into a single rare layer1 transaction.
+Sidechain withdrawals take the form of "Bundles" -- named because they "bundle up" many individual withdrawal-requests into a single rare layer1 transaction.
 
 Sidechain full nodes aggregate the withdrawal-requests into a big set. The sidechain calculates what M6 would have to look like, to pay all of these withdrawal-requests out. Finally, the sidechain calculates what the hash of this M6 would be. This 32-byte hash identifies the Bundle.
 
@@ -248,11 +259,18 @@ 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
+    1-byte - nSidechain (the slot number)
+
+M3 is ignored if it does not parse, or if it is for a sidechain that doesn't exist.
 
-The new validation rules pertaining to M3 are:
+M3 is invalid if:
 
-# 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.
+* This block already has an M3 for that nSidechain.
+* A bundle with this hash is already in D2.
+* A bundle with this hash already paid out.
+* A bundle with this hash was rejected in the past.
+
+Otherwise: M3 adds an entry to D2, with initial ACK score = 1 and initial Blocks Remaining = 26,299. (Merely being added to D2, does count as your first upvote.)
 
 Once a Bundle is in D2, how can we give it enough ACKs to make it valid?
 
@@ -263,44 +281,139 @@ M4 is a coinbase OP Return output containing the following:
     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.
+    n-byte - The "upvote vector" -- describes which bundle-choice is "upvoted", for each sidechain.
+
+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 upvote vector would be { 07, 04 }. And M4 would be [0x6A,D77D1776,00,0006,0003].
 
-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. Other interesting versions are possible: 0x03 might say "do exactly what was done in the previous block" (which could consume a fixed 6 bytes total, regardless of how many sidechains). 0x04 might say "upvote everyone who is clearly in the lead" (which also would require a mere 6 bytes), and so forth.
+The version number allows us to shrink the upvote vector in many cases. Version 0x00 requires a full two bytes per sidechain, but it always works. Version 0x01 uses half that (one byte per sidechain), and it works while all sidechains have fewer than 255 disputed withdrawals (ie, 99.99%+ of the time). Version 0x02 uses zero bytes (ie, 6 bytes for the whole M4) and sets this block's M4 equal to the previous block's M4. Version 0x03 upvotes only those withdrawals that are leading their rivals by at least 50 votes.
 
 If a sidechain has no pending bundles, then it is skipped over when M4 is created and parsed.
 
-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.
+For example, an upvote vector of { 2 , N/A, 1 } would be represented as [0x6A,D77D1776,01,00,00]. It means: "upvote the first bundle in sidechain #1; and the first bundle in sidechain #3" (iff sidechains #2 has no bundles proposed).
 
-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".
+An upvote vector of { N/A, N/A, 4 } would be [0x6A,D77D1776,01,03].
 
-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).
 
-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").
+The M4 message will be invalid (and invalidate the block), if:
 
-Finally, we describe Deposits and Withdrawals.
+*  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.)
+* There are no Bundles at all, from any sidechain.
+
+If M4 is NOT present in a block, then it is treated as "abstain".
+
+If M4 is present and valid: each withdrawal-bundle that is ACKed, will gain one upvote.
+
+Important: Within a sidechain-group, upvoting one Bundle ("+1") automatically downvotes ("-1") 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").
+
+For example:
+
+{| class="wikitable" 
+|-
+! SC#
+! Bundle Hash
+! ACKs
+! Blocks Remaining
+|-
+| 1
+| h1
+| 45
+| 22,109
+|-
+| 1
+| h2
+| 12
+| 22,008
+|-
+| 2
+| h3
+| 13
+| 22,999
+|-
+| 2
+| h4
+| 8
+| 23,550<br />
+|-
+| 2
+| h5
+| 2
+| 22,560
+|}
+
+
+...in block 900,000 could become...
+
+
+{| class="wikitable" 
+|-
+! SC#
+! Bundle Hash
+! ACKs
+! Blocks Remaining
+|-
+| 1
+| h1
+| 46
+| 22,108
+|-
+| 1
+| h2
+| 11
+| 22,007
+|-
+| 2
+| h3
+| 12
+| 22,998
+|-
+| 2
+| h4
+| 9
+| 23,549<br />
+|-
+| 2
+| h5
+| 1
+| 22,559
+|}
+
+...if M4 were [0x6A,D77D1776,00,0000,0001].
 
 
+Finally, we describe Deposits and Withdrawals.
+
 ==== M5 -- Deposit BTC to Sidechain ====
 
-Both M5 and M6 are regular Bitcoin txns. They are distinguished from regular txns (non-M5 non-M6 txns), when they select one of the special Bip300 CTIP UTXOs as one of their inputs (see D1).
+Each sidechain stores all its BTC in one UTXO, called the "CTIP".
 
-All of a sidechain’s coins, are stored in one UTXO, called the "CTIP". Every time a deposit or withdrawal is made, the CTIP changes. Each deposit/withdrawal will select the sidechains CTIP, and generate a new CTIP. (Deposits/Withdrawals never cause UTXO bloat.) The current CTIP is cached in D1 (above).
+By definition, an M5 is a transaction which spends the CTIP and '''increases''' the quantity of coins. An M6 is a transaction which spends the CTIP and '''decreases''' the quantity of coins in the CTIP. See [https://github.com/LayerTwo-Labs/mainchain/blob/391ab390adaa19f92871d769f8e120ca62c1cf14/src/validation.cpp#L688-L801 here].
 
-If the '''quantity of coins''', in the from-CTIP-to-CTIP transaction, 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].
+Every time a deposit/withdrawal is made, the old CTIP is spent and a new one is created. (Deposits/Withdrawals never cause UTXO bloat.) At all times, the CTIP of each sidechain is cached in D1 (above).
+
+Every M5 is valid, as long as:
+
+* It has at least one OP_TRUE output -- this becomes the new CTIP.
+* The new CTIP has '''more''' coins in it, than before.
 
-As far as mainchain consensus is concerned, all deposits to a sidechain are always valid.
 
 ==== M6 -- Withdraw BTC from a Sidechain ====
 
 We come, finally, to the critical matter: where users can take their money *out* of the sidechain.
 
-First, M6 must obey the same CTIP rules of M5 (see immediately above).
+M6 is invalid if:
+
+* The blinded hash of M6 does NOT match one of the approved Bundle-hashes.  (In other words: M6 must first be approved by 13,150 upvotes.)
+* The first output of M6 is NOT an OP_TRUE. (This OP_TRUE becomes the new CTIP. In other words: all non-withdrawn coins are paid back to the sidechain.)
+* The second output is NOT an OP_RETURN script of exactly 10 bytes, of which 8 bytes are a serialized Bitcoin amount.
+* The txn fee of M6 is NOT exactly equal to the amount of the previous bullet point.
+
+Else, M6 is valid. 
+
+(The point of the latter two bullet points, is to allow the bundle hash to cover the L1 transaction fee.)
 
-Second, an M6 is only valid for inclusion in a block, if its blinded TxID matches an "approved" Bundle hash (ie, one with an ACK score of 13150+). In other words, an M6 can only be included in a block, after the 3+ month (13150 block) ceremony.
 
-Third, M6 must meet two accounting criteria, lest it be invalid:
-# "Give change back to Escrow" -- The first output, TxOut0, must be paid back to the sidechain's Bip300 script. In other words, all non-withdrawn coins must be paid back into the sidechain.
-# "No traditional txn fee" -- For this txn, the sum of all inputs must equal the sum of all outputs. No traditional tx fee is possible. (Of course, there is still a txn fee for miners: it is paid via an OP TRUE output in the Bundle.) We want the withdraw-ers to set the fee "inside" the Bundle, and ACK it over 3 months like everything else.
 
 
 ==Backward compatibility==
@@ -331,7 +444,7 @@ See http://www.drivechain.info/literature/index.html
 
 ==Credits==
 
-Thanks to everyone who contributed to the discussion, especially: ZmnSCPxj, Adam Back, Peter Todd, Dan Anderson, Sergio Demian Lerner, Chris Stewart, Matt Corallo, Sjors Provoost, Tier Nolan, Erik Aronesty, Jason Dreyzehner, Joe Miyamoto, Ben Goldhaber.
+Thanks to everyone who contributed to the discussion, especially: Luke Dashjr, ZmnSCPxj, Adam Back, Peter Todd, Dan Anderson, Sergio Demian Lerner, Chris Stewart, Matt Corallo, Sjors Provoost, Tier Nolan, Erik Aronesty, Jason Dreyzehner, Joe Miyamoto, Ben Goldhaber.
 
 
 ==Copyright==