Skip to content

11 Issuance and Block Subsidy

New decred enters existence in exactly two ways: through the block-one ledger, a fixed list of payments made by the coinbase transaction of the block at height 1, and through the block subsidy, an amount created by every later block and divided between the proof-of-work miner, the stakeholders whose votes the block contains, and the project treasury. Transaction fees are not new money; they move existing atoms from transaction inputs to the miner.

This chapter specifies the subsidy schedule (the full block subsidy as a function of height and its periodic reduction), the three-way split of that subsidy and the two changes made to the split by stakeholder vote (DCP-0010, DCP-0012), the coinbase transaction that pays the proof-of-work share, the amount checks on the stake tree that pay the vote and treasury shares, the block-one ledger, and the resulting total supply. The formats of votes and of the treasurybase transaction are specified in Chapter 8 and Chapter 12; this chapter fixes only the amounts they carry.

All arithmetic in this chapter is on non-negative int64 values, and every division truncates. The order of the multiplications and divisions is part of the consensus rules: reordering them, or replacing an iterated computation by a closed form, changes results by a few atoms and splits the chain.

11.1 Overview

Table 11.1 summarizes who receives each part of the subsidy, which transaction carries it, and how its amount depends on the block. The quantities named there are defined in Section 11.2 and Section 11.3.

Table 11.1. Where each share of the subsidy of the block at height ℎ is paid
ShareCarried byAmount and dependencies
Block-one ledgerCoinbase of block 1The fixed list of outputs in BlockOneLedger; paid only at ℎ=1 (Section 11.6).
Proof of workCoinbase (regular tree)𝑊(ℎ,𝑣): the work proportion of 𝑆(ℎ), scaled by the number of votes 𝑣 in the block from StakeValidationHeight on. Lost if the next block disapproves this block’s regular tree.
VotesStakebase input of each vote (stake tree)𝑉(ℎ−1) per vote: the vote proportion of 𝑆(ℎ−1), divided by TicketsPerBlock. Based on the height of the block voted on, not the block containing the vote. Not scaled by 𝑣.
Treasury, before the treasury agendaOutput 0 of the coinbase𝑇(ℎ,𝑣): one tenth of 𝑆(ℎ), scaled by 𝑣 from StakeValidationHeight on. Lost if the block is disapproved.
Treasury, after the treasury agendaTreasurybase (first stake transaction)𝑇(ℎ): one tenth of 𝑆(ℎ), not scaled by 𝑣. Unaffected by disapproval.

Table 11.2 lists the parameters and constants used. The full per-network tables are in Chapter 14; Table 11.3 summarizes the subsidy-related values of all four networks because the derived quantities given there (block-one subsidy, final subsidy interval) are computed in this chapter.

Table 11.2. Parameters and constants of the subsidy rules (main-network values)
NameValueMeaning
BaseSubsidy3119582664Full subsidy, in atoms, of every block in the first reduction interval (except blocks 0 and 1).
MulSubsidy100Reduction multiplier.
DivSubsidy101Reduction divisor.
SubsidyReductionInterval6144Length of a reduction interval in blocks.
WorkRewardProportion6Proof-of-work proportion of the original split.
StakeRewardProportion3Vote proportion of the original split.
BlockTaxProportion1Treasury proportion (all eras).
TicketsPerBlock5Maximum number of votes per block; the divisor in all vote scaling.
StakeValidationHeight4096First height whose blocks must contain votes.
CoinbaseMaturity256Blocks before coinbase outputs may be spent (Chapter 7).
OrganizationPkScripta914f5916158e3e2c4551c1796708db8367207ed13bb87Script that coinbase output 0 must pay before the treasury agenda (a pay-to-script-hash script).
OrganizationPkScriptVersion0Required script version of that output.
BlockOneLedger3146 entriesRequired outputs of the block-one coinbase (Section 11.6).
MinCoinbaseScriptLen2Minimum coinbase signature script length in bytes.
MaxCoinbaseScriptLen100Maximum coinbase signature script length in bytes.
maxUniqueCoinbaseNullDataSize256Maximum length of the data pushed by the coinbase height commitment.

Two derived quantities are used throughout. With 𝑁 = TicketsPerBlock,

𝑃=WorkRewardProportion+StakeRewardProportion+BlockTaxProportion=10

(11.1)

is the denominator of the original split and of the treasury share in every era, and

𝑚=⌊𝑁2⌋+1=3

(11.2)

is the minimum number of votes a block at or above StakeValidationHeight must contain (enforced in Chapter 8).

Table 11.3. Subsidy parameters and derived quantities on each network
NetworkBaseSubsidyIntervalStakeValidationHeightBlock-one subsidyFirst zero-subsidy height
mainnet31195826646144409616800000000000011010048 (interval 1792)
testnet325000000002048768100000000000003622912 (interval 1769)
simnet5000000000012814430000000000000265088 (interval 2071)
regnet5000000000012814430000000000000265088 (interval 2071)

All four networks use MulSubsidy =100, DivSubsidy =101, proportions 6, 3 and 1, and TicketsPerBlock =5.

Note

chaincfg.Params also carries fields named WorkRewardProportionV2 (1) and StakeRewardProportionV2 (8). They are deprecated and are not read by the consensus code: the proportions of the modified splits are fixed constants (Table 11.4), the same on every network. (The fields WorkRewardProportion and StakeRewardProportion carry the same deprecation notice in dcrd but are read: they define the original split.)

11.2 The Full Block Subsidy

The full block subsidy 𝑆(ℎ) is the total amount a block at height ℎ may create before it is divided into shares. It is constant within a reduction interval of SubsidyReductionInterval consecutive blocks and is multiplied by 100101 at the start of each new interval, so that it decays geometrically, by roughly one percent every 6144 blocks (about three weeks on the main network). Interval 𝑘 consists of the heights 𝑘⋅6144 through 𝑘⋅6144+6143, so interval 0 contains the genesis block and block 1, both of which are special.

