8 The Stake System¶
Decred’s proof-of-stake layer lets holders of the currency lock funds in tickets. Every block draws a small set of tickets at random from the pool of live tickets; the holders of the drawn tickets publish votes that approve or disapprove the regular transactions of the block they vote on and express preferences on proposed rule changes. The next block is only valid if it carries votes from a majority of the drawn tickets. A ticket that is drawn but whose vote is not included is missed; a ticket that is never drawn eventually expires. The locked funds of missed and expired tickets are returned by a revocation.
This chapter specifies the three stake transaction types (ticket purchase, vote and revocation) byte for byte, the rules that tie their amounts to one another, the ticket database that every node maintains, the lottery that draws the winning tickets, and every block-level rule whose subject is a ticket, a vote or a revocation. Several neighboring subjects are specified elsewhere and only summarized here: the ticket price algorithm (stake difficulty) in Chapter 9; the value of the vote subsidy in Chapter 11; the treasury transactions that also live in the stake tree in Chapter 12; the meaning of the vote bits other than bit 0, and the vote version, in Chapter 13; the consequences of a disapproved block for its regular transactions in Chapter 10; the general transaction rules (sanity, fraud proofs, script execution, fees) in Chapter 7 and Chapter 6.
8.1 Overview¶
8.1.1 Terminology¶
- Stake tree
- The second of the two transaction lists of a block (the first is the regular tree). Every ticket purchase, vote and revocation, and every treasury transaction, is in the stake tree; no other transaction may be (Rule 8.34).
- Ticket
- A ticket purchase transaction (dcrd: SStx, “stake submission”). Its first output locks the ticket price under a script tagged
OP_SSTX. The ticket is identified by its transaction hash. - Stake difficulty
- The minimum ticket price, carried in the
SBitsfield of the block header and computed by the algorithm of Chapter 9. - Commitment
- An
OP_RETURNoutput of a ticket that names, for one funding input, the hash of the address that will receive that input’s share of the ticket’s eventual return, the amount contributed, and optional fee limits (Section 8.3.1). - Immature ticket
- A ticket that has been mined but has not yet entered the live ticket pool.
- Live ticket
- A ticket in the live ticket pool, eligible to be drawn.
- Winner
- One of the
TicketsPerBlocktickets drawn by the lottery run on block ; the winners of block are the only tickets that may vote in block , and their votes are votes on block . - Vote
- A vote transaction (dcrd: SSGen, “stake generation”) that spends a winning ticket, names the block it votes on, carries the vote bits, and pays the ticket price plus the vote subsidy to the ticket’s commitments.
- Stakebase
- The first input of a vote. It spends nothing and introduces the vote subsidy, much as a coinbase introduces the proof-of-work subsidy.
- Missed ticket
- A winner whose vote is not included in the next block.
- Expired ticket
- A live ticket that was not drawn within
TicketExpiryblocks of entering the pool. - Revocation
- A revocation transaction (dcrd: SSRtx, “stake revocation”) that spends a missed or expired ticket and returns the ticket price to the commitments.
8.1.2 Life of a ticket¶
Table 8.1 follows a ticket mined in the block at height through its life, using main-network parameter values. All heights are consequences of rules stated later in this chapter, which are referenced in the last column.
TicketMaturity , TicketExpiry )| Height | Event | Reference |
|---|---|---|
| Ticket purchase mined. The price is at least the stake difficulty in the header of block . | Rule 8.6 | |
The ticket enters the live pool while block is connected, provided StakeEnabledHeight. | Algorithm 8.9 | |
| First lottery that can draw it: the lottery run on block selects the winners for block . | Algorithm 8.9 | |
| Earliest block that can contain its vote. | Rule 8.15 | |
| Earliest block in which it can become missed (and, with DCP-0009 active, be revoked). | Rule 8.15 | |
| Earliest revocation of a missed ticket before DCP-0009. | Rule 8.15 | |
| Last block in which it can vote. If it is not a winner for this block it expires while this block is connected. | Algorithm 8.9 |
8.1.3 Parameters and constants¶
Table 8.2 lists the network parameters used in this chapter with their main-network values; the values for the other networks are tabulated in Chapter 14. Table 8.3 lists the network-independent constants.
| Parameter | Value | Meaning |
|---|---|---|
TicketsPerBlock | 5 | Winners drawn per block; maximum votes per block. |
TicketMaturity | 256 | Blocks between a ticket’s purchase and its entry into the live pool. |
TicketExpiry | 40960 | Blocks a ticket may remain live before it expires. |
StakeEnabledHeight | 512 | First height at which tickets can enter the live pool and at which the ticket database processes votes, expiries and revocations. |
StakeValidationHeight | 4096 | First height that must contain votes; the lottery first runs on the block one below it. |
MaxFreshStakePerBlock | 20 | Maximum ticket purchases per block. |
MinimumStakeDiff | 200000000 | Absolute minimum ticket price in atoms (2 DCR). |
StakeBaseSigScript | 0000 | Required signature script of every stakebase input. |
SStxChangeMaturity | 1 | Maturity of ticket change outputs (and of vote and revocation outputs before the treasury agenda). |
CoinbaseMaturity | 256 | Maturity of vote and revocation outputs once the treasury agenda is active. |
TicketPoolSize | 8192 | Not used by this chapter; used by the stake difficulty algorithm (Chapter 9). |
Note
StakeBaseSigScript differs between networks: it is 0000 on the main, test and simulation networks and 7357 on the regression test network. TicketsPerBlock (5), MaxFreshStakePerBlock (20) and SStxChangeMaturity (1) are the same on all four networks; every other parameter in Table 8.2 differs from its main-network value on at least one other network; see Chapter 14.| Name | Value | Meaning |
|---|---|---|
MaxInputsPerSStx | 64 | Maximum inputs of a ticket. |
MaxOutputsPerSStx | 129 | Maximum outputs of a ticket (). |
NumInputsPerSSGen | 2 | Exact number of inputs of a vote. |
MaxOutputsPerSSGen | 66 | Maximum outputs of a vote (), including any treasury vote output. A vote for a ticket with 64 commitments therefore has no room for that output and can never cast treasury votes. |
NumInputsPerSSRtx | 1 | Exact number of inputs of a revocation. |
MaxOutputsPerSSRtx | 64 | Maximum outputs of a revocation. |
SStxPKHMinOutSize | 32 | Minimum length of a commitment script. |
SStxPKHMaxOutSize | 77 | Maximum length of a commitment script. |
SSGenBlockReferenceOutSize | 38 | Exact length of a vote’s block reference script. |
SSGenVoteBitsOutputMinSize | 4 | Minimum length of a vote’s vote bits script. |
SSGenVoteBitsOutputMaxSize | 77 | Maximum length of a vote’s vote bits script. |
MaxDataCarrierSize | 256 | Maximum data in a null data script (Rule 8.3). |
TxVersionAutoRevocations | 2 | Revocation version introduced by DCP-0009. |
TxVersionTreasury | 3 | Transaction version required for a vote that carries treasury votes. |
maxRevocationsPerBlock | 255 | Maximum revocations per block. |
earlyVoteBitsValue | 0x0001 | Required header vote bits below StakeValidationHeight. |
seedConst | 243f6a8885a308d3 | Constant appended to the lottery seed (the first 64 bits of the fractional part of ). |
8.1.4 Rule changes affecting this chapter¶
Several consensus votes changed the rules in this chapter. Each rule that depends on one names the agenda; “the agenda is active” always means active for the block being validated, as defined in Chapter 13 (dcrd evaluates it on the block’s parent).
| Agenda | DCP | Effect in this chapter |
|---|---|---|
treasury | DCP-0006 | Votes may carry treasury spend votes in a final output (Section 8.4.3); the number of required vote payments excludes that output; vote and revocation outputs need CoinbaseMaturity instead of SStxChangeMaturity confirmations (Rule 8.22); treasury transactions join the stake tree. |
autorevocations | DCP-0009 | Revocations must be version 2, carry an empty signature script, pay zero fee and distribute the rounding remainder pseudorandomly; they skip script validation; tickets may be revoked in the block in which they become missed or expired; blocks must revoke every such ticket. |
explicitverupgrades | DCP-0008 | Caps the transaction version at 3 (Chapter 7); this bounds the versions of stake transactions. |
changesubsidysplit, changesubsidysplitr2 | DCP-0010, DCP-0012 | Change the vote subsidy value (Chapter 11); the formulas of this chapter are unchanged. |
8.2 Classification and Common Script Forms¶
Whether a transaction is a ticket, a vote or a revocation is decided purely from its own contents, by three structural predicates defined in Section 8.3, Section 8.4 and Section 8.5. The classification does not depend on the chain, on agenda state, or on the tree in which the transaction appears. A transaction that fails a predicate is not thereby invalid; it is simply not of that type. It will usually be invalid for some other reason, for example because it is a regular transaction placed in the stake tree (Rule 8.34) or because it creates stake-tagged outputs outside a stake transaction (Chapter 7).
Rule 8.1 · Stake transaction type
The type of a transaction is the first of the following that applies:
- ticket, if it satisfies the ticket predicate (Algorithm 8.1);
- vote, if it satisfies the vote predicate (Algorithm 8.2);
- revocation, if it satisfies the revocation predicate (Algorithm 8.3);
- if its version is at least
TxVersionTreasury: treasury add, treasury spend or treasurybase, by the predicates of Chapter 12 in that order; - otherwise regular.
The three stake predicates are mutually exclusive, so the order of the first three tests does not matter in practice.
dcrd: blockchain/stake/staketx.go · DetermineTxType
8.2.1 Tagged scripts¶
Every non-OP_RETURN output of a stake transaction is a pay-to-pubkey-hash (P2PKH) or pay-to-script-hash (P2SH) script prefixed with one byte, a stake tag opcode, that marks how it was created and therefore how it may be spent (Chapter 6 gives the opcodes no execution semantics beyond a no-op).
| Tag | Byte | Used for |
|---|---|---|
OP_SSTX | 0xba | Ticket output 0: the ticket price and the right to vote. |
OP_SSGEN | 0xbb | Vote payment outputs. |
OP_SSRTX | 0xbc | Revocation payment outputs. |
OP_SSTXCHANGE | 0xbd | Ticket change outputs. |
| Tagged P2PKH (26 bytes): Tagged P2SH (24 bytes): | ||
Rule 8.2 · Tagged script
A public key script with script version is tagged with opcode if and only if , , , and is exactly one of the following, where is any 20 bytes:
- a 25-byte P2PKH script
76 a9 1488 ac, that is,OP_DUP OP_HASH160 OP_DATA_20OP_EQUALVERIFY OP_CHECKSIG; - a 23-byte P2SH script
a9 1487, that is,OP_HASH160 OP_DATA_20OP_EQUAL.
No other length or form is accepted.
dcrd: blockchain/stake/scripttype.go · isTaggedScript
8.2.2 Null data scripts¶
Rule 8.3 · Null data script
A public key script with script version is a null data script if and only if ,0x6a (OP_RETURN), and either , or parses as exactly one opcode that consumes all of , where that opcode is one of OP_0 (0x00), a direct push OP_DATA_1…OP_DATA_75 (0x01–0x4b), OP_PUSHDATA1, OP_PUSHDATA2 or OP_PUSHDATA4 (0x4c–0x4e), or OP_1…OP_16 (0x51–0x60), and the number of bytes it pushes is at most MaxDataCarrierSize . A push whose length prefix or data runs past the end of the script does not parse. Pushes need not be minimally encoded. OP_0 and OP_1…OP_16 push no data bytes for the purpose of this length test.dcrd: blockchain/stake/staketx.go · IsNullDataScript
8.3 Ticket Purchase Transactions¶
A ticket is funded by one or more inputs, possibly owned by different parties (this is how stake pools and ticket splitting work). For each input the ticket carries a pair of outputs: a commitment naming who receives input ’s share when the ticket is later spent, and a change output returning whatever part of input was not contributed. Output 0 holds the ticket price; whoever can satisfy its script can vote with the ticket.
| Position | Content |
|---|---|
| Inputs | Any outpoints (subject to Rule 8.4). Input funds the commitment at output . |
| Output 0 | Ticket price. Script tagged OP_SSTX (voting rights). |
| Output | Commitment for input : a null data script with the 30-byte payload of Table 8.7. |
| Output | Change for input . Script tagged OP_SSTXCHANGE. The value may be zero. |
8.3.1 The commitment output¶
| Field | Type | Bytes | Description |
|---|---|---|---|
| [0] | uint8 | 1 | 0x6a (OP_RETURN). |
| [1] | uint8 | 1 | Push opcode 0x1e…0x4b (OP_DATA_30…OP_DATA_75); equals . |
| [2:22] | bytes | 20 | Payment hash : a public key hash (P2PKH) or a script hash (P2SH), selected by the flag in bit 63 of the next field. |
| [22:30] | uint64 LE | 8 | Encoded amount . Bit 63 (the top bit of byte 29) is the P2SH flag; the committed amount is . |
| [30:32] | uint16 LE | 2 | Fee limits (Table 8.8). |
| [32:] | bytes | 0–45 | Arbitrary, ignored. |
| Bits | Mask | Meaning |
|---|---|---|
| 0–5 | 0x003f | : base-2 logarithm of the fee limit for votes. |
| 6 | 0x0040 | Vote fee limit flag. When clear, each vote output must pay exactly its computed amount. |
| 7 | 0x0080 | Unused, ignored. |
| 8–13 | 0x3f00 | : base-2 logarithm of the fee limit for revocations, . |
| 14 | 0x4000 | Revocation fee limit flag (ignored for revocations once DCP-0009 is active). |
| 15 | 0x8000 | Unused, ignored. |
How the fee limits constrain votes and revocations is specified in Rule 8.18.
8.3.2 Structure¶
Algorithm 8.1 · Ticket predicate
OP_RETURN, OP_SSTX, OP_SSGEN, OP_SSRTX, OP_SSTXCHANGE = 0x6a, 0xba, 0xbb, 0xbc, 0xbd
def is_ticket(tx) -> bool:
if len(tx.inputs) > 64: # MaxInputsPerSStx
return False
if len(tx.outputs) > 129: # MaxOutputsPerSStx
return False
if len(tx.outputs) == 0:
return False
for out in tx.outputs:
if out.script_version != 0:
return False
if not is_tagged(0, tx.outputs[0].script, OP_SSTX):
return False
if 2 * len(tx.inputs) + 1 != len(tx.outputs):
return False
for i in range(1, len(tx.outputs)):
s = tx.outputs[i].script
if i % 2 == 0: # change output
if not is_tagged(0, s, OP_SSTXCHANGE):
return False
else: # commitment output
if not is_null_data(0, s):
return False
if len(s) < 32 or len(s) > 77:
return False
if s[0] != OP_RETURN or not (0x1e <= s[1] <= 0x4b):
return False
return Truedcrd: blockchain/stake/staketx.go · CheckSStx
Algorithm 8.1 implies that a commitment script is exactly bytes with a direct push of bytes, so the 30 bytes of Table 8.7 are always present. A transaction with no inputs is excluded by the transaction sanity rules (Chapter 7), not by this predicate.
Note
The value fields of commitment outputs are not constrained by any stake rule. They are ordinary, unspendable outputs: any value placed in them counts towards the ticket’s total output value (and so reduces its fee) and is lost.8.3.3 Inputs, commitments and price¶
Rule 8.4 · Ticket input script forms
For every input of a ticket, the referenced output MUST exist and be unspent, MUST have script version 0, and its public key script MUST be one of: an untagged P2PKH script (25 bytes) or untagged P2SH script (23 bytes) of the exact forms in Rule 8.2, or a script tagged withOP_SSGEN, OP_SSRTX or OP_SSTXCHANGE. In particular a ticket cannot be funded by an OP_SSTX output, a treasury (OP_TGEN) output, or any other script type.dcrd: internal/blockchain/validate.go · checkTicketPurchaseInputs, isAllowedTicketInputScriptForm
Rule 8.5 · Ticket commitment amounts
For every input of a ticket, let be the amount of the output it spends, the committed amount of output (bytes 22–29 decoded as a little-endianuint64 with bit 63 cleared, taken as int64), and the value of output . Then MUST equal exactly.dcrd: internal/blockchain/validate.go · checkTicketPurchaseInputs, extractTicketCommitAmount
Rule 8.6 · Ticket price
The value of output 0 of every ticket in a block’s stake tree MUST be at least theSBits field of that block’s header (ErrNotEnoughStake), and MUST be at least MinimumStakeDiff (ErrStakeBelowMinimum). Both comparisons are “not less than”: a ticket may pay more than the stake difficulty. The check uses the block’s own claimed SBits and is context free; Rule 9.6 separately requires the claim to equal the stake difficulty computed by Chapter 9.dcrd: internal/blockchain/validate.go · checkProofOfStake
The general input rules (Chapter 7) also apply to tickets: total input value at least total output value, no zero-value inputs, fraud proofs, maturity of spent outputs, script validation, and the prohibition on spending outputs created in the same block (Rule 8.23).
Note
Write for the ticket price (output 0), for the total commitment and . The input rules give , and Rule 8.5 gives , so . The difference is the ticket’s transaction fee plus any value placed in commitment outputs. Since , the division in Algorithm 8.4 never divides by zero.Test vector: A ticket purchase (dcrd regression-network test chain, block 19)
ticket 2f278527eea8d2e6663c547f9b669a6c1aaa8f330bac43f16bb8bb93e0d21df5 (display)
input 0 spends 320000 atoms
out 0 value 20000 ba76a9149bc83f416940190002e6bdded468709d87ffd36088ac
= OP_SSTX-tagged P2PKH, hash 9bc83f416940190002e6bdded468709d87ffd360
out 1 value 0 6a1e9bc83f416940190002e6bdded468709d87ffd36000e20400000000000058
push 0x1e (30 bytes)
hash 9bc83f416940190002e6bdded468709d87ffd360
amount 00e2040000000000 -> 0x000000000004e200 = 320000, bit 63 clear: P2PKH
limits 0058 -> 0x5800: vote flag (0x0040) clear -> votes pay exact amounts
revocation flag (0x4000) set, k_rev = (0x5800 & 0x3f00) >> 8 = 24
out 2 value 0 bd76a914000000000000000000000000000000000000000088ac
= OP_SSTXCHANGE-tagged P2PKH (change of 0 atoms)
check c_0 + r_0 = 320000 + 0 = v_0 ticket fee = 320000 - 20000 = 3000008.4 Vote Transactions¶
A vote spends a winning ticket. Its first input, the stakebase, creates the vote subsidy; its second input spends output 0 of the ticket. Its first two outputs are data: the block being voted on and the vote bits. Then follows one payment per ticket commitment, in commitment order. Once the treasury agenda is active a vote may end with one more data output carrying votes on treasury spends.
| Position | Content |
|---|---|
| Input 0 (stakebase) | Previous outpoint: hash all zero, index 0xffffffff, tree 0. Fraud proof: block height 0, block index 0xffffffff, value in = vote subsidy. Signature script = StakeBaseSigScript. |
| Input 1 | Outpoint (ticket hash, index 0, tree 1): output 0 of the ticket. Signature script satisfies the OP_SSTX script. |
| Output 0 | Block reference: 6a 24 block hash (32 bytes) (block height). Exactly 38 bytes. |
| Output 1 | Vote bits: 6a push(2…75 bytes) beginning with (vote bits). |
| Outputs | Payment (output ) pays commitment (ticket output ); script tagged OP_SSGEN. |
| Output (optional) | Treasury votes: 6a push("TV" 1 to 7 entries of 33 bytes). Only with the treasury agenda active (Section 8.4.3). |
8.4.1 Block reference and vote bits outputs¶
| Field | Type | Bytes | Description |
|---|---|---|---|
| [0] | uint8 | 1 | 0x6a (OP_RETURN). |
| [1] | uint8 | 1 | 0x24 (OP_DATA_36). |
| [2:34] | hash | 32 | Hash of the block voted on, in internal byte order (the order in which a block hash is serialized, not display order). |
| [34:38] | uint32 LE | 4 | Height of the block voted on. |
| Field | Type | Bytes | Description |
|---|---|---|---|
| [0] | uint8 | 1 | 0x6a (OP_RETURN). |
| [1] | uint8 | 1 | Push opcode 0x02…0x4b; equals . |
| [2:4] | uint16 LE | 2 | Vote bits (Section 8.10). |
| [4:8] | uint32 LE | 0 or 4 | Vote version. Present only when ; otherwise the vote version is 0. |
| [8:] | bytes | 0–69 | Remaining extended vote bits; no consensus meaning. |
dcrd calls bytes the extended vote bits (at most bytes); the vote version occupies the first four of them.
8.4.2 Structure¶
Algorithm 8.2 · Vote predicate
NOT_A_VOTE = None
def is_vote(tx): # returns the list of treasury votes, or NOT_A_VOTE
if len(tx.inputs) != 2: # NumInputsPerSSGen
return NOT_A_VOTE
if len(tx.outputs) > 66: # MaxOutputsPerSSGen
return NOT_A_VOTE
if len(tx.outputs) < 2:
return NOT_A_VOTE
sb = tx.inputs[0] # stakebase
if not (sb.prev.hash == bytes(32) and sb.prev.index == 0xffffffff
and sb.prev.tree == 0):
return NOT_A_VOTE
if not (sb.block_height == 0 and sb.block_index == 0xffffffff):
return NOT_A_VOTE
if tx.inputs[1].prev.index != 0:
return NOT_A_VOTE
if tx.inputs[1].prev.tree != 1: # stake tree
return NOT_A_VOTE
for out in tx.outputs:
if out.script_version != 0:
return NOT_A_VOTE
s0 = tx.outputs[0].script
if not is_null_data(0, s0) or len(s0) != 38 or s0[0:2] != b"\x6a\x24":
return NOT_A_VOTE
s1 = tx.outputs[1].script
if not is_null_data(0, s1) or not (4 <= len(s1) <= 77):
return NOT_A_VOTE
if s1[0] != 0x6a or not (0x02 <= s1[1] <= 0x4b):
return NOT_A_VOTE
end = len(tx.outputs)
tvotes = []
last = tx.outputs[-1]
if is_null_data(last.script_version, last.script):
end = end - 1
tvotes = parse_treasury_votes(last.script)
if tvotes is NOT_A_VOTE:
return NOT_A_VOTE
if not (len(tvotes) > 0 and tx.version == 3): # TxVersionTreasury
return NOT_A_VOTE
for i in range(2, end):
if not is_tagged(0, tx.outputs[i].script, OP_SSGEN):
return NOT_A_VOTE
return tvotesdcrd: blockchain/stake/staketx.go · CheckSSGenVotes, IsStakeBase
Implementation pitfall
The test for a treasury vote output looks only at the last output and applies whenever it is a null data script, whatever the transaction version and whatever the agenda state. In a two-output transaction the last output is the vote bits output itself, so such a transaction is a vote only if its vote bits push happens to parse as treasury votes (and its version is 3). Conversely, a transaction whose last output is any null data script that does not parse as treasury votes is not a vote at all.8.4.3 Treasury votes¶
The format of the treasury vote output and the function parse_treasury_votes used by Algorithm 8.2 are specified in Chapter 12 (Algorithm 12.6). Wherever that algorithm rejects, parse_treasury_votes yields NOT_A_VOTE here: the transaction is not a vote at all.
Because a null data script pushes at most 256 bytes and an OP_PUSHDATA1 push at most 255, a vote carries between 1 and 7 treasury votes (; ). The hashes are treasury spend transaction hashes in internal byte order. How treasury votes are tallied is specified in Chapter 12.
Rule 8.7 · Treasury votes require the treasury agenda
When computing the number of payment outputs of a vote (Rule 8.16) and when matching outputs to commitments (Rule 8.17), the final output is excluded if and only if the treasury agenda is active for the block and the vote has a treasury vote output. Before the agenda is active the treasury vote output, if any, is therefore counted and matched as a payment, which always fails (Rule 8.16 or Rule 8.17). In effect, votes MUST NOT carry treasury votes before the treasury agenda is active.dcrd: internal/blockchain/validate.go · checkVoteInputs, checkTicketRedeemerCommitments
8.4.4 Contextual checks¶
Rule 8.8 · Stakebase signature script
The signature script of input 0 of a vote MUST be between 2 and 100 bytes long inclusive (MinCoinbaseScriptLen, MaxCoinbaseScriptLen) and MUST be byte-for-byte equal to StakeBaseSigScript.dcrd: internal/blockchain/validate.go · checkTransactionContext
Rule 8.9 · Ticket input not null
The previous outpoint of input 1 of a vote, and of input 0 of a revocation, MUST NOT be the null outpoint (all-zero hash, index0xffffffff, tree 0). (This is already implied by the predicates, which require index 0 and tree 1 for a vote and tree 1 for a revocation.)dcrd: internal/blockchain/validate.go · checkTransactionContext
The stakebase input is not a real spend: it is skipped by the UTXO lookup, fraud-proof, maturity and script checks of Chapter 7, and its signature script is excluded from signature operation counting (Chapter 6). Its value-in contributes the vote subsidy to the vote’s inputs (Rule 8.19).
The vote’s version is otherwise bounded only by the general maximum transaction version (Chapter 7); a vote with a treasury vote output must have version exactly 3 by Algorithm 8.2.
Test vector: A vote (dcrd regression-network test chain, block 144)
vote 86f999e29e60384f60c4bc8309f022ef2641e51b4c1f416954cd63a636c60344 (display)
in 0 stakebase: prev 00..00:ffffffff tree 0, height 0, index ffffffff,
value in 2970297029 (the vote subsidy)
in 1 prev 49d9a5021ea29435e45c4a1342d687102d7b307bfd42903fb16a952fd23d912a:0
tree 1
out 0 6a24bf7895d75e5da09e707eab994c05a30bf7c5c7e39ace6aed779609b36f0100008f000000
hash, internal order:
bf7895d75e5da09e707eab994c05a30bf7c5c7e39ace6aed779609b36f010000
= block (display order):
0000016fb3099677ed6ace9ae3c7c5f70ba3054c99ab7e709ea05d5ed79578bf
height 8f000000 -> 143
out 1 6a020100 push of 2 bytes: vote bits 0x0001 (approve), vote version 0
out 2 value 3252437701
bb76a91463ac6e0158d456f34131bca6eb8b471638daa5ec88ac (OP_SSGEN P2PKH)
ticket: price 282140672, one commitment of 282440672, vote fee flag clear
expected payment = floor(282440672 * (282140672 + 2970297029) / 282440672)
= 3252437701 (exact, since the vote fee flag is clear)Note
The stakebase signature script of this test-chain vote (deadbeef) is not today’s: the test chain (dcrd’s blockchain/stake/testdata/testexpiry.bz2) was generated with a different genesis block, block-one ledger, organization script and StakeBaseSigScript. Its proof-of-work limit and difficulty rules are those of today’s regression network.8.5 Revocation Transactions¶
A revocation spends a missed or expired ticket and returns the ticket price to the commitments, one output per commitment, in commitment order. Before DCP-0009 [33] the revocation had to be signed by the holder of the voting rights; since DCP-0009 anyone, typically the miner, may create it, it carries no signature and pays no fee, and its outputs are fully determined by the ticket and the parent block.
| Position | Content |
|---|---|
| Input 0 | Outpoint (ticket hash, index 0, tree 1). Signature script empty if the version is at least 2. |
| Outputs | Payment pays commitment (ticket output ); script tagged OP_SSRTX. |
Algorithm 8.3 · Revocation predicate
def is_revocation(tx) -> bool:
if len(tx.inputs) != 1: # NumInputsPerSSRtx
return False
if len(tx.outputs) > 64: # MaxOutputsPerSSRtx
return False
if len(tx.outputs) == 0:
return False
for out in tx.outputs:
if out.script_version != 0:
return False
if tx.inputs[0].prev.tree != 1: # stake tree
return False
for out in tx.outputs:
if not is_tagged(0, out.script, OP_SSRTX):
return False
if tx.version >= 2: # TxVersionAutoRevocations
if len(tx.inputs[0].sig_script) != 0:
return False
if sum(out.value for out in tx.outputs) < tx.inputs[0].value_in:
return False # non-zero fee
return Truedcrd: blockchain/stake/staketx.go · CheckSSRtx
The version-2 conditions are part of the predicate itself and apply regardless of agenda state. The value_in they use is the fraud-proof amount of the input, which the general input rules require to equal the amount of the spent ticket output (Chapter 7); with that, the condition says the fee is zero. The predicate does not check the input’s outpoint index; Rule 8.12 does.
Rule 8.10 · Revocation version
If theautorevocations agenda is active for the block, every revocation MUST have version exactly TxVersionAutoRevocations .dcrd: internal/blockchain/validate.go · checkTransactionContext
Rule 8.11 · Revocation script validation
If theautorevocations agenda is active for the block, the input scripts of a revocation whose version is at least 2 are not executed. In every other case the signature script of a revocation’s input MUST satisfy the ticket’s OP_SSTX output script under the rules of Chapter 6.dcrd: internal/blockchain/scriptval.go · checkBlockScripts, ValidateTransactionScripts
Note
Before DCP-0009 a revocation of version 2 or higher is required by the predicate to have an empty signature script, yet its script is executed and an empty signature script cannot satisfy a tagged P2PKH or P2SH script. Such revocations therefore never validate; before activation, valid revocations have version 0 or 1.Test vector: A revocation of an expired ticket, pre-DCP-0009 rules (regression-network test chain, block 420)
revocation (display hash), version 1:
3ad0c0fd5720d0266d213815614a7dcd08047aa83f21820d22fd3921b7edb0c8
in 0 prev acc72577d3c3efac89975fddbe22d18eca143a6882d7a49714da81a98f6ed43f:0
signed; the ticket has price 20000 and one commitment of 320000
to 9bc83f41...d360 with fee limits 0x5800
out 0 value 20000 bc76a9149bc83f416940190002e6bdded468709d87ffd36088ac
= OP_SSRTX-tagged P2PKH to the committed hash 9bc83f41...d360
expected amount = floor(320000 * 20000 / 320000) = 20000
revocation fee flag set, k_rev = 24, 2^24 >= 20000:
allowed range [0, 20000]8.6 Input and Amount Validation¶
This section specifies the checks that need the UTXO set: that a vote or revocation spends a real, mature ticket; that it pays the ticket’s commitments exactly the amounts they are owed; and the maturity rules for outputs created by stake transactions. They are applied to each transaction of the stake tree, in order, as part of connecting the block (Chapter 7 gives the surrounding procedure). Throughout, is the height of the block containing the transaction being checked.
8.6.1 Spending a ticket¶
Rule 8.12 · Ticket outpoint index
The ticket input of a vote (input 1) and of a revocation (input 0) MUST reference output index 0 of the ticket.dcrd: internal/blockchain/validate.go · checkVoteInputs, checkRevocationInputs
Rule 8.13 · Ticket output available
The output referenced by the ticket input of a vote or revocation MUST exist in the UTXO set as seen by the transaction (that is, after the effects of the preceding transactions of the block) and be unspent.dcrd: internal/blockchain/validate.go · checkVoteInputs, checkRevocationInputs
Rule 8.14 · Ticket submission output
The output referenced by the ticket input of a vote or revocation MUST have script version 0, its public key script MUST be tagged withOP_SSTX (Rule 8.2), and the transaction that created it MUST have been classified as a ticket (Rule 8.1).dcrd: internal/blockchain/validate.go · checkTicketSubmissionInput, isStakeSubmission
Rule 8.15 · Ticket spend maturity
Let be the height of the block that contains the ticket. A vote at height MUST satisfy . A revocation at height MUST satisfy if theautorevocations agenda is not active for the block, and if it is.dcrd: internal/blockchain/validate.go · checkVoteInputs, checkRevocationInputs
Rationale
A ticket mined at enters the live pool while block is connected and can first be drawn for the following block, so is the earliest possible vote. Before DCP-0009 a revocation required the ticket to be in the missed set of the parent block, which cannot happen before . With DCP-0009 a ticket may be revoked in the very block in which it is missed (code comment ininternal/blockchain/validate.go · checkRevocationInputs).These maturity rules are necessary but far from sufficient: which tickets may be voted or revoked in a block is decided by the ticket database (Rule 8.42). A ticket that never entered the live pool (Section 8.8.3) can be neither voted nor revoked.
The general input checks of Chapter 7 also apply to the ticket input, in particular the fraud proof (the input’s value in, block height and block index must match the ticket output) and script validation (subject to Rule 8.11).
8.6.2 Number of payments¶
Rule 8.16 · Number of payments
Let be the number of commitments of the spent ticket. For a vote, let if the treasury agenda is active for the block and the vote has a treasury vote output (Algorithm 8.2 returned a non-empty list), and otherwise; the vote MUST have exactly outputs. A revocation MUST have exactly outputs.dcrd: internal/blockchain/validate.go · checkVoteInputs, checkRevocationInputs
8.6.3 Return amounts¶
When a ticket is spent, the total to be returned is the ticket price , plus the vote subsidy for a vote. The total is divided among the commitments in proportion to the amounts they committed, which include each contributor’s share of the ticket purchase fee. The division rounds every share down; the rounding remainder, between 0 and atoms, is left as transaction fee for votes and (before DCP-0009) for revocations. Under DCP-0009 the remainder of a revocation is distributed one atom at a time to outputs chosen by the lottery’s pseudorandom generator, seeded with the serialized header of the parent block, so that the fee can be exactly zero.
Algorithm 8.4 · Ticket return amounts
def commit_amount(script) -> int64:
return int64(le64_decode(script[22:30]) & (2**63 - 1))
def return_amounts(ticket_outs, price, vote_subsidy, prev_header_bytes,
is_vote, auto_revocations_active) -> list[int64]:
commits = [commit_amount(ticket_outs[i].script)
for i in range(1, len(ticket_outs), 2)]
contribution_sum = sum(commits) # > 0 for every valid ticket
total = price + vote_subsidy # vote_subsidy = 0 for revocations
returns = []
for c in commits: # unbounded (big) integers here
returns.append(((c * total) << 32) // contribution_sum >> 32)
if is_vote or not auto_revocations_active:
return returns
remainder = total - sum(returns)
if remainder > 0:
prng = Hash256PRNG(prev_header_bytes) # Algorithm "PRNG"
for _ in range(remainder):
returns[prng.uniform(uint32(len(returns)))] += 1
return returnsdcrd: internal/blockchain/validate.go · calcTicketReturnAmounts
The intermediate product exceeds 64 bits and must be computed with arbitrary precision (dcrd uses big.Int); all operands are non-negative, so the floor division and right shift are exact floors. The formula equals exactly, but an implementation that evaluates it differently must take care not to overflow. Each result fits in int64 because it does not exceed .
The pseudorandom generator is the one of Algorithm 8.6, with the 180-byte serialized header of the parent of the block being validated (the block at height ) as seed. A fresh generator is created for every revocation, so all revocations in one block draw from the same sequence. That sequence is also the one the lottery used to select the winners for block .
Test vector: Return amounts (computed with dcrd’s calcTicketReturnAmounts)
prev header (180 bytes, from dcrd validate_test.go):
07000000dc02335daa073d293e1b150648f0444a60b9c97604abd01e00000000000000003c449b23
21c4bd0d1fa76ed59f80ebaf46f16cfb2d17ba46948f09f21861095566482410a463ed49473c2727
8cd7a2a3712a3b19ff1f6225717d3eb71cc2b5590100012c7312a3c30500050095a100000cf42418
f1820a870300000020a10700091600005b32a55f5bcce31078832100007469943958002e00000000
0000000000000000000000000000000007000000
PRNG IV fd99cb2f0ea29b91d6d4f3366299a9969598ce5c2ff275bd5ed034a23fe993db
first rand32 values 4254714671 245537681 3604280118 1654237590
-> uniform(3): 2 2 0 0 uniform(5): 1 1 3 0 (2^32 mod 3 = 2^32 mod 5 = 1)
commitments [100000000, 200000000, 300000007], price 600000005
vote, subsidy 0 -> [99999999, 199999999, 300000005] sum 600000003
vote, subsidy 123456789 -> [120576130, 241152261, 361728401] sum 723456792
revocation, pre-DCP-0009 -> [99999999, 199999999, 300000005] sum 600000003
revocation, DCP-0009 -> [99999999, 199999999, 300000007] sum 600000005
(remainder 2, both atoms to index 2)
commitments [100000000] x 5, price 400000004
revocation, DCP-0009 -> [80000001, 80000002, 80000000, 80000001, 80000000]
(remainder 4 to indexes 1, 1, 3, 0)8.6.4 Matching outputs to commitments¶
Payment of a vote is output ; payment of a revocation is output . Payment corresponds to commitment , which is output of the ticket, and to the -th return amount of Algorithm 8.4 (computed with = value of ticket output 0 and, for votes, = the vote subsidy of Rule 8.19).
Rule 8.17 · Payment script
For every payment (every output from the first payment position up to, but excluding, the treasury vote output when it is excluded by Rule 8.16):
- its script version MUST be 0;
- if bit 63 of commitment ’s encoded amount is set (byte 29 of the commitment script has its top bit set), its script MUST be a P2SH script tagged with
OP_SSGEN(vote) orOP_SSRTX(revocation), in the exact 24-byte form of Rule 8.2; otherwise it MUST be a P2PKH script with the same tag in the exact 26-byte form; - the 20-byte hash in that script MUST equal bytes 2–21 of commitment ’s script.
dcrd: internal/blockchain/validate.go · checkTicketRedeemerCommitments
Rule 8.18 · Payment value and fee limits
Let be the fee limits field of commitment (Table 8.8). Payment is fee-limited if
- the transaction is a vote and bit
0x0040of is set, or - the transaction is a revocation, bit
0x4000of is set, and it is not the case that theautorevocationsagenda is active for the block and the revocation’s version is at least 2.
If payment is not fee-limited its value MUST equal exactly. If it is fee-limited, let for a vote or for a revocation, and let
(8.1)
Then its value MUST satisfy .
dcrd: internal/blockchain/validate.go · checkTicketRedeemerCommitments
Note
The fee limit applies to each payment separately, not to the transaction fee as a whole. Since has six bits, is the only value that always permits the whole payment to be taken as fee; a smaller does so only when . The computation never overflowsint64 because it is only evaluated for . Once DCP-0009 is active every revocation is version 2 (Rule 8.10) and therefore not fee-limited: each payment is exactly , and because the remainder has been distributed the payments sum to exactly , which is consistent with the zero-fee condition of Algorithm 8.3.Note
The values of a vote’s two data outputs (and of a treasury vote output) are not constrained by any stake rule; value placed there is unspendable and counts against the general requirement that outputs not exceed inputs.8.6.5 The vote subsidy¶
Rule 8.19 · Stakebase amount
Let be the height encoded in bytes 34–37 of the vote’s output 0 (the height of the block voted on). The value-in field of the vote’s input 0 MUST equal the vote subsidy for height , computed by the vote subsidy function of Chapter 11 (dcrdCalcStakeVoteSubsidyV3) with the subsidy split variant selected by the agendas active for the block: the DCP-0012 variant if changesubsidysplitr2 is active, otherwise the DCP-0010 variant if changesubsidysplit is active, otherwise the original. This value is the subsidy used in Algorithm 8.4.dcrd: internal/blockchain/validate.go · checkVoteInputs
Note
A dcrd source comment records that the subsidy “really should” be computed from the height of the block containing the vote rather than the block voted on, and that this is now part of consensus. Since votes must vote on the parent block (Rule 8.40), in every valid block.Rule 8.20 · Stakebase totals
Let be the vote subsidy for height (same function and variant as in Rule 8.19). For every vote in the block, the sum of all its output values minus the amount of the ticket output it spends MUST NOT exceed . Summed over all votes in the block, the total output value minus the total spent ticket amount MUST NOT exceed if , and MUST NOT exceed 0 otherwise, whereVoters is the header field.dcrd: internal/blockchain/validate.go · checkStakeBaseAmounts, getStakeBaseAmounts, checkTransactionsAndConnect
These two checks are implied by the preceding rules in any block that satisfies them, but they are separate checks in dcrd and are stated for completeness. The stake tree is processed before the regular tree; transaction fees of stake transactions are added to the fees available to the coinbase as described in Chapter 11.
8.6.6 Summary: checking a vote or revocation¶
Algorithm 8.5 collects the transaction-level checks of this section for one vote or revocation. It adds nothing to the rules above; it shows which data each check needs. The block-level eligibility of the ticket (Rule 8.42) is checked separately.
Algorithm 8.5 · Input checks for a vote or revocation at height h
def check_redeemer_inputs(tx, h, utxo, parent_header, flags, params):
is_vote = tx_type(tx) == VOTE
if is_vote:
tin = tx.inputs[1]
voted_height = le32_decode(tx.outputs[0].script[34:38])
subsidy = vote_subsidy(voted_height, flags.subsidy_variant)
if tx.inputs[0].value_in != subsidy:
reject("bad stakebase amount")
else:
tin = tx.inputs[0]
subsidy = 0
if tin.prev.index != 0:
reject("ticket input must reference output 0")
entry = utxo.lookup(tin.prev)
if entry is None or entry.spent:
reject("missing ticket output")
if (entry.script_version != 0 or not is_tagged(0, entry.script, OP_SSTX)
or entry.tx_type != TICKET):
reject("not a ticket submission output")
extra = 1 if is_vote or flags.auto_revocations else 2
if h - entry.height < params.TicketMaturity + extra:
reject("immature ticket spend")
ticket_outs = entry.ticket_outputs # every output of the ticket
n = (len(ticket_outs) - 1) // 2
if is_vote:
e = 1 if flags.treasury and len(is_vote_tvotes(tx)) > 0 else 0
first, payments = 2, len(tx.outputs) - 2 - e
else:
first, payments = 0, len(tx.outputs)
if payments != n:
reject("wrong number of payments")
amounts = return_amounts(ticket_outs, ticket_outs[0].value, subsidy,
serialize(parent_header), is_vote,
flags.auto_revocations)
for j in range(payments):
check_payment(tx, first + j, ticket_outs[2 * j + 1].script,
amounts[j], is_vote, flags) # payment script and value rulesdcrd: internal/blockchain/validate.go · checkVoteInputs, checkRevocationInputs, checkTicketRedeemerCommitments
Here is_vote_tvotes(tx) is the list returned by Algorithm 8.2.
Implementation pitfall
Validating a vote or revocation needs all outputs of the spent ticket: the ticket price from output 0 and the hashes, amounts and fee limits of the commitment outputs, which are unspendable null data outputs that a UTXO set would normally discard. dcrd stores them with the ticket’s output 0 in its UTXO entry for as long as that output is unspent (internal/blockchain/utxoentry.go · TicketMinimalOutputs). An implementation must likewise retain every output (value, script version and script) of each unspent ticket.8.6.7 Outputs created by stake transactions¶
Rule 8.21 · Ticket outputs are spent only by votes and revocations
An input of any transaction that is neither a vote nor a revocation MUST NOT spend an output whose script (with its script version) is tagged withOP_SSTX.dcrd: internal/blockchain/validate.go · CheckTransactionInputs
Rule 8.22 · Maturity of stake outputs
Let be the height of the block containing the spent output and the height of the spending transaction’s block.
- An output tagged with
OP_SSGENorOP_SSRTXMUST NOT be spent unless when the treasury agenda is not active for the block, or when it is. - An output tagged with
OP_SSTXCHANGEMUST NOT be spent unless .
dcrd: internal/blockchain/validate.go · CheckTransactionInputs
Implementation pitfall
SStxChangeMaturity is 1 on every network, so before the treasury agenda vote rewards and revocation refunds could be spent in the very next block. Informative documentation that describes a 256-block wait for vote rewards matches the consensus rule only once the treasury agenda is active. The general coinbase and expiry maturity rules of Chapter 7 still apply independently.Rule 8.23 · Stake transactions do not spend same-block outputs
No input of a ticket, vote, revocation, treasury add, treasury spend or treasurybase (other than input 0 of a vote, treasury spend or treasurybase, which spends nothing) may spend an output created in the same block (in either tree), except the single historical outputs listed in Table 8.13: on the given network, at the given height, output 0 of the regular-tree transaction with the given hash may be spent by a stake transaction of the same block.dcrd: internal/blockchain/validate.go · CheckTransactionInputs, isSBSSViolation
| Network | Height | Transaction |
|---|---|---|
| main | 1106817 | 0875ecdc5f12c8aa6ee0d54331fd5b5e786639882a3adb09882de5e3b939613b |
| main | 1106831 | 714e71358937cd33480fd2900853d43ea3440ca67b38bacdfeaeb0c37c80ee27 |
| main | 1106837 | aeba09a4efa334e3c13e68f27f40bd37cda7643c263f88d69f38a33c2cdacd18 |
| main | 1106854 | 17228266d9d6dd7084aa2e479319aca6d755c2a9d2dbb3cf28c8151470c7a439 |
| main | 1106860 | 20d6d3ed1b609f03969474dca1f452c25e035766457dfd58061f9b9270fc4e6d |
| main | 1107195 | 5d2e1898fe0c631cb795b1906fb3cf8d9772f1826be8dea64dd3ab85ac0ab2d3 |
| testnet3 | 1980161 | 451b6eed1a777bc5bbb5c1dbe10a9e444cbeb7d863adb75fc6b7a676b3dcbb58 |
The mechanics of this exception (dcrd re-adds output 0 of the listed transaction to the view before connecting the stake tree) belong to the UTXO model of Chapter 7.
8.7 The Lottery¶
After each block at height is connected, every node draws TicketsPerBlock distinct winners from the live ticket pool as it stands after that block. The draw is a deterministic function of two things only: the serialized header of block and the set of live tickets. Because the header commits to the block’s transactions and to its proof of work, a miner cannot cheaply bias the draw, and every node computes the same winners. The winners of block may vote on block in block . A six-byte digest of the draw, the final state, is committed in the header of block so that a node can check it has the same live pool and the same winners before validating the votes.
All hashing in this section is BLAKE-256 (Chapter 3), written , producing 32 bytes.
8.7.1 The pseudorandom generator¶
The generator, Hash256PRNG, turns a seed of arbitrary length into a stream of 32-bit integers. The seed is hashed together with a constant to a 32-byte initialization vector (IV). The first eight outputs are the eight big-endian 32-bit words of the IV itself; every following group of eight is the words of for .
Algorithm 8.6 · Hash256PRNG
SEED_CONST = bytes.fromhex("243f6a8885a308d3")
class Hash256PRNG:
def __init__(self, seed: bytes):
self.seed = BLAKE256(seed + SEED_CONST) # the IV
self.last_hash = self.seed
self.hash_idx = 0 # next 4-byte word of last_hash to use, 0..7
self.idx = 0 # uint64: number of hashes derived from seed
def rand32(self) -> uint32:
i = 4 * self.hash_idx
r = be32_decode(self.last_hash[i:i + 4])
self.hash_idx += 1
if self.hash_idx > 7:
self.last_hash = BLAKE256(self.seed + be32(uint32(self.idx)))
self.idx += 1
self.hash_idx = 0
if self.idx > 0xffffffff: # unreachable in practice
self.seed = BLAKE256(self.seed)
self.last_hash = self.seed
self.idx = 0
return r
def state_hash(self) -> bytes: # 32 bytes
return BLAKE256(self.last_hash + be32(uint32(self.idx))
+ bytes([self.hash_idx]))dcrd: blockchain/stake/lottery.go · CalcHash256PRNGIV, NewHash256PRNGFromIV, Hash256Rand, StateHash
Note the order of operations in rand32: the word is read first, and the next hash is computed immediately after the eighth word of a hash has been read, not lazily before the ninth. This matters for state_hash, which depends on last_hash, idx and hash_idx exactly as they stand after the last call. The rollover of idx past would require more than calls and cannot occur in consensus use; it is included for completeness.
Implementation pitfall
Both 32-bit encodings in this generator are big-endian, unlike almost every other integer in the protocol: the words read from the hash and the counter appended to the IV. The counter appended for the first derived hash is 0, so the ninth output comes from .8.7.2 Uniform integers¶
Algorithm 8.7 · Uniform random integer in [0, n)
def uniform(prng: Hash256PRNG, n: uint32) -> uint32: # prng.uniform(n)
if n < 2:
return 0 # consumes no output
if n > 0x80000000:
lo = uint32(2**32 - n)
else:
lo = uint32(0xffffffff - 2 * n + 1) % n
while True: # rejection sampling
r = prng.rand32()
if r >= lo:
return r % ndcrd: blockchain/stake/lottery.go · UniformRandom
In both branches lo equals (for the expression is 0), so the accepted values form a range whose length is a multiple of and the result is exactly uniform. Values below lo are discarded and another word is drawn.
Test vector: Hash256PRNG and uniform, seed = ASCII “Decred” (446563726564)
IV = d48f4175da6800a5e3557cb4205f8be944483480935c0f2f30d7d4eaabd2efcf
rand32 #0..#11:
3566158197 3664248997 3814030516 543132649 1145582720 2472283951
819451114 2882727887 2142381687 1037079434 122677752 3963859140
(#0..#7 are the words of the IV; #8 = 0x7fb22677 is the first word
of BLAKE256(IV || 00000000))
state_hash after 12 calls (idx = 1, hash_idx = 4):
84b9d4f546995a04697b695feb9497d66e46a23b82c339cfdd03e4282c0d6ce5
fresh generator, successive calls:
uniform(1) = 0 (no output consumed)
uniform(2) = 1 (r = 3566158197, lo = 0)
uniform(5) = 2 (r = 3664248997, lo = 1)
uniform(40960) = 40116 (r = 3814030516, lo = 0)
uniform(2147483649) = 324800302
(lo = 2147483647: r = 543132649 and 1145582720
rejected, r = 2472283951 accepted)
uniform(4294967295) = 819451114 (lo = 1)
dcrd TestBasicPRNG: seed = BLAKE256(01), 100000 calls, state_hash =
e4c445ebe0815aaf9944f94b63d388566132b72e1ee2d3a985fcfbae72cdf1248.7.3 Order of the live ticket pool¶
dcrd stores the live tickets in a treap keyed by ticket hash, with the ticket’s live height as heap priority. Only the key order matters for consensus: a winner index denotes the ticket at position of the pool in ascending key order.
Rule 8.24 · Live pool order
The live ticket pool is ordered by ticket hash, ascending, where two hashes are compared as 32-byte strings in internal byte order (the byte order in which the hash is produced by BLAKE-256 and serialized in an outpoint), lexicographically from byte 0, each byte as an unsigned value. Position 0 is the smallest hash. The heights of the tickets play no part in the order.dcrd: blockchain/stake/internal/tickettreap/immutable.go · get, Put, GetByIndex | blockchain/stake/lottery.go · fetchWinners
Implementation pitfall
Display-form hashes are byte-reversed (Chapter 2). Sorting display strings, or sorting hashes interpreted as little-endian 256-bit integers, gives a different order. In terms of display strings the comparison starts at the last two hexadecimal digits. Any data structure may be used; a sorted array of 32-byte keys reproduces dcrd exactly.8.7.4 Drawing the winners and the final state¶
In the algorithms of this section fail(reason) means that the block cannot be connected. It is distinct from reject because dcrd does not report the condition as a blockchain rule violation (the draw failure is an untyped error, the others are stake-package errors), so the block is not marked invalid; it is refused either way.
Algorithm 8.8 · Winner selection and final state
def draw_winners(header_bytes: bytes, pool: list[bytes], k: int):
# header_bytes: the 180-byte serialized header of the block just connected
# pool: live ticket hashes after connecting it, sorted as in the pool order rule
# k: TicketsPerBlock
prng = Hash256PRNG(header_bytes)
size = len(pool)
if size < k:
fail("cannot draw winners") # block cannot be connected
idxs = []
while len(idxs) < k:
r = prng.uniform(uint32(size))
if r not in idxs: # draw again on a repeat
idxs.append(r)
winners = [pool[i] for i in idxs] # in draw order, not sorted
final_state = BLAKE256(b"".join(winners) + prng.state_hash())[0:6]
return winners, final_statedcrd: blockchain/stake/tickets.go · connectNode | blockchain/stake/lottery.go · findTicketIdxs, fetchWinners | internal/blockchain/blockindex.go · lotteryIV
The winners keep the order in which they were drawn; the final state hashes their concatenation in that order (each hash in internal byte order) followed by the generator’s state hash after the last draw. A pool larger than tickets is an error in dcrd and cannot occur. The case size < k is discussed in Section 8.8.3.
Test vector: Lottery on a ten-ticket pool (computed with dcrd’s connectNode)
seed (stands in for a header): ASCII "block one header"
= 626c6f636b206f6e6520686561646572
IV = 4295eeba3103039d7adb28dee716bbceb7bce96ee13f5089d43daea53a43c1fd
pool = { BLAKE256(byte i) : i = 0..9 }, sorted (internal byte order):
[0] 0ce8d4ef4dd7cd8d62dfded9d4edb0a774ae6a41929a74da23109e8f11139c87 BLAKE256(00)
[1] 19b7506ad9c189a9f8b063d2aee15953d335f5c88480f8515d7d848e7771c4ae BLAKE256(06)
[2] 49af37ab5270015fe25276ea5a3bb159d852943df23919522a202205fb7d175c BLAKE256(02)
[3] 4a6c419a1e25c85327115c4ace586decddfe2990ed8f3d4d801871158338501d BLAKE256(01)
[4] 4c2231813064f8500edae05b40195416bd543fd3e76c16d6efb10c816d92e8b6 BLAKE256(09)
[5] 4c6eb9e38415034f4c93d3304d10bef38bf0ad420eefd0f72f940f11c5857786 BLAKE256(04)
[6] 53d661e71e47a0a7e416591200175122d83f8af31be6a70af7417ad6f54d0038 BLAKE256(07)
[7] 9bff7982eab6f7883322edf7bdc86a23c87ca1c07906fbb1584f57b197dc6253 BLAKE256(08)
[8] b706d561742ad3671703c247eb927ee8a386369c79644131cdeb2c5c26bf6c5d BLAKE256(03)
[9] bdd15db13448905791a70b68137445e607cca06cc71c7a58b9b2e84a06c54d08 BLAKE256(05)
k = 5: indexes drawn [4, 7, 8, 6, 5] (6 draws: idx = 0, hash_idx = 6 afterwards)
state_hash = 45a5fba5bbb9c9058645d09514427a53722ec3f2ab4076f650741f06a6bd4229
final state = 27a0cf022cbd
next block (seed "block two header"): winners [4] [7] [8] vote, [6] and [5] are
missed; the pool is now the 5 remaining tickets and all 5 are drawn:
indexes [3, 1, 0, 4, 2] over the new pool, final state = 27c864c436eaTest vector: Duplicate rejection: seed “Decred”, pool size 7, k = 5
rand32 #0..#6 mod 7 = 0 3 2 3 2 4 6 (lo = 2^32 mod 7 = 4; no rejections)
indexes = [0, 3, 2, 4, 6] (draws #3 and #4 repeat and are discarded)
state_hash = 95e00d629ec81c0e67a570021bf081437385ce01db184af466c7773bbdbb1e97Test vector: A real draw: dcrd regression-network test chain, lottery on block 143
header of block 143 (180 bytes):
000000008379bcce660662c28735988b54d193bd9386c501acae677fe002326c66b10000a1c527ea
1a1abceb6a145579ba739a0fb0de3ba3594f8717c62e3fc1d88b25fe000000000000000000000000
000000000000000000000000000000000000000001000000000000000000000080070000f7e4001f
00004834040000008f0000007e0100006d5cec57306f010000000000000000000000000000000000
0000000000000000000000000000000000000000
IV = f680c8ab1cac33b1b9fd72165d34adaeaca23a564bfe16f55976b6953a338e72
live pool after block 143: 1940 tickets
indexes [1315, 1193, 1774, 302, 1558]
winners (internal byte order):
adad145e4bb898ea4e2e4ab4eac39cad1d628cead91e245df48d1851cc8001ff
9f2fcb5eb5dd8710c219db9899eb1bd8c60163eaa25abecbfeeca0c5c8df4cc2
eb97034120808b03bf4155183094e37cd723de0f1d2e470d5b0482adc7e9f530
2a913dd22f956ab13f9042fd7b307b2d1087d642134a5ce43594a21e02a5d949
cd615d92df7eb0f042c36899b4dbafa9935b8fc320c32cd689e21054acae63b5
state_hash = 0ca9f8c7ca073e2f9e4e2303b2a632407975d6c10dcb4e0e106233c671ceb980
final state = ff00007be270 = FinalState in the header of block 144 (PoolSize 1940)The fourth winner of the last vector is the ticket spent by the vote shown in Section 8.4.4 (whose display-form hash 49d9a5021ea29435e45c4a1342d687102d7b307bfd42903fb16a952fd23d912a is the reverse of the internal form above).
8.8 The Ticket Database¶
Every node maintains, for each block, the set of live tickets, the set of missed tickets and the set of revoked tickets as of that block, together with the winners drawn on that block and its final state. dcrd calls this per-block state a stake node (blockchain/stake/tickets.go · Node). The state of a block is a function of the state of its parent and of the block itself; the genesis block’s state is empty.
8.8.1 Ticket states¶
| State | Set | Leaves the state when |
|---|---|---|
| Immature | none | Block is connected: the ticket becomes live (if that height is at least StakeEnabledHeight). |
| Live | live, with live height | It is a winner of the parent of the block being connected (then voted or missed), or that block’s height reaches (then expired). |
| Voted | none (removed) | Final. The vote is the ticket’s only spend. |
| Missed | missed, flag expired = false | Revoked. |
| Expired | missed, flag expired = true | Revoked. |
| Revoked | revoked | Final. |
The live height of a ticket is the height of the block whose connection made it live, , not the height of its purchase. Expired tickets are kept in the missed set; the expired flag only distinguishes them for reporting. In consensus terms “missed set” always means missed or expired, not yet revoked.
8.8.2 Connecting a block¶
Algorithm 8.9 · Stake state transition when connecting the block at height h
def connect(parent: StakeState, block, h: int, params) -> StakeState:
st = parent.copy() # live: hash -> L; missed: hash -> (L, expired); revoked
# Tickets spent in this block, in stake-tree order:
voted = [tx.inputs[1].prev.hash for tx in block.stake_txs
if is_vote(tx) is not NOT_A_VOTE]
revoked = [tx.inputs[0].prev.hash for tx in block.stake_txs if is_revocation(tx)]
if h >= params.StakeEnabledHeight:
# 1. Every voted ticket must be a winner drawn on the parent.
for t in voted:
if t not in parent.winners:
fail("unknown ticket spent")
# 2. Each parent winner is now either voted or missed.
for w in parent.winners:
L = st.live.pop(w) # must be present
if w not in voted:
st.missed[w] = (L, False)
# 3. Expire live tickets whose live height is old enough.
expire_h = h - params.TicketExpiry if h > params.TicketExpiry else 0
for t, L in list(st.live.items()):
if L <= expire_h:
del st.live[t]
st.missed[t] = (L, True)
# 4. Revocations move tickets from missed to revoked.
for t in revoked:
if t not in st.missed:
fail("revoked ticket not missed")
st.revoked[t] = st.missed.pop(t)
# 5. Tickets bought TicketMaturity blocks ago become live.
for t in tickets_in(ancestor(block, h - params.TicketMaturity)):
if t in st.live:
fail("duplicate ticket")
st.live[t] = h # live height L = h
# 6. Draw the winners for block h + 1.
st.winners, st.final_state = [], bytes(6)
if h >= params.StakeValidationHeight - 1:
st.winners, st.final_state = draw_winners(serialize(block.header),
sorted(st.live),
params.TicketsPerBlock)
return stdcrd: blockchain/stake/tickets.go · connectNode | internal/blockchain/stakenode.go · maybeFetchNewTickets, fetchStakeNode | blockchain/stake/staketx.go · FindSpentTicketsInBlock
Here tickets_in(B) is the list of hashes of the stake-tree transactions of block that are tickets (Rule 8.1), and ancestor(block, x) is the ancestor of block at height on its own chain. The order of steps 1 to 5 is significant: winners are processed before expiry, so a winner whose expiry height has also arrived becomes voted or missed, never expired; expiry precedes revocations, which (with DCP-0009) lets a block revoke a ticket that expires in that same block; and new tickets are added before the draw, so a ticket that becomes live at height can be drawn for block . The order of tickets within each step affects only dcrd’s undo records, not the resulting sets.
Rule 8.25 · Stake state transition
A block can only be connected if Algorithm 8.9 succeeds for it: every vote spends a winner drawn on its parent, every revoked ticket is in the missed set after steps 2 and 3, no ticket becomes live twice, and, at heights , the live pool after step 5 contains at leastTicketsPerBlock tickets. A block for which it fails MUST NOT become part of the chain.dcrd: blockchain/stake/tickets.go · connectNode | internal/blockchain/chain.go · connectBlock
Note
In dcrd a failure of Algorithm 8.9 is reported as an ordinary error rather than a rule violation, because in any block that has passed the checks of Section 8.9 the first two conditions are already guaranteed (by Rule 8.42) and the third by unique transaction hashes. The pool-size condition is a genuine consensus constraint: a block at height after which the live pool would hold fewer thanTicketsPerBlock tickets cannot be connected, so a chain whose pool is about to run out cannot be extended past that point. Mining software avoids producing such a chain (Section 8.11).Test vector: State transitions (dcrd’s connectNode with TicketsPerBlock , StakeEnabledHeight , StakeValidationHeight , TicketExpiry )
Ti = BLAKE256(byte i); hashes abbreviated to their first 4 bytes (internal order).
Block headers are replaced by the seeds "h1".."h4". Only the ticket database
transition is exercised; the block-level rules are not applied.
block 1: T0..T9 become live (L = 1)
live T0 0ce8d4ef T6 19b7506a T2 49af37ab T1 4a6c419a T9 4c223181
T4 4c6eb9e3 T7 53d661e7 T8 9bff7982 T3 b706d561 T5 bdd15db1
winners [T6, T1] final state 3aced47dce07
block 2: votes T6; revokes T1 (missed in step 2, revoked in step 4)
live T0 T2 T9 T4 T7 T8 T3 T5 revoked T1
winners [T7, T5] final state 95ea5ea60e92
block 3: votes T7; T5 is missed and not revoked
live T0 T2 T9 T4 T8 T3 missed T5 revoked T1
winners [T4, T9] final state 93df9dcae44a
expiring in block 4 (e = 4 - 3 = 1, winners excluded): T0 T2 T8 T3
block 4: votes T4; T9 missed (step 2); T0 T2 T8 T3 expire (step 3);
revokes T9 T0 T2 T8 T3 (step 4); T10 T11 T12 become live (L = 4)
live T12 61a3403f T11 7b527886 T10 e81db4f0
missed T5 revoked T0 T2 T1 T9 T8 T3
winners [T11, T10] final state 52c4fe6489248.8.3 Early heights¶
The two activation parameters divide the chain into three phases.
- Before
StakeEnabledHeight - Steps 1 to 5 are skipped entirely. No ticket becomes live, nothing expires, and no winners exist. Tickets may be bought (subject to the price rules) from the first block that can fund them.
- From
StakeEnabledHeighttoStakeValidationHeight - Tickets become live and can expire; the parent’s winner list is empty, so step 2 does nothing. Blocks may not contain votes or revocations (Rule 8.27, Rule 8.36).
- From
StakeValidationHeight - The draw runs after every block. The first winners are drawn on block
StakeValidationHeight, and blockStakeValidationHeightis the first block that must carry votes.
Implementation pitfall
The block at height adds the tickets of block only when . A ticket mined in a block below would never enter the live pool and could never be voted or revoked. On all four networksStakeEnabledHeight equals CoinbaseMaturity TicketMaturity (256 + 256 on the main network, 16 + 16 on the others), and every spendable output descends from a coinbase of block 1 or later, which cannot be spent before height ; so no ticket can be mined that early and every ticket does enter the pool. An implementation must nevertheless gate step 5 on exactly as stated.The header fields PoolSize and FinalState of block commit to the state of block (Rule 8.32, Rule 8.33). For every block below StakeValidationHeight the final state is therefore the all-zero value, matching Rule 8.27; the first non-zero final state is in the header of block StakeValidationHeight.
8.8.4 Tickets expiring in the next block¶
The block-level revocation rules of DCP-0009 need to know, when validating block , which tickets block will expire. This set is computed from the parent’s state.
Rule 8.26 · Tickets expiring in block h
Let if and otherwise. The tickets expiring in block are the tickets in the parent’s live set whose live height equals , excluding the parent’s winners. (Every live ticket with a smaller live height has already expired, so this is the same set that step 3 of Algorithm 8.9 expires.)dcrd: blockchain/stake/tickets.go · ExpiringNextBlock
8.8.5 Disconnecting a block (informative)¶
A reorganization requires undoing blocks. Since the state of a block is a function of its parent’s state and the block, an implementation may simply recompute or cache states. dcrd instead records, for every block, the list of ticket transitions it performed (each with the ticket’s live height and its flags) and applies them in reverse order to restore the parent’s live, missed and revoked sets. The parent’s winners are recovered from the transitions that removed winners (spent ones and missed non-expired ones), restored to their original draw order, and the parent’s final state is recomputed by re-running the draw on the parent’s header. Reverse order matters because, with DCP-0009, one ticket can be missed (or expired) and revoked in the same block. None of this affects consensus.
8.9 Block-Level Stake Rules¶
The rules in this section apply to a whole block. Together with the rules above they determine which stake transactions a block may contain and tie the stake fields of the header to the block’s contents and to the ticket database. Table 8.15 lists the header fields involved; their serialization is specified in Chapter 4.
| Field | Type | Must equal |
|---|---|---|
VoteBits | uint16 | 0x0001 below StakeValidationHeight; afterwards bit 0 must match the majority of the votes (Rule 8.41). Other bits are unconstrained here. |
FinalState | [6]byte | Final state of the lottery drawn on the parent (Rule 8.33). |
Voters | uint16 | Number of votes in the stake tree (Rule 8.38). |
FreshStake | uint8 | Number of tickets in the stake tree (Rule 8.31). |
Revocations | uint8 | Number of revocations in the stake tree (Rule 8.39). |
PoolSize | uint32 | Number of live tickets after the parent (Rule 8.32). |
SBits | int64 | Stake difficulty (Chapter 9); minimum ticket price (Rule 8.6). |
8.9.1 Context-free header rules¶
Rule 8.27 · Stake header fields below stake validation height
If the header’sHeight is less than StakeValidationHeight, its Voters MUST be 0, its Revocations MUST be 0, its VoteBits MUST equal 0x0001, and its FinalState MUST be six zero bytes.dcrd: internal/blockchain/validate.go · checkBlockHeaderSanity
Rule 8.28 · Minimum number of votes
If the header’sHeight is at least StakeValidationHeight, its Voters MUST be at least (3 on every network, where TicketsPerBlock ).dcrd: internal/blockchain/validate.go · checkBlockHeaderSanity
Rule 8.29 · Maximum number of votes
The header’sVoters MUST NOT exceed TicketsPerBlock.dcrd: internal/blockchain/validate.go · checkBlockHeaderSanity
Rule 8.30 · Maximum number of ticket purchases
The header’sFreshStake MUST NOT exceed MaxFreshStakePerBlock.dcrd: internal/blockchain/validate.go · checkBlockHeaderSanity
Rule 8.31 · Ticket purchase count
The header’sFreshStake MUST equal the number of transactions in the block’s stake tree that are tickets.dcrd: internal/blockchain/validate.go · checkBlockDataSanity
Rule 8.6, which checks every ticket in the stake tree against the header’s SBits and MinimumStakeDiff, is also a context-free block check in dcrd.
8.9.2 Header commitments to the ticket database¶
Rule 8.32 · Pool size commitment
The header’sPoolSize MUST equal the number of tickets in the live set of the parent block’s stake state (the live pool from which the winners for this block were drawn).dcrd: internal/blockchain/validate.go · checkBlockHeaderContext
Rule 8.33 · Final state commitment
The header’sFinalState MUST equal the final state of the parent block’s stake state: the value computed by Algorithm 8.8 on the parent, or six zero bytes if no draw was made on the parent.dcrd: internal/blockchain/validate.go · checkBlockHeaderContext
Note
dcrd skips these two checks, together with the difficulty, stake difficulty and stake version checks and the ticket redeemer check of Rule 8.42, when it adds a block that is an ancestor of its assumed-valid block or while in bulk-import mode (BFFastAdd). That is an optimization for blocks presumed valid; the rules hold for every block of the chain.8.9.3 Stake tree composition¶
Rule 8.34 · Tree membership
Every transaction in a block’s regular tree MUST be of type regular (Rule 8.1), and every transaction in its stake tree MUST NOT be of type regular.dcrd: internal/blockchain/validate.go · checkBlockContext
Rule 8.35 · Allowed stake transaction types
Every transaction in the stake tree MUST be a ticket, a vote, a revocation, or, only if the treasury agenda is active for the block, a treasury add, a treasury spend or a treasurybase. A stake-tree transaction classified as a treasury type while the treasury agenda is not active makes the block invalid.dcrd: internal/blockchain/validate.go · checkBlockContext
Rule 8.36 · No votes or revocations below stake validation height
If the block’s height is less thanStakeValidationHeight, every transaction in its stake tree MUST be a ticket, or, if the treasury agenda is active, a treasury add or treasurybase. (Votes, revocations and treasury spends are excluded.)dcrd: internal/blockchain/validate.go · checkBlockContext
Rule 8.37 · Non-empty stake tree
If the block’s height is at leastStakeValidationHeight, its stake tree MUST NOT be empty. (This is implied by Rule 8.28 and Rule 8.38.)dcrd: internal/blockchain/validate.go · checkTransactionsAndConnect
Rule 8.38 · Vote count
The header’sVoters MUST equal the number of votes in the stake tree.dcrd: internal/blockchain/validate.go · checkBlockContext
Rule 8.39 · Revocation count and limit
The number of revocations in the stake tree MUST NOT exceed 255 (maxRevocationsPerBlock), and the header’s Revocations MUST equal that number.dcrd: internal/blockchain/validate.go · checkBlockContext
There is no rule on the order of tickets, votes and revocations within the stake tree. The only positional requirement in the stake tree is that a treasurybase, when the treasury agenda is active, is its first transaction (Chapter 12). Because stake transactions cannot spend outputs of the same block (Rule 8.23), their relative order cannot affect the validity of their inputs.
8.9.4 Votes¶
Rule 8.40 · Votes vote on the parent
If the block’s height is at leastStakeValidationHeight, the block reference of every vote in the stake tree (Table 8.10) MUST name the block’s parent: its 32-byte hash MUST equal the header’s PrevBlock field and its height MUST equal .dcrd: internal/blockchain/validate.go · checkBlockContext
Rule 8.41 · Parent approval
If the block’s height is at leastStakeValidationHeight, let be the number of votes in the stake tree whose vote bits have bit 0 set and the total number of votes. The votes approve the parent if (a strict majority; a tie disapproves). Bit 0 of the header’s VoteBits MUST be set if the votes approve the parent and MUST be clear otherwise.dcrd: internal/blockchain/validate.go · checkBlockContext, voteBitsApproveParent
What happens to the parent’s regular tree when it is disapproved is specified in Chapter 10: from height 2 on, a block whose header has bit 0 of VoteBits clear undoes the effects of its parent’s regular tree before its own transactions are applied. Below StakeValidationHeight the header value is fixed at 0x0001 (approve) by Rule 8.27.
8.9.5 Votes and revocations against the ticket database¶
Algorithm 8.10 · Ticket redeemer check for the block at height h
def check_ticket_redeemers(block, h, parent: StakeState, auto_revocations_active):
# h: height of block; parent: stake state of block h - 1
vote_tickets = [tx.inputs[1].prev.hash for tx in block.stake_txs
if is_vote(tx) is not NOT_A_VOTE]
revoke_tickets = [tx.inputs[0].prev.hash for tx in block.stake_txs
if is_revocation(tx)]
has_vote = {w: False for w in parent.winners}
for t in vote_tickets:
if t not in has_vote:
reject("vote for ineligible ticket")
has_vote[t] = True
newly_missed = {w for w, voted in has_vote.items() if not voted}
expiring = set(expiring_in_block(parent, h)) # expiring-tickets rule
revoked = set()
for t in revoke_tickets:
eligible = ((auto_revocations_active
and (t in newly_missed or t in expiring))
or t in parent.missed)
if not eligible:
reject("revocation of ineligible ticket")
revoked.add(t)
if auto_revocations_active:
for t in newly_missed:
if t not in revoked:
reject("missing revocation of missed ticket")
for t in expiring:
if t not in revoked:
reject("missing revocation of expired ticket")dcrd: internal/blockchain/validate.go · checkTicketRedeemers, checkBlockContext
Rule 8.42 · Votes and revocations spend eligible tickets
If the block’s height is at least StakeValidationHeight, Algorithm 8.10 MUST NOT reject it. That is:
- every vote MUST spend one of the winners drawn on the parent;
- if the
autorevocationsagenda is not active for the block, every revocation MUST spend a ticket in the parent’s missed set; - if it is active, every revocation MUST spend a ticket that is in the parent’s missed set, or is a winner of the parent without a vote in this block, or expires in this block (Rule 8.26); and the block MUST contain a revocation for every winner of the parent that has no vote in this block and for every ticket that expires in this block.
dcrd: internal/blockchain/validate.go · checkTicketRedeemers, checkBlockContext
Duplicate spends of one ticket (two votes, two revocations, or a vote and a revocation) are excluded by the ordinary double-spend rule, since all of them spend output 0 of the ticket.
Rationale
DCP-0009 makes revocation automatic: as soon as a ticket is missed or expires, the block in which that happens must return its funds. Because a version-2 revocation needs no signature and its outputs are fully determined (Rule 8.18), the miner can always construct it.Note
Tickets that became missed before DCP-0009 activated and were never revoked remain in the missed set and may still be revoked at any later height. The required revocations of a block number at most missed winners (a valid block carries at least a majority of the votes) plus the tickets that became live togetherTicketExpiry blocks earlier (at most MaxFreshStakePerBlock), well below the limit of 255.8.10 Vote Bits and Vote Version¶
Each vote carries 16 vote bits (bytes 2–3 of output 1, little-endian) and, optionally, a 32-bit vote version (bytes 4–7). At the transaction level only two things are defined here:
- Bit 0 (
0x0001, dcrdBlockValid) is the voter’s verdict on the regular tree of the block voted on: set means approve, clear means disapprove. The verdicts of the votes in a block are combined by Rule 8.41. - The vote version is the little-endian
uint32at bytes 4–7 of the vote bits script if that script is at least 8 bytes long, and 0 otherwise.
| Field | Value |
|---|---|
| vote bits | |
| approves parent | |
| vote version | if , else 0 |
| voted block hash | of output 0 (internal byte order) |
| voted block height | of output 0 |
The meaning of bits 1–15 (choices on consensus rule changes, each agenda occupying a masked group of bits), how the vote version of the votes in a block feeds the stake version and the rule-change tallies, and which votes are counted, are specified in Chapter 13. No stake rule constrains bits 1–15 or the vote version; a vote with any values is valid as far as this chapter is concerned.
8.11 Non-Consensus Behavior¶
The following is policy: it describes what dcrd’s mempool, block template generator and wallets do, not what a block must satisfy. Details are in Chapter 17.
- Automatic revocations. Once DCP-0009 is active, dcrd’s block template generator creates a version-2, zero-fee revocation for every ticket that the block must revoke (
blockchain/stake/staketx.go · CreateRevocationFromTicket), computing outputs with the same return amount algorithm. - Ticket exhaustion. The template generator refuses to produce a block template whose ticket purchases are too few to keep at least
TicketsPerBlocklive tickets after the ticket maturity period, counting all immature tickets and the votes that will consume tickets (internal/blockchain/validate.go · checkTicketExhaustion). This is not a consensus rule; it prevents miners from producing a chain that Rule 8.25 would make impossible to extend. - Fee limits. The fee limits are chosen by the wallet that builds the ticket. The tickets in dcrd’s regression-network test data, such as the one in the vector of Section 8.3.3, set the revocation fee flag with and leave the vote fee flag clear, so their votes pay no fee beyond the rounding remainder.
- Stake tree order. Apart from the treasurybase, which must come first when the treasury agenda is active, the order of stake transactions is left to the block producer; no order is required by consensus.
8.12 Error Kinds (informative)¶
dcrd reports each violation with an error kind. Table 8.17 maps the error kinds whose subject is a ticket, vote or revocation to the rules of this chapter, as a cross-check for implementers comparing behavior with dcrd. The kind reported for an invalid block depends on the order of dcrd’s checks and is not part of consensus.
| Error kind(s) | Rule |
|---|---|
ErrSStxTooManyInputs, ErrSStxTooManyOutputs, ErrSStxNoOutputs, ErrSStxInvalidOutputs, ErrSStxInOutProportions | Algorithm 8.1 (the transaction is not a ticket) |
ErrSSGenWrongNumInputs, ErrSSGenTooManyOutputs, ErrSSGenNoOutputs, ErrSSGenNoStakebase, ErrSSGenWrongIndex, ErrSSGenWrongTxTree, ErrSSGenBadGenOuts, ErrSSGenNoReference, ErrSSGenBadReference, ErrSSGenNoVotePush, ErrSSGenBadVotePush, ErrSSGenInvalidTxVersion | Algorithm 8.2 (not a vote) |
ErrSSGenInvalidDiscriminatorLength, ErrSSGenInvalidNullScript, ErrSSGenUnknownDiscriminator, ErrSSGenInvalidTVLength, ErrSSGenInvalidTreasuryVote, ErrSSGenDuplicateTreasuryVote | Algorithm 12.6 (not a vote) |
ErrSSRtxWrongNumInputs, ErrSSRtxTooManyOutputs, ErrSSRtxNoOutputs, ErrSSRtxBadOuts, ErrSSRtxWrongTxTree, ErrSSRtxInputHasSigScript, ErrSSRtxInvalidFee | Algorithm 8.3 (not a revocation) |
ErrStakeTxInRegularTree, ErrRegTxInStakeTree | Rule 8.34 |
ErrNonstandardStakeTx | Rule 8.35 |
ErrNotEnoughStake, ErrStakeBelowMinimum | Rule 8.6 |
ErrTicketInputScript; ErrMissingTxOut for a ticket input | Rule 8.4 |
ErrTicketCommitment | Rule 8.5 |
ErrBadStakebaseScriptLen, ErrBadStakebaseScrVal | Rule 8.8 |
ErrBadTxInput (null ticket input) | Rule 8.9 |
ErrInvalidRevocationTxVersion | Rule 8.10 |
ErrScriptValidation (revocation input) | Rule 8.11 |
ErrInvalidVoteInput, ErrInvalidRevokeInput | Rule 8.12, Rule 8.14 |
ErrMissingTxOut for a ticket input of a vote or revocation | Rule 8.13 |
ErrImmatureTicketSpend | Rule 8.15 |
ErrBadNumPayees | Rule 8.16, Rule 8.7 |
ErrBadPayeeScriptVersion, ErrBadPayeeScriptType, ErrMismatchedPayeeHash | Rule 8.17 |
ErrBadPayeeValue | Rule 8.18 |
ErrBadStakebaseAmountIn | Rule 8.19 |
ErrSSGenSubsidy, ErrBadStakebaseValue | Rule 8.20 |
ErrTxSStxOutSpend | Rule 8.21 |
ErrImmatureSpend for a stake-tagged output | Rule 8.22 |
ErrMissingTxOut for a same-block spend | Rule 8.23 |
ErrUnknownTicketSpent, ErrMissingTicket, ErrDuplicateTicket, and the untyped “cannot pick unique ticket indexes” error | Rule 8.25 |
ErrInvalidEarlyStakeTx | Rule 8.27, Rule 8.36 |
ErrInvalidEarlyVoteBits, ErrInvalidEarlyFinalState | Rule 8.27 |
ErrNotEnoughVotes | Rule 8.28 |
ErrTooManyVotes | Rule 8.29 |
ErrTooManySStxs | Rule 8.30 |
ErrFreshStakeMismatch | Rule 8.31 |
ErrPoolSize | Rule 8.32 |
ErrInvalidFinalState | Rule 8.33 |
ErrNoStakeTx | Rule 8.37 |
ErrVotesMismatch | Rule 8.38 |
ErrTooManyRevocations, ErrRevocationsMismatch | Rule 8.39 |
ErrVotesOnWrongBlock | Rule 8.40 |
ErrIncongruentVotebit | Rule 8.41 |
ErrTicketUnavailable (ineligible vote), ErrInvalidSSRtx, ErrNoMissedTicketRevocation, ErrNoExpiredTicketRevocation | Rule 8.42 |
ErrTicketUnavailable (in the stakebase total checks) | Unreachable: the ticket output was loaded by the earlier input checks. |
ErrSerializeHeader | Unreachable: header serialization cannot fail. |
ErrTicketExhaustion | Policy only (Section 8.11). |
ErrSStxBadCommitAmount, ErrSStxBadChangeAmts, ErrSSRtxInvalidTxVersion, ErrDatabaseCorrupt, ErrMissingDatabaseTx, ErrMemoryCorruption | Not consensus: raised only by helper, wallet, mining or database code. |
ErrSStxInvalidInputs, ErrSStxVerifyCalcAmts, ErrVerSStxAmts, ErrVerifyInput, ErrVerifyOutType, ErrVerifyTooMuchFees, ErrVerifySpendTooMuch, ErrVerifyOutputAmt, ErrVerifyOutPkhs, ErrFindTicketIdxs | Defined but never raised by dcrd at this commit. |