Writing 𝐵, 𝑀, 𝐷 and 𝐼 for BaseSubsidy, MulSubsidy, DivSubsidy and SubsidyReductionInterval, and 𝐿 for the sum of the amounts in BlockOneLedger,

𝑆(ℎ)={0ifℎ≤0𝐿ifℎ=1𝑓(⌊ℎ𝐼⌋)ifℎ≥2𝑓(𝑘)={𝐵if𝑘=0⌊𝑓(𝑘−1)⋅𝑀𝐷⌋if𝑘≥1.

(11.3)

Rule 11.1 · Full block subsidy

The full block subsidy of height ℎ MUST be computed by Algorithm 11.1. In particular the reduction MUST be applied once per completed interval, as a multiplication by MulSubsidy followed by a truncating division by DivSubsidy, each step operating on the result of the previous step. The genesis block has subsidy 0, and block 1 has the sum of the block-one ledger instead of BaseSubsidy.

dcrd: blockchain/standalone/subsidy.go · CalcBlockSubsidy

Algorithm 11.1 · Full block subsidy

def block_subsidy(height: int64) -> int64:
    if height <= 0:
        return 0                      # genesis (and negative heights)
    if height == 1:
        return block_one_subsidy()    # sum of BlockOneLedger amounts; 0 if empty
    s: int64 = BaseSubsidy
    for _ in range(height // SubsidyReductionInterval):
        s = s * MulSubsidy            # never overflows for valid parameters
        s = s // DivSubsidy           # truncating; both operands non-negative
        if s == 0:
            break                     # all later intervals are also 0
    return s

dcrd: blockchain/standalone/subsidy.go · CalcBlockSubsidy

Implementation pitfall

Iterated truncating division is not the same as the closed form ⌊𝐵⋅(𝑀𝐷)𝑘⌋. The two first differ in interval 2, where the iteration gives 3058114560 and the closed form 3058114561. The gap grows to 31 atoms by interval 100 and stays between 42 and 56 atoms from interval 200 on, and the closed form is still 56 atoms when the iterated value reaches zero. Exact rational or floating point evaluation of a power is therefore wrong. An implementation may cache per-interval values (dcrd does), but each cached value must be the result of the iteration.

11.2.1 When the Subsidy Reaches Zero

For 1≤𝑠≤101, ⌊100𝑠101⌋=𝑠−1. Once the full subsidy falls to 101 atoms or less it therefore decreases by exactly one atom per interval. On the main network 𝑆 is 1 atom in interval 1791 (heights 11003904 to 11010047) and 0 from interval 1792 on: the first height with zero full subsidy is 11010048. The shares reach zero earlier, because each is a truncated fraction of 𝑆 (Section 11.7 gives the last heights).

Note

The parameter documentation states that BaseSubsidy must not exceed 140739635871744=⌊263−1216−1⌋ atoms, so that the products in this chapter cannot overflow int64. All networks are far below this bound, and no consensus check enforces it.

11.3 Splitting the Subsidy

The full subsidy of a block is divided among proof of work, votes and the treasury in fixed proportions. The proportions have changed twice by stakeholder vote; each set is called a split variant.

11.3.1 Split Variants and Their Selection

Table 11.4. Subsidy split variants. Each share is a fraction 𝑛/𝑑 of 𝑆.
VariantAgendaPoW 𝑤𝑛/𝑤𝑑Votes 𝑠𝑛/𝑠𝑑TreasuryMain-network activation
Originalnone6/10 (60%)3/10 (30%)1/10 (10%)From genesis
DCP-0010changesubsidysplit10/100 (10%)80/100 (80%)1/10 (10%)Block 657280
DCP-0012changesubsidysplitr21/100 (1%)89/100 (89%)1/10 (10%)Block 794368

In the original variant the work fraction is WorkRewardProportion /𝑃 and the vote fraction is StakeRewardProportion /𝑃, with 𝑃 from Eq. (11.1); in the two modified variants they are the fixed constants shown, on every network. The treasury share is BlockTaxProportion /𝑃=1/10 in all three variants. The activation heights are those recorded in [38] and [39] for the main network; an implementation derives activation from the chain (Chapter 13), not from this table.

Rule 11.2 · Selection of the split variant

The split variant used for every subsidy amount checked while connecting a block (its coinbase, its votes’ stakebase inputs and its stake-tree totals) MUST be chosen from the agendas that are active for that block, that is, as determined from the state after its parent:

  1. if changesubsidysplitr2 (DCP-0012) is active for the block, the DCP-0012 variant;
  2. otherwise, if changesubsidysplit (DCP-0010) is active for the block, the DCP-0010 variant;
  3. otherwise, the original variant.

The DCP-0012 variant takes precedence even if changesubsidysplit is not active. The same block’s variant applies to the vote subsidy even though that subsidy is computed from the parent’s height (Rule 11.3).

dcrd: internal/blockchain/validate.go · checkConnectBlock | internal/blockchain/agendas.go · isSubsidySplitAgendaActive, isSubsidySplitR2AgendaActive

Whether the treasury agenda (DCP-0006) is active for the block is likewise determined from the state after its parent, and that agenda is never active for blocks 0 and 1.

11.3.2 The Three Shares

Algorithm 11.2 defines the three share functions. WORK[variant] and VOTE[variant] are the pairs (𝑛,𝑑) of Table 11.4, and 𝑚 is from Eq. (11.2). The argument voters is the number of votes in the block, which equals the Voters field of its header (Chapter 10); below StakeValidationHeight it is 0 and is ignored.

Algorithm 11.2 · Proof-of-work, per-vote and treasury subsidies

P = WorkRewardProportion + StakeRewardProportion + BlockTaxProportion   # 10
MIN_VOTES = TicketsPerBlock // 2 + 1                                     # 3
WORK = {ORIGINAL: (WorkRewardProportion, P), DCP0010: (10, 100), DCP0012: (1, 100)}
VOTE = {ORIGINAL: (StakeRewardProportion, P), DCP0010: (80, 100), DCP0012: (89, 100)}

def work_subsidy(height: int64, voters: int, variant) -> int64:
    if height == 1:
        return block_subsidy(1)
    if height >= StakeValidationHeight and voters < MIN_VOTES:
        return 0
    n, d = WORK[variant]
    s = block_subsidy(height) * n // d                 # first truncation
    if height < StakeValidationHeight:
        return s                                       # no vote scaling yet
    return (voters * s) // TicketsPerBlock             # second truncation

def vote_subsidy(height: int64, variant) -> int64:     # amount per vote
    if height < StakeValidationHeight - 1:
        return 0
    n, d = VOTE[variant]
    return block_subsidy(height) * n // (d * TicketsPerBlock)   # one truncation

def treasury_subsidy(height: int64, voters: int, treasury_active: bool) -> int64:
    if height <= 1:
        return 0
    if height >= StakeValidationHeight and voters < MIN_VOTES:
        return 0
    s = block_subsidy(height) * BlockTaxProportion // P
    if height < StakeValidationHeight or treasury_active:
        return s
    return (voters * s) // TicketsPerBlock

dcrd: blockchain/standalone/subsidy.go · calcWorkSubsidy, CalcWorkSubsidyV3, calcStakeVoteSubsidy, CalcStakeVoteSubsidyV3, CalcTreasurySubsidy

In formulas, for ℎ≥2 and 𝑣 votes (at least 𝑚 from StakeValidationHeight on, and 0 below it), with 𝑁 = TicketsPerBlock:

𝑊(ℎ,𝑣)=⌊𝑣⋅⌊𝑆(ℎ)⋅𝑤𝑛𝑤𝑑⌋𝑁⌋,𝑉(ℎ)=⌊𝑆(ℎ)⋅𝑠𝑛𝑠𝑑⋅𝑁⌋,𝑇(ℎ,𝑣)=⌊𝑣⋅⌊𝑆(ℎ)10⌋𝑁⌋,

(11.4)

where the outer scaling by 𝑣𝑁 is omitted below StakeValidationHeight, and for 𝑇 also when the treasury agenda is active. Three details of Algorithm 11.2 are easy to miss:

  • The work subsidy is truncated twice (once for the proportion, once for the vote scaling), in that order. Computing ⌊𝑆⋅𝑤𝑛⋅𝑣/(𝑤𝑑⋅𝑁)⌋ instead gives different results: at height 6144 with three votes it gives 1111930454 instead of the correct 1111930453.
  • The vote subsidy is 𝑆⋅𝑠𝑛 divided by 𝑠𝑑⋅𝑁. Because nested truncating divisions of non-negative integers compose, this equals the collective stake share ⌊𝑆⋅𝑠𝑛/𝑠𝑑⌋ divided by 𝑁; what matters is that the collective share is never scaled by the number of votes.
  • The treasury share always uses the denominator 𝑃=10 derived from the original parameters; the modified variants change only the work and vote shares. Before the treasury agenda it is scaled by the number of votes like the work share; afterwards it is not.

Rule 11.3 · The vote subsidy is based on the height voted on

The subsidy earned by each vote in the block at height ℎ MUST be vote_subsidy(h - 1, variant), where variant is the split variant of the block at height ℎ (Rule 11.2). The proof-of-work and treasury subsidies of the same block use height ℎ.

dcrd: internal/blockchain/validate.go · checkVoteInputs, checkStakeBaseAmounts, checkTransactionsAndConnect | blockchain/standalone/subsidy.go · calcStakeVoteSubsidy

Implementation pitfall

Because of Rule 11.3, the votes in the first block of each reduction interval earn the subsidy of the previous interval, while the work and treasury shares of that block already use the reduced value. Under the modified variants the vote share dominates, so the total paid by such a block exceeds its own full subsidy: block 657408, the first block of interval 107, pays 107574538+5⋅173840453+107574538=1084351341 atoms against 𝑆(657408)=1075745381. The same offset makes the votes in the first voting block, at height StakeValidationHeight, earn the subsidy of height StakeValidationHeight −1, which is why vote_subsidy returns a non-zero value from that height on. dcrd’s source calls this basis unfortunate but it is part of consensus.

Rationale

The work subsidy is scaled by the number of votes so that a miner gains nothing by withholding votes from a block; each missing vote forfeits a fifth of the proof-of-work share. The vote subsidy is not scaled, since a vote that is not included simply earns nothing. DCP-0006 removed the vote scaling of the treasury share when that share moved to the treasurybase.

11.3.3 Rounding and Unissued Atoms

The shares are truncated independently, so with five votes 𝑊+5𝑉+𝑇 is normally a few atoms less than 𝑆; those atoms are never created. Table 11.5 shows the shortfall at some heights. Two further amounts are never issued: the vote share of the blocks below StakeValidationHeight −1 (heights 2 to 4094 on the main network, which no vote ever votes on), and every share lost to missing votes, disapproved blocks, or coinbases that pay less than allowed.

Table 11.5. Shortfall 𝑆−𝑊−5𝑉−𝑇 in atoms, five votes, 𝑉 evaluated at the same height
Height𝑆(ℎ)OriginalDCP-0010DCP-0012
40963119582664522
61443088695706364
6144001153344657326
1228800426404419224
6144000148792346

11.3.4 Test Vectors

The vectors below were produced by calling dcrd’s SubsidyCache with the main-network parameters. Table 11.6 gives the work and treasury functions and Table 11.7 the per-vote function, each evaluated at the height in the first column (not shifted).

Table 11.6. Main network: 𝑆(ℎ), work_subsidy per variant and treasury_subsidy with the treasury agenda inactive and active
ℎ𝑣𝑆(ℎ)𝑊 orig.𝑊 0010𝑊 0012𝑇 inactive𝑇 active
00000000
10168000000000000=𝑆(1)=𝑆(1)=𝑆(1)00
203119582664187174959831195826631195826311958266311958266
409503119582664187174959831195826631195826311958266311958266
409653119582664187174959831195826631195826311958266311958266
409643119582664149739967824956661224956660249566612311958266
409633119582664112304975818717495918717495187174959311958266
40962311958266400000
614453088695706185321742330886957030886957308869570308869570
614433088695706111193045318532174218532174185321742308869570
5524484128675013161764006210294001010294000102940010128675013
6572805108650283565190170110865028310865028108650283108650283
79436838642497483111299085185498451854985185498486424974
100000056223488873734093326223488862234886223488862234888
500000049567454592377653976537653995674
100000003243871411424
110100475100000
110100485000000
Table 11.7. Main network: vote_subsidy(h, variant), the amount per vote, at height ℎ
ℎOriginalDCP-0010DCP-0012
4094000
4095187174959499133226555285714
6143187174959499133226555285714
6144185321742494191312549787835
55244877205007205880020229041523
65728065190170173840453193397504
79436851854984138279959153836455
10000003734093399575821110778101
500000057404153079170300
10000000143843

Table 11.8 combines the functions as consensus applies them to a whole block at height ℎ: the work and treasury shares at ℎ, the per-vote share at ℎ−1, and the required coinbase input value (Rule 11.8). “Total” is 𝑊+𝑇+𝑣⋅𝑉(ℎ−1).

Table 11.8. Main network: subsidy amounts of a block at height ℎ with 𝑣 votes
ℎ𝑣VariantTreasury agendaWorkPer voteTreasuryCoinbase inputTotal
20orig.no1871749598031195826621837078642183707864
40965orig.no187174959818717495931195826621837078643119582659
40963orig.no112304975818717495918717495913102247171871749594
61444orig.no148257393818717495924709565617296695942478369430
5524474orig.no617640062772050071029400107205800721029400100
5524484orig.yes617640062772050071286750136176400621055135103
65728050010yes1086502831738404531086502831086502831086502831
65740850010yes1075745381738404531075745381075745381084351341
79436830012yes5185498153836455864249745185498553119837
79872050012yes8556928153836455855692818556928863308484

11.4 The Coinbase Transaction

The coinbase is the first transaction of a block’s regular transaction tree. It has a single input that spends nothing, whose ValueIn field (part of the input’s witness data, Chapter 4) commits to the subsidy being claimed, and its outputs pay the proof-of-work subsidy plus the block’s fees to whatever scripts the miner chooses. Before the treasury agenda its first output also pays the treasury share. Except in blocks 0 and 1, one output carries the block height, which makes every coinbase’s transaction hash unique.

11.4.1 Identifying a Coinbase

Algorithm 11.3 · Coinbase identification

def is_coinbase(tx, treasury_active: bool) -> bool:
    if treasury_active and tx.version != 3:
        return False
    if len(tx.inputs) != 1:
        return False
    prev = tx.inputs[0].prev_out
    if prev.index != 0xffffffff or prev.hash != bytes(32):
        return False                              # prev.tree is not examined here
    if treasury_active and len(tx.outputs) >= 2:  # exclude treasury-spend look-alikes
        sig = tx.inputs[0].sig_script
        s0 = tx.outputs[0].pk_script
        s1 = tx.outputs[1].pk_script
        if (len(sig) > 0 and len(s0) > 0 and len(s1) > 0 and sig[-1] == 0xc2
                and s0[0] == 0x6a and s1[0] == 0xc3):  # OP_TSPEND, OP_RETURN, OP_TGEN
            return False
    return True

dcrd: blockchain/standalone/tx.go · IsCoinBaseTx

Before the treasury agenda a coinbase may have any transaction version permitted by the general version rules (Chapter 7); once the agenda is active it must have version 3 (TxVersionTreasury), and a transaction of any other version is not a coinbase at all.

Rule 11.4 · The first regular transaction is the only coinbase

For every block other than the genesis block, the first transaction of the regular tree MUST satisfy is_coinbase(tx, treasury_active), where treasury_active tells whether the treasury agenda is active for the block. Every other transaction of the regular tree MUST NOT satisfy it.

dcrd: internal/blockchain/validate.go · checkBlockContext

Rule 11.5 · Coinbase input

For a regular-tree transaction that satisfies is_coinbase:

  1. the previous outpoint of its input MUST be the null outpoint: hash of 32 zero bytes, index 0xffffffff and tree 0 (regular);
  2. the fraud-proof fields of its input MUST be null: BlockHeight =0 (NullBlockHeight) and BlockIndex = 0xffffffff (NullBlockIndex);
  3. the length of its signature script MUST be at least MinCoinbaseScriptLen =2 and at most MaxCoinbaseScriptLen =100 bytes.

The contents of the signature script are otherwise unconstrained. The input’s ValueIn is constrained by Rule 11.8.

dcrd: internal/blockchain/validate.go · checkTransactionContext, isNullOutpoint, isNullFraudProof

The general transaction rules of Chapter 7 (sanity limits, version and script-version limits, lock time and expiry, the prohibition on stake opcodes in regular transactions) apply to the coinbase as to any other regular transaction. The coinbase has no real inputs, so input existence, script execution and sequence locks do not apply to it.

11.4.2 Required Outputs

The required leading outputs of the coinbase depend on whether the treasury agenda is active for the block (Table 11.9). Outputs after the required ones are free: any number of them, with any scripts and amounts allowed by the general rules, subject only to the total of Rule 11.9. They normally pay the miner.

Table 11.9. Leading outputs of the coinbase of a block at height ℎ≥2
Outputtreasury agenda not activetreasury agenda active
0Treasury payment: script OrganizationPkScript, version OrganizationPkScriptVersion, amount exactly treasury_subsidy(h, v, False) (Rule 11.6)Height commitment (Rule 11.7)
1Height commitment (Rule 11.7)Free
2, …FreeFree

Rule 11.6 · Treasury output before the treasury agenda

If the treasury agenda is not active for a block at height ℎ≥2, its coinbase MUST have at least one output, and output 0 MUST have script version equal to OrganizationPkScriptVersion, a public key script byte-for-byte equal to OrganizationPkScript, and an amount equal to treasury_subsidy(h, v, False), where 𝑣 is the number of votes in the block. Blocks 0 and 1 are exempt.

dcrd: internal/blockchain/subsidy.go · coinbasePaysTreasuryAddress | internal/blockchain/validate.go · checkConnectBlock

Once the treasury agenda is active the coinbase carries no treasury payment; the treasury share is paid by the treasurybase, which must be the first transaction of the stake tree. Its format, its own height commitment and its effect on the treasury balance are specified in Chapter 12; its amount is fixed by Rule 11.12.

11.4.3 The Height Commitment

The height commitment is a provably unspendable output (Chapter 6) whose script is OP_RETURN followed by a single data push. The first four bytes of the pushed data are the block height as a little-endian uint32; any further bytes, up to 252 of them, are free and conventionally hold an extra nonce that miners vary to change the coinbase hash, and with it the block’s Merkle root, without changing anything else.

Rule 11.7 · Coinbase height commitment

For a block at height ℎ≥2, let 𝑖=1 if the treasury agenda is not active for the block and 𝑖=0 if it is. The coinbase MUST have at least 𝑖+1 outputs; output 𝑖 MUST have script version 0; and its public key script, parsed by commitment_data of Algorithm 11.4, MUST yield between 4 and maxUniqueCoinbaseNullDataSize =256 bytes inclusive, whose first four bytes, read as a little-endian uint32, MUST equal uint32(h). The output’s amount is not constrained by this rule. Blocks 0 and 1 are exempt.

dcrd: internal/blockchain/validate.go · checkCoinbaseUniqueHeight

Algorithm 11.4 · Extracting the coinbase height commitment

def commitment_data(pk: bytes) -> bytes:
    # pk must be OP_RETURN followed by exactly one push opcode (0x00..0x4e)
    # and nothing else; any other form yields the empty string.
    if len(pk) < 2 or pk[0] != 0x6a:          # OP_RETURN
        return b""
    op, rest = pk[1], pk[2:]
    if op <= 0x4b:                            # OP_0 and OP_DATA_1..OP_DATA_75
        n, body = op, rest
    elif op == 0x4c and len(rest) >= 1:       # OP_PUSHDATA1
        n, body = rest[0], rest[1:]
    elif op == 0x4d and len(rest) >= 2:       # OP_PUSHDATA2
        n, body = le16_decode(rest[0:2]), rest[2:]
    elif op == 0x4e and len(rest) >= 4:       # OP_PUSHDATA4
        n, body = le32_decode(rest[0:4]), rest[4:]
    else:
        return b""
    if n != len(body):                        # truncated push or trailing bytes
        return b""
    return body

def check_height_commitment(coinbase, h: int, treasury_active: bool):
    if h < 2:
        return
    i = 0 if treasury_active else 1
    if len(coinbase.outputs) < i + 1:
        reject("missing height commitment output")
    out = coinbase.outputs[i]
    if out.script_version != 0:
        reject("height commitment script version")
    data = commitment_data(out.pk_script)
    if len(data) > 256 or len(data) < 4:
        reject("height commitment data length")
    if le32_decode(data[0:4]) != h % 2**32:
        reject("wrong height in coinbase")

dcrd: internal/blockchain/validate.go · checkCoinbaseUniqueHeight | txscript/tokenizer.go · ScriptTokenizer.Next

Minimal push encoding is not required: the height may be pushed with OP_PUSHDATA1, OP_PUSHDATA2 or OP_PUSHDATA4 as well as with a direct push, and the number is never interpreted with script-number semantics. Table 11.10 shows the 14-byte form that dcrd’s block template generator produces (a policy choice). The treasurybase is required to use exactly this form (Chapter 12).

Table 11.10. Standard coinbase height-commitment script (policy; 14 bytes)
FieldTypeBytesDescription
opcodebyte10x6a (OP_RETURN).
pushbyte10x0c (OP_DATA_12).
heightuint324Block height, little-endian (consensus: must equal the block height).
extra nonceuint648Random value chosen by the miner, little-endian.

11.4.4 Coinbase Amounts

The coinbase may pay out at most the subsidy it is entitled to plus the fees of the block, and its input must state the subsidy part exactly. The fees are the sum of the fees of all transactions of both trees of the block, as computed by the input checks of Chapter 7; the stake-tree fees (from tickets, votes, revocations, treasury adds and treasury spends) are added to those of the regular tree. A vote whose outputs total less than its inputs (the ticket amount plus the stakebase subsidy), as the fee limits of its ticket may allow (Chapter 8), therefore contributes the difference as a fee that the coinbase may claim. From StakeValidationHeight on, the fee total is scaled by the number of votes, so that a block with fewer than five votes can claim only part of its fees; the unclaimable part is destroyed.

Algorithm 11.5 · Coinbase amount checks

def check_coinbase_amounts(block, h: int, voters: int, variant, treasury_active: bool,
                           stake_fees: int64, regular_fees: list[int64]):
    fees: int64 = stake_fees              # fees of all stake-tree transactions, summed
                                          # with the same overflow check as below
    for f in regular_fees:                # regular-tree fees (coinbase contributes 0)
        fees = fees + f
        if overflows_int64(fees):
            reject("total fees overflow")
    if h >= StakeValidationHeight:
        fees = fees * voters // TicketsPerBlock
    if h == 1:
        expected = block_subsidy(1)       # fees are not added at height 1
    else:
        work = work_subsidy(h, voters, variant)
        if treasury_active:
            expected = work + fees        # treasury share is in the treasurybase
        else:
            expected = work + treasury_subsidy(h, voters, False) + fees
    coinbase = block.regular[0]
    if coinbase.inputs[0].value_in != expected - fees:
        reject("coinbase ValueIn does not commit to the subsidy")
    if sum(out.value for out in coinbase.outputs) > expected:
        reject("coinbase pays more than subsidy plus fees")

dcrd: internal/blockchain/validate.go · checkTransactionsAndConnect, checkConnectBlock

Rule 11.8 · Coinbase input value

The ValueIn of the coinbase input of a block at height ℎ≥1 MUST equal expected - fees as computed by Algorithm 11.5. For ℎ≥2 this is work_subsidy(h, v, variant) plus, while the treasury agenda is not active for the block, treasury_subsidy(h, v, False). For ℎ=1 it is the block-one subsidy minus the block’s fees.

dcrd: internal/blockchain/validate.go · checkTransactionsAndConnect

Rule 11.9 · Coinbase output total

The sum of the amounts of all outputs of the coinbase of a block at height ℎ≥1, including the treasury output and the height commitment where present, MUST NOT exceed expected as computed by Algorithm 11.5. Paying less is permitted; the difference is never created. The running fee total MUST NOT overflow int64.

dcrd: internal/blockchain/validate.go · checkTransactionsAndConnect

Note

At height 1 the fee total is necessarily zero: no output that a non-coinbase transaction could spend exists before block 1′s coinbase outputs mature, so block 1 cannot contain fee-paying transactions. The rules are stated as implemented nonetheless. The individual coinbase outputs of block 1 are fixed by Rule 11.14.

Implementation pitfall

The fee scaling uses the votes of the block whose coinbase is being checked and is applied to the combined fee total, with one truncation: for 999 atoms of fees and three votes the coinbase may claim ⌊999⋅35⌋=599 atoms. The fees are those of the block’s own two trees only; nothing from the parent block is included.

11.4.5 Disapproval and the Coinbase

When the votes of block 𝑁+1 disapprove block 𝑁 (Chapter 10), every transaction of 𝑁’s regular tree, the coinbase included, is disconnected as if it had never been mined, while 𝑁’s stake tree remains in effect. Consequently:

  • 𝑁’s proof-of-work subsidy and all fees its coinbase claimed are never created. This includes the stake-tree fees of 𝑁, which stay spent because 𝑁’s stake transactions remain valid.
  • Before the treasury agenda, the treasury payment in output 0 of 𝑁’s coinbase is lost as well. Afterwards the treasury share is paid by the treasurybase in the stake tree and survives disapproval, which DCP-0006 gives as an intended consequence.
  • The vote subsidies paid by 𝑁’s votes are unaffected.
  • The non-coinbase transactions of 𝑁’s regular tree, and their fees, return to the unconfirmed state and may be included again, by 𝑁+1 or later.

The coinbase of block 𝑁+1 is checked against 𝑁+1′s own subsidy and fees by Algorithm 11.5 whether or not it disapproves 𝑁.

11.4.6 Maturity

Outputs of a coinbase cannot be spent until CoinbaseMaturity =256 blocks have passed (the treasury balance and vote outputs have related maturity rules). These rules are specified in Chapter 7 and Chapter 12.

11.4.7 Coinbase Construction (Policy)

The following describes what dcrd’s block template generator produces; none of it is required beyond the rules above. Its coinbase has version 1 before the treasury agenda and 3 afterwards; a signature script of two zero bytes followed by the ASCII text /dcrd/; input sequence 0xffffffff; and the outputs, in order: the treasury payment (before the agenda), a zero-value height commitment of the form in Table 11.10 with a random extra nonce, and a single output paying the work subsidy to the miner’s address. For blocks above height 1, once the block’s transactions are selected, the fee total of both trees, scaled by the number of votes from StakeValidationHeight on exactly as in Algorithm 11.5, is added to that last output, so a dcrd-built coinbase claims its full entitlement. Its ValueIn is set as required by Rule 11.8 (the subsidy only, without the fees). Three cases differ: the coinbase of block 1 has only the ledger outputs; before the agenda, on a network whose BlockTaxProportion is zero, output 0 is a zero-value OP_TRUE script; and with no mining address configured the work output pays to OP_TRUE.

11.5 Subsidy Checks in the Stake Tree

Each vote (Chapter 8) has a stakebase input, its first input, which, like the coinbase input, spends nothing and whose ValueIn states the subsidy the vote creates. Its second input spends the ticket. The vote’s outputs pay the ticket amount plus the subsidy to the addresses committed to by the ticket; how that total is divided among the outputs is specified in Chapter 8. The following rules fix the amounts.

Rule 11.10 · Vote stakebase value

The ValueIn of the stakebase input of every vote MUST equal vote_subsidy(H, variant), where 𝐻 is the height of the block the vote votes on, as encoded in the vote itself, and variant is the split variant of the block containing the vote. Chapter 8 requires 𝐻=ℎ−1 for every vote in a block at height ℎ.

dcrd: internal/blockchain/validate.go · checkVoteInputs

Rule 11.11 · Vote output limits

For a block at height ℎ containing votes, let 𝐴= vote_subsidy(h - 1, variant), and for each vote let its excess be the sum of its output amounts minus the amount of the ticket output its second input spends.

  1. The excess of each vote MUST NOT exceed 𝐴.
  2. The sum of the excesses of all votes in the block MUST NOT exceed 𝐴⋅𝑣 if ℎ≥ StakeValidationHeight, where 𝑣 is the number of votes, and MUST NOT exceed 0 otherwise.

dcrd: internal/blockchain/validate.go · checkStakeBaseAmounts, getStakeBaseAmounts, checkTransactionsAndConnect

These two limits are implied by Rule 11.10 together with the general rule that outputs may not exceed inputs and the output commitments of Chapter 8, but dcrd checks them separately and they are consensus rules in their own right.

Rule 11.12 · Treasurybase amount

If the treasury agenda is active for a block at height ℎ≥2, both the amount of output 0 of its treasurybase and the ValueIn of the treasurybase’s input MUST equal treasury_subsidy(h, v, True), which does not depend on the number of votes 𝑣 once 𝑣≥𝑚. All other properties of the treasurybase are specified in Chapter 12.

dcrd: internal/blockchain/subsidy.go · checkTreasuryBase | internal/blockchain/validate.go · checkTransactionsAndConnect

Note

dcrd maintains a running “total subsidy” in its chain state (reported by its RPC interface) by adding, for each block, the coinbase ValueIn of the parent if the block approves it, the treasurybase ValueIn, and the stakebase ValueIn of each vote. The figure counts claimed subsidy, not the amounts actually paid out, and is not used by any consensus rule.

11.6 The Block-One Ledger

Decred has no subsidy at height 1 in the usual sense. Instead, the coinbase of block 1 must pay exactly the outputs listed in the network’s BlockOneLedger: an ordered list of entries, each a script version, a public key script and an amount. On the main network the ledger distributes 1680000 DCR, eight percent of 21 million: according to the Decred documentation [37], half to the project’s founding developers in compensation for initial development and half airdropped to registered participants.

Rule 11.13 · Block-one coinbase

If BlockOneLedger is non-empty, the coinbase of the block at height 1 MUST have lock time 0, expiry 0 (NoExpiryValue), and input sequence number 0xffffffff.

dcrd: internal/blockchain/subsidy.go · blockOneCoinbasePaysTokens

Rule 11.14 · Block-one outputs

If BlockOneLedger is non-empty, the coinbase of the block at height 1 MUST have exactly as many outputs as the ledger has entries, and for every index 𝑖, output 𝑖 MUST have the script version, the public key script (byte for byte) and the amount of ledger entry 𝑖. The order is significant. If the ledger is empty this rule imposes nothing.

dcrd: internal/blockchain/subsidy.go · blockOneCoinbasePaysTokens

Together with Rule 11.8 and Rule 11.9 this fixes the coinbase of block 1 completely except for its transaction version and its signature script (2 to 100 bytes). Block 1 has no height commitment and no treasury output. All four networks have a non-empty ledger, and every entry on every network is a version-0 pay-to-pubkey-hash script of 25 bytes (76 a9 14 ‖ 20-byte hash ‖ 88 ac).

Table 11.11. Block-one ledgers. The digest is BLAKE-256 over the concatenation, in ledger order, of each entry serialized as LE64(amount)‖LE16(version)‖varint(|script|)‖script, the serialization of the outputs in the block-one coinbase without the leading output count; it is given in natural byte order.
NetworkEntriesTotal (atoms)Ledger digest
mainnet3146168000000000000fc5c40905a817a6d6d2407648cdbb5ad39a2875c31c309f5ee62d7e33da737ab
testnet321000000000000080b7d8ec820546e6a40c7720435bf03f895812316bf3756d66dedb7cb0a04110
simnet330000000000000d6f72c64c85ed781166656e579807aede52e88aa97810fc3a359cfe29385020b
regnet33000000000000077b5ee4b9abcb50abb51322f4227aa9617524ac7f90dbbcb5f320f59a6fe1be2

The serialized main-network list is 113256 bytes (3146×36). A second identifier follows from the fact that a Decred transaction hash covers only the transaction prefix, which excludes the signature script and ValueIn (Chapter 4): the hash of block 1′s coinbase is determined by the ledger and the transaction version. With version 1, as on the main network, it is, in display form,

which matches the premine transaction identified in the Decred documentation [37].

Table 11.12. Main-network ledger: distribution of amounts
Amount (atoms)EntriesSubtotal (atoms)
50000000000016783500000000000
28263795424297284000000000128
2018018018021201801801802
80900900901180900900901
72072072072172072072072
63063063063163063063063
54054054054154054054054
18018018018118018018018
10090089962110090089962
3146168000000000000

The first main-network entry pays 500000000000 atoms to 76a91464e20eb6075561d30c23a517c5b73badbc120f0588ac and the last pays 28263795424 atoms to 76a9145e4cde3d3d959bbc1efe5e5f0f63b9fbe00f486488ac. The ledgers of the test and private networks are short enough to list in full (Table 11.13).

Table 11.13. Block-one ledgers of the test and private networks (all script version 0)
NetworkPublic key scriptAmount (atoms)
testnet376a914bb56576997d9f7abeebac585821b4d9a79d7ea0a88ac8000000000000
testnet376a9147a5c4cca76f2e0b36db4763daacbd6cbb6ee6e7b88ac2000000000000
simnet76a91494ff37a0ee4d48abc45f70474f9b86f9da69a70988ac10000000000000
simnet76a914a6753ebbc08e2553e7dd6d64bdead4bcbff4fcf188ac10000000000000
simnet76a9147aa3211c2ead810bbf5911c275c69cc196202bd888ac10000000000000
regnet76a9147e4765ae88ba9ad5c9e4715c484e90b34d358d5188ac10000000000000
regnet76a91402fb1ac0137666d79165e13cecd403883615270788ac10000000000000
regnet76a91469de627d3231b14228653dd09cba75eeb872754288ac10000000000000

Note

In the dcrd source the ledger exists in two forms. chaincfg/subsidydefinitions.go holds the human-readable list of (script, amount) entries per network; it is compiled only with the build tag subsidydefs and serves as the input to the generator chaincfg/generatesubsidytables.go. The generator writes chaincfg/subsidytables.go, which stores, per network, all scripts concatenated into one hexadecimal string and a list of (end offset, amount) pairs; at start-up these are sliced back into the entries of BlockOneLedger. Only the generated file is compiled into the node, and it is consensus-critical through Rule 11.14 and the block-one subsidy. The two forms were checked to agree entry for entry on all four networks. Earlier versions kept the list in a file named chaincfg/premine.go, which no longer exists.

11.7 Total Supply

The supply of decred is the block-one ledger plus everything paid by the subsidy rules. For a given history of agenda activations it is largest when every block from StakeValidationHeight on contains five votes, no block is disapproved, and every coinbase, vote and treasurybase claims its full entitlement. Under those assumptions, and with each split variant and the treasury agenda applied from its main-network activation height and never changed again (552448 for treasury, 657280 for DCP-0010, 794368 for DCP-0012: in each case the first block to which the new rules apply, the Active block of the deployment tables in [40], [38] and [39]), summing the per-block amounts of Table 11.8 over every height with dcrd’s subsidy functions gives the figures of Table 11.14. They are an upper bound on the main-network supply under these assumptions, not a value fixed by any consensus rule.

Table 11.14. Maximum main-network supply under the stated assumptions (atoms)
ComponentAtoms
Block-one ledger168000000000000
Proof-of-work subsidy779527937380932
Vote subsidy958890472085010
Treasury subsidy193583145837068
Total2100001555303010
Sum of 𝑆(ℎ) over ℎ≥2 (nominal, for comparison)1935831507356784
Less: 𝑆(ℎ)−𝑊−𝑇 of blocks 2 to 4095, which pay no vote share (4094 × 935874800; the table attributes 𝑉(ℎ) to the block at height ℎ that contains the votes, and the last row corrects for votes being paid at the rate of the block they vote on)3831471431200
Less: truncation 𝑆(ℎ)−𝑊−5𝑉(ℎ)−𝑇 of blocks from 4096 on37531264
Plus: net effect of votes in block ℎ earning 𝑉(ℎ−1) rather than 𝑉(ℎ)1556908690

The last four rows reconcile the total: 168000000000000+1935831507356784−3831471431200−37531264+1556908690=2100001555303010. Further results under the same assumptions:

  • The cumulative supply first exceeds 21×1014 atoms in block 8605295 (interval 1400). The maximum exceeds 21 million DCR by 1555303010 atoms, about 15.55 DCR, because of the one-block offset of the vote subsidy (Rule 11.3): without the last row of Table 11.14 the total would be 2099999998394320 atoms. The offset contributes, for each era of constant split variant, five times the per-vote subsidy at the start of the era minus five times that at its end (609923945+177802470+769182275 atoms for the three eras). dcrd’s own test suite, which sums 𝑉(ℎ) instead of 𝑉(ℎ−1), checks the figure 2099999999800912 for the original variant applied forever.
  • Under DCP-0012 the proof-of-work subsidy is last non-zero at height 10401791, the treasury subsidy at height 10954751, and the vote subsidy in block 10979328, whose five votes earn one atom each. No block after 10979328 creates any subsidy, although the full subsidy 𝑆 stays positive until height 11010047.
  • The realized supply is lower than the maximum: every missing vote forfeits one vote subsidy and part of the proof-of-work share (and, before the treasury agenda, part of the treasury share), every disapproved block forfeits its coinbase, and coinbases may claim less than allowed. MaxAmount (Chapter 2) bounds individual amounts and is not a supply cap; no consensus rule limits the cumulative supply.
Table 11.15. Main-network schedule by reduction interval (five votes per block). Per-block shares are for a block whose votes vote within the same interval, under the variant in force at the start of the interval (original through interval 106, DCP-0010 for intervals 107 to 129, DCP-0012 from interval 130); “Issued” is the total created in the interval and “Cumulative” includes the ledger. Interval 0 starts its vote share at height 4096.
𝑘First height𝑆WorkPer voteTreasuryIssuedCumulative
003119582664187174959818717495931195826615329005280848183329005280848
161443088695706185321742318532174230886957018976955665317202305960946165
2122883058114560183486873618348687330581145618789065012553221095025958718
3184323027836198181670171818167017130278361918603034647158239698060605876
4245762997857621179871457217987145729978576218418846204706258116906810582
5307202968175862178090551717809055129681758618236481376082276353388186664
10614402824117486169447049116944704928241174817351386294046364862896567950
251536002432552105145953126314595312624325521014945607418487605440778188861
503072001896827356113809641311380964118968273511654112947312934590216157870
8954681612867501317720500787720500712867501379057966343941309421832808688
10061440011533446576920067946920067911533446570861530142111391386193254264
10665126410865028356519017016519017010865028366754766712171432453826242617
107657408107574538110757453817211926010757453866093881961091439063214438726
129792576864249748864249741382799598642497453099573480481569006292865055
13079872085569281985569281523133218556928152573842648861574263677129941
15092160070127830870127831248275387012783043086601350121669136082867336
20012288004264044194264044758999864264044126198325207601838018828956872
3001843200157646462157646428061070157646469685812532952003143923576476
500307200021548080215480383555821548081323915830072086762823622948
7504608000179082517908318766179082110028140202098901612484732
10006144000148792148726484148799141425092099910396925214
125076800001232012321921232756634752099994163967890
1500921600097991749759965542100001050474236
1700104448009201695468162100001531476498
17821094860810011368642100001555180125
1786109731846010307202100001555303005
178710979328500052100001555303010
179111003904100002100001555303010
179211010048000002100001555303010

Intervals 89, 106 and 129 contain an activation (of treasury, DCP-0010 and DCP-0012 respectively); their “Issued” figures include both rules. The figures in this section other than 𝑆 are exact consequences of the rules only under the stated assumptions; 𝑆 and the share functions themselves are exact for every chain.

11.8 Summary of Checks

Table 11.16 maps each rule of this chapter to the error kind dcrd reports when it is violated, for use when testing an implementation against dcrd.

Table 11.16. Rules of this chapter and the corresponding dcrd error kinds
Ruledcrd error kind(s)
Rule 11.4ErrFirstTxNotCoinbase, ErrMultipleCoinbases
Rule 11.5ErrBadCoinbaseOutpoint, ErrBadCoinbaseFraudProof, ErrBadCoinbaseScriptLen
Rule 11.7ErrFirstTxNotCoinbase (missing output, wrong version, malformed or wrongly sized push), ErrCoinbaseHeight (wrong height)
Rule 11.6ErrNoTxOutputs, ErrNoTreasury
Rule 11.8ErrBadCoinbaseAmountIn
Rule 11.9ErrBadCoinbaseValue, ErrBadFees
Rule 11.10ErrBadStakebaseAmountIn
Rule 11.11ErrSSGenSubsidy (per vote), ErrBadStakebaseValue (total)
Rule 11.12ErrTreasurybaseOutValue (output), ErrBadTreasurybaseAmountIn (input)
Rule 11.13ErrBlockOneTx (lock time, expiry), ErrBlockOneInputs (sequence)
Rule 11.14ErrBlockOneOutputs