Skip to content

12 The Decentralized Treasury

A fixed share of every block subsidy is reserved for the development of the project. Since the activation of DCP-0006 [40] this share is not paid to an address but credited to an on-chain treasury account: a balance that exists only as consensus state, that no private key controls, and that can be debited only by a treasury spend transaction which is both signed by one of a small set of well-known keys and approved by the stakeholders through the ordinary proof-of-stake votes. This chapter specifies the account, the three transaction types that change it, the voting procedure for spends, and the three successive expenditure policies that limit how fast the account may be drawn down.

12.1 Background and Overview

12.1.1 The legacy arrangement

From block 2 until the activation of the treasury agenda, the coinbase transaction of every block was required to pay the treasury share of the subsidy in its output 0 to a fixed, network-specific script, OrganizationPkScript (on the main network a 2-of-3 pay-to-script-hash script controlled by a conventional legal entity), and from stake validation height on the amount was reduced in proportion to the number of votes in the block. The exact amounts and the coinbase rules of that era are specified in Chapter 11; the relevant facts here are that these payments created ordinary unspent outputs, that spending them required only the keys behind the organization script, and that they lived in the regular transaction tree, so that a block whose regular tree was disapproved by the next block’s voters also lost its treasury payment.

Rationale

DCP-0006 gives the motivation: the legacy treasury put sovereignty over spending in the hands of the key holders rather than the stakeholders, exposed the funds to theft, coercion or loss of key holders, and was insufficiently transparent. The decentralized treasury converts the treasury from an output model to an account model whose debits require a stakeholder vote.

12.1.2 The account model

With the treasury agenda active, value enters and leaves the treasury through three new kinds of stake transaction, all of transaction version 3 (TxVersionTreasury) and all carried in the stake tree:

Table 12.1. Treasury transaction types
TypeCreated byPer blockEffect on the treasury account
TreasurybaseThe block’s minerexactly one, first in the stake treeCredits the treasury share of the block subsidy. Replaces the legacy coinbase output.
Treasury add (TAdd)Anyoneat most 20Burns ordinary coins (its inputs) and credits the amount of its OP_TADD output.
Treasury spend (TSpend)Holders of a Politeia key (Pi key)only in treasury vote interval blocksDebits the treasury by its input value and creates OP_TGEN-tagged outputs paying the recipients.

The balance of the account is not stored in any output. Every full node computes it from the chain (Section 12.4). Credits and debits are subject to coinbase maturity: the value changes made by a block take effect in the balance CoinbaseMaturity blocks later.

A treasury spend names its own voting window through its Expiry field. Ticket holders vote yes or no on it by appending an optional output to their ordinary vote transactions (Section 12.8). The spend may be included only in a block whose height is a multiple of the treasury vote interval (TVI), only within its window, only once on a given chain, only with a quorum of votes and a sufficient yes majority, and only if the total spent stays within the expenditure policy in force (Section 12.9).

12.1.3 Activation

The rules of this chapter apply to a block exactly when the treasury agenda (DCP-0006) is active for the block in the sense of Chapter 13. In dcrd the question is always asked of the block’s parent: the agenda is active for block 𝐵 when it is active “as of the block after” 𝐵’s parent. The agenda is never active for the genesis block or for block 1, regardless of network.

History

On the main network the treasury agenda became active with block 552448; reverttreasurypolicy (DCP-0007) with block 657280; and maxtreasuryspend (DCP-0013) with block 1052416. These heights are informative. An implementation derives activation from the votes in the chain, as described in Chapter 13, and the other networks activate at different heights.

The balance of the treasury account starts at zero. Activation did not move any funds held under the legacy organization script: dcrd contains no code that credits a legacy balance, and the account balance is defined solely by the treasury transactions in blocks for which the agenda is active. Moving legacy funds into the account is possible only through ordinary treasury add transactions, which is one of the uses DCP-0006 names for them.

Activation of the treasury agenda changes several rules owned by other chapters. They are listed in Table 12.2 for orientation and those that concern treasury transactions are specified in Section 12.10.

Table 12.2. Rules changed by the treasury agenda
ChangeSpecified in
The coinbase transaction must have version 3; it no longer pays the treasury, and its height-encoding null-data output moves from output 1 to output 0.Chapter 11
The treasury subsidy is no longer reduced by the number of votes in the block.Chapter 11
The opcodes 0xc1, 0xc2 and 0xc3 are interpreted as OP_TADD, OP_TSPEND and OP_TGEN, and are forbidden in the outputs of regular transactions.Chapter 6, Rule 12.30
OP_TSPEND counts as a signature operation.Chapter 6, Section 12.10.1
Vote transactions may carry a final treasury-vote output.Chapter 8, Section 12.8.2
Outputs tagged OP_SSGEN or OP_SSRTX require CoinbaseMaturity confirmations instead of SStxChangeMaturity.Rule 8.22
Treasurybase, treasury add and treasury spend transactions are accepted in the stake tree.this chapter

12.2 Parameters and Constants

Table 12.3 lists the network parameters and constants used in this chapter with their main-network values. Abbreviations used in formulas are given in the second column. The values for the other networks are tabulated in Chapter 14.

Table 12.3. Treasury parameters and constants (main network)
NameSymbolValueMeaning
TreasuryVoteIntervalTVI288Treasury spends may only be included in blocks whose height is a nonzero multiple of TVI.
TreasuryVoteIntervalMultiplierTVIM12Length of a voting window in TVIs.
TreasuryVoteQuorumMultiplierTVQM1Quorum numerator.
TreasuryVoteQuorumDivisorTVQD5Quorum denominator (quorum 20%).
TreasuryVoteRequiredMultiplierTVRM3Required yes fraction numerator.
TreasuryVoteRequiredDivisorTVRD5Required yes fraction denominator (60%).
TreasuryExpenditureWindowTEW2Length of an expenditure policy window in voting windows.
TreasuryExpenditurePolicyTEP6Number of prior policy windows averaged (DCP-0006 policy only).
TreasuryExpenditureBootstrapTEB1600000000000Average assumed when no prior window has spends (DCP-0006 policy only), in atoms (16000 DCR).
PiKeys2 keysCompressed secp256k1 public keys allowed to sign treasury spends (Table 12.4).
CoinbaseMaturityCM256Maturity of treasury credits and debits and of OP_TGEN outputs.
TicketsPerBlockTPB5Votes per block; bounds the treasury vote count.
StakeValidationHeightSVH4096Treasury spend voting windows may not start before this height.
BaseSubsidy3119582664Initial block subsidy; defines the DCP-0013 floor.
TxVersionTreasury3Transaction version of all treasury transactions.
MaxTAddsPerBlock20Maximum number of treasury adds per block.
TSpendScriptLen100Exact length of a treasury spend signature script.
OP_TADD, OP_TSPEND, OP_TGEN0xc1, 0xc2, 0xc3Treasury opcodes (Chapter 6).
Table 12.4. Main-network Pi keys (PiKeys), as 33-byte compressed public keys
IndexPublic key
003f6e7041f1cf51ee10e0a01cd2b0385ce3cd9debaabb2296f7e9dee9329da946c
10319a37405cb4d1691971847d7719cfce70857c0f6e97d7c9174a3998cf0ab86dd

Several derived quantities recur. With the main-network values:

Voting window length
TVI⋅TVIM=3456 blocks.
Expenditure policy window 𝑊
TVI⋅TVIM⋅TEW=6912 blocks.
Maximum votes in a window
TPB⋅TVI⋅TVIM=17280.
Quorum
⌊17280⋅TVQMTVQD⌋=3456 votes.
Lower bound on the expiry of an includable spend
2+SVH+TVI⋅TVIM=7554 (Rule 12.21). The bound is not itself a valid expiry, because Expiry−2 must be a multiple of TVI; the smallest valid expiry is 7778, with window [4320,7776].
DCP-0013 spend floor
⌊BaseSubsidy10⌋⋅TVI⋅TVIM=1078127767296 atoms.
Test vector: Derived treasury quantities on every network
network   floor          W     maxVotes quorum bound minExp TVI TVIM CM  SVH
mainnet   1078127767296  6912  17280    3456   7554  7778   288 12   256 4096
testnet3  60000000000    960   1200     240    1010  1022   60  4    16  768
simnet    720000000000   576   720      144    290   290    48  3    16  144
regnet    60000000000    48    60       12     158   158    4   3    16  144

bound is 2+SVH+TVI⋅TVIM; minExp is the smallest expiry at or above it with Expiry−2 a multiple of TVI.

12.3 Classification of Treasury Transactions

Every transaction is classified as exactly one of: regular, ticket, vote, revocation, treasury add, treasury spend or treasurybase. The ticket, vote and revocation tests (Chapter 8) are applied first. A transaction that is none of these is tested for the three treasury types only if its version is at least 3, in the order treasury add, treasury spend, treasurybase; the first structural predicate that holds determines the type, and a transaction that satisfies none is regular. The three structural predicates are defined in Algorithm 12.3, Algorithm 12.4 and Algorithm 12.2. Each requires version exactly 3, and the three are mutually exclusive, so the order matters only for performance.

Classification is a pure function of the transaction and does not depend on whether the treasury agenda is active. The following two rules make the agenda’s state matter.

Rule 12.1 · Treasury transactions only in the stake tree

A block’s regular transaction tree MUST NOT contain any transaction that is classified as anything other than regular, including treasury add, treasury spend and treasurybase transactions. This rule applies whether or not the treasury agenda is active for the block.

dcrd: internal/blockchain/validate.go · checkBlockContext

Rule 12.2 · No treasury transactions before activation

If the treasury agenda is not active for a block, its stake tree MUST NOT contain any transaction classified as treasury add, treasury spend or treasurybase. (dcrd counts the stake transactions of each type it accepts, counting the treasury types only when the agenda is active, and rejects the block when the counts do not add up to the number of stake transactions.)

dcrd: internal/blockchain/validate.go · checkBlockContext

Rule 12.3 · Permitted stake transactions before stake validation height

In a block whose height is below StakeValidationHeight, every stake transaction MUST be a ticket, a treasury add or a treasurybase (the latter two only when the agenda is active). In particular a treasury spend is never valid below stake validation height.

dcrd: internal/blockchain/validate.go · checkBlockContext

The coinbase test of the regular tree (Chapter 11) also depends on the agenda and on the treasury spend format, because a treasury spend, like a coinbase, has a single input that references the null outpoint.

Rule 12.4 · Coinbase detection with the treasury active

When the treasury agenda is active, a transaction is a coinbase only if, in addition to the conditions of Chapter 11 (exactly one input whose previous outpoint has index 232−1 and the all-zero hash), its version is 3 and it is not treasury-spend-like. A transaction is treasury-spend-like when it has at least two outputs, its input 0 signature script and the scripts of outputs 0 and 1 are all non-empty, the last byte of the input 0 signature script is OP_TSPEND (0xc2), the first byte of the output 0 script is OP_RETURN (0x6a), and the first byte of the output 1 script is OP_TGEN (0xc3). Note that a treasurybase satisfies this coinbase test; dcrd excludes it explicitly wherever the distinction matters, as noted below.

dcrd: blockchain/standalone/tx.go · IsCoinBaseTx

12.4 The Treasury Balance

12.4.1 Treasury values of a block

Each block for which the treasury agenda is active carries a list of treasury values: signed amounts, in atoms, that change the treasury balance. Credits are positive and debits negative. The list is derived from the block’s stake tree in transaction order, as in Algorithm 12.1. The net change of a block is the sum of its values. A block for which the agenda is not active has no treasury values.

Algorithm 12.1 · Treasury values of a block

def treasury_values(block) -> list[tuple[str, int64]]:
    values = []
    for tx in block.stake_transactions:            # in block order
        t = classify(tx)
        if t == "tadd":
            values.append(("tadd", tx.outputs[0].value))   # change ignored
        elif t == "treasurybase":
            values.append(("tbase", tx.outputs[0].value))
        elif t == "tspend":
            total_out = 0
            for out in tx.outputs[1:]:                     # output 0 is the OP_RETURN
                values.append(("tspend", -out.value))
                total_out += out.value
            # The fee, recorded as a non-positive debit.
            values.append(("fee", total_out - tx.inputs[0].value_in))
    return values

def is_debit(kind) -> bool:
    return kind == "tspend" or kind == "fee"

def net_change(block) -> int64:
    return sum(amount for (_, amount) in treasury_values(block))

dcrd: internal/blockchain/treasury.go · dbPutTreasuryBalance

For a treasury spend the values sum to exactly −ValueIn of its single input: the payouts plus the recorded fee, which is ValueIn minus the payouts. The transaction fee (ValueIn minus the sum of all output values) is paid out of the treasury and, like every other stake-tree fee, is available to the block’s coinbase (Chapter 11). The two differ only by the value of output 0, which is a null-data output and is therefore destroyed.

12.4.2 Balance and maturity

Rule 12.5 · Treasury balance

Let 𝐵 be a block at height 𝐻 for which the treasury agenda is active, and let 𝐴 be the height of the earliest block on 𝐵’s chain for which the agenda is active. The treasury balance as of 𝐵 is

bal(𝐵)=∑ℎ=𝐴𝐻−CMnet(𝐵ℎ),

(12.1)

where 𝐵ℎ is 𝐵’s ancestor at height ℎ and the sum is zero when 𝐻−CM<𝐴. Equivalently, bal(𝐵)=0 if the agenda is not active for 𝐵’s parent or if 𝐻−CM<𝐴, and otherwise bal(𝐵)=bal(parent(𝐵))+net(𝐵𝐻−CM).

dcrd: internal/blockchain/treasury.go · calculateTreasuryBalance | internal/blockchain/chain.go · connectBlock

The balance as of 𝐵 therefore includes the values of 𝐵’s ancestor CoinbaseMaturity blocks back but none of the values of the CM most recent blocks, 𝐵 itself included. Credits (treasurybases and treasury adds) and debits (treasury spends and their fees) mature alike. With CM=256, the treasurybase of the first active block on the main network, 552448, first counts in the balance of block 552704.

The balance does not depend on the approval of any block by the following block’s voters. All treasury transactions are in the stake tree, which a disapproval vote never removes (Chapter 10). This is a deliberate change from the legacy arrangement, in which a disapproved block lost its treasury payment.

Implementation pitfall

The balance used to check a treasury spend (Rule 12.25) does not reflect debits from treasury spends mined in the preceding CM−1 blocks, because they have not yet matured. On the main network, testnet and simnet TVI>CM, so the spends of one TVI block have matured by the next. On regnet (TVI=4, CM=16) they have not. An implementation must use exactly the balance of Rule 12.5 and must not subtract immature debits. On regnet the balance of a later block can therefore become negative once the spends of several TVI blocks less than CM apart mature, each of which passed Algorithm 12.10; no consensus rule checks the balance of a block that contains no treasury spend. dcrd cannot record a negative balance in its treasury state and fails to connect such a block with an internal database error, not with a rule violation.

12.5 Treasurybase

The treasurybase carries the treasury share of the block subsidy into the account. It has a single input that, like a coinbase input, references no previous output and whose ValueIn states the amount created; an OP_TADD output whose value is that amount; and a null-data output that commits to the block height, which makes every treasurybase hash distinct.

Table 12.5. Treasurybase transaction
FieldTypeBytesDescription
Versionuint1623.
TxIn[0].PreviousOutPointoutpoint37Null outpoint: hash all zero, index 0xffffffff, tree 0 (regular).
TxIn[0].Sequenceuint324Unconstrained by consensus (dcrd writes 0xffffffff).
TxIn[0].ValueInint648The treasury subsidy for the block.
TxIn[0].BlockHeightuint3240x00000000 (null fraud proof).
TxIn[0].BlockIndexuint3240xffffffff (null fraud proof).
TxIn[0].SignatureScriptvarbytes1Empty.
TxOut[0].Valueint648The treasury subsidy for the block.
TxOut[0].Versionuint1620.
TxOut[0].PkScriptvarbytes2c1 (OP_TADD), exactly one byte.
TxOut[1].Valueint6480 (implied by the amount rules).
TxOut[1].Versionuint1620.
TxOut[1].PkScriptvarbytes1514 bytes: 6a 0c followed by LE32(height) and 8 arbitrary bytes.
LockTime, Expiryuint328Subject only to the general finality and expiry rules (Chapter 7).

Algorithm 12.2 · Treasurybase structure

NULL_OUTPOINT = (bytes(32), 0xffffffff, 0)        # (hash, index, tree)

def is_treasurybase(tx) -> bool:                    # full predicate (stake package)
    if tx.version != 3:                            return False
    if len(tx.inputs) != 1 or len(tx.outputs) != 2: return False
    if len(tx.inputs[0].signature_script) != 0:    return False
    if tx.inputs[0].previous_outpoint != NULL_OUTPOINT: return False
    if any(out.script_version != 0 for out in tx.outputs): return False
    if tx.outputs[0].pk_script != bytes([0xc1]):   return False   # OP_TADD only
    return is_strict_null_data(tx.outputs[1], 12)

def is_strict_null_data(out, n) -> bool:            # n <= 75
    s = out.pk_script
    return out.script_version == 0 and len(s) == 2 + n and s[0] == 0x6a and s[1] == n

def is_treasurybase_minimal(tx) -> bool:            # minimal predicate (standalone)
    return (tx.version == 3 and len(tx.inputs) == 1 and len(tx.outputs) == 2
            and len(tx.inputs[0].signature_script) == 0
            and tx.outputs[0].pk_script == bytes([0xc1])
            and len(tx.outputs[1].pk_script) == 14
            and tx.outputs[1].pk_script[0] == 0x6a
            and tx.outputs[1].pk_script[1] == 0x0c
            and tx.inputs[0].previous_outpoint == NULL_OUTPOINT)

dcrd: blockchain/stake/treasury.go · CheckTreasuryBase | blockchain/standalone/tx.go · IsTreasuryBase

is_strict_null_data is stated here for the lengths used in this chapter (12 and 32). For these lengths the general strict null-data test of Chapter 6 reduces to the form shown: OP_RETURN followed by the single canonical push opcode equal to the length, and nothing else. The minimal predicate differs from the full one only in not checking output script versions. It is used by the positional rules below. A transaction that passes the minimal predicate but not the full one is never valid, since it is then classified as regular, and a regular transaction is rejected in the stake tree (Rule 10.30) and fails the regular-tree checks elsewhere.

Rule 12.6 · Treasurybase required and unique

If the treasury agenda is active for a block, its stake tree MUST be non-empty and its first transaction MUST satisfy the minimal treasurybase predicate of Algorithm 12.2, and no other transaction in the stake tree MAY satisfy that predicate.

dcrd: internal/blockchain/validate.go · checkBlockContext

Rule 12.7 · Treasurybase form

The first stake transaction of a block for which the agenda is active MUST be classified as a treasurybase, so it MUST satisfy the full predicate of Algorithm 12.2. As a treasurybase it MUST additionally have a null fraud proof (BlockHeight = 0 and BlockIndex = 0xffffffff) and an empty signature script.

dcrd: blockchain/stake/treasury.go · CheckTreasuryBase | internal/blockchain/validate.go · checkTransactionContext

Rule 12.8 · Treasurybase height commitment

For a block at height 𝐻≥2 for which the agenda is active, output 1 of the treasurybase MUST have script version 0 and a script of exactly 14 bytes beginning 6a 0c, and bytes 2 to 5 of that script, read as a little-endian uint32, MUST equal 𝐻 (as uint32). The remaining 8 bytes are unconstrained.

dcrd: internal/blockchain/validate.go · checkTreasurybaseUniqueHeight

Rule 12.9 · Treasurybase amount

Let 𝑆 be the treasury subsidy for the block, computed as in Chapter 11 with the treasury agenda active (that is, not reduced by the number of votes). For a block at height 𝐻≥2 for which the agenda is active:

  • the treasurybase MUST have exactly two outputs, output 0 MUST have script version 0 and the one-byte script OP_TADD, and its value MUST equal 𝑆;
  • the ValueIn of its input MUST equal 𝑆;
  • the sum of its output values MUST NOT exceed its ValueIn. With the two preceding conditions, this forces output 1 to have value 0.

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

Rule 12.10 · Treasurybase creates no outputs

Connecting a treasurybase spends nothing and adds none of its outputs to the set of unspent transaction outputs. Its only effect on state is its treasury value (Algorithm 12.1).

dcrd: internal/blockchain/utxoviewpoint.go · connectStakeTransaction

A treasurybase has no signature operations (Section 12.10.1). Its input is not checked against any previous output and no script is executed for it.

Test vector: Treasurybase, main network, height 1052416, 5 votes

Treasury subsidy at height 1052416: 56903836 atoms (with the treasury agenda active; the legacy rule would give 34142301 with 3 votes). The 8 arbitrary bytes are 01 02 ... 08.

Serialized: 03000000010000000000000000000000000000000000000000000000000000000000000000ffffffff00ffffffff029c48640300000000000001c1000000000000000000000e6a0c000f100001020304050607080000000000000000019c4864030000000000000000ffffffff00

Transaction hash (display form): 9e57dfea4b6be2bcbab6c05e1b6a481b486fb7a81bcd2aeb168865128f202b5b

12.6 Treasury Add

A treasury add moves existing coins into the treasury account. Anyone may create one. It spends ordinary outputs, exactly like a regular transaction, and pays the amount to be credited into an OP_TADD output that is never spendable. Change, if any, must go to a stake change output.

Table 12.6. Treasury add transaction
FieldTypeBytesDescription
Versionuint1623.
TxIn[0..n-1]inputsvarOne or more ordinary inputs spending existing outputs, with ordinary signature scripts.
TxOut[0]outputvarValue: the amount credited to the treasury. Script version 0, script exactly c1 (OP_TADD).
TxOut[1]outputvarOptional. Stake change: script version 0, OP_SSTXCHANGE (0xbd) followed by a P2PKH or P2SH script; value nonzero.

Algorithm 12.3 · Treasury add structure

def is_p2pkh(s) -> bool:   # OP_DUP OP_HASH160 <20> OP_EQUALVERIFY OP_CHECKSIG
    return (len(s) == 25 and s[0] == 0x76 and s[1] == 0xa9 and s[2] == 0x14
            and s[23] == 0x88 and s[24] == 0xac)

def is_p2sh(s) -> bool:    # OP_HASH160 <20> OP_EQUAL
    return len(s) == 23 and s[0] == 0xa9 and s[1] == 0x14 and s[22] == 0x87

def is_tagged(out, opcode) -> bool:
    s = out.pk_script
    return (out.script_version == 0 and len(s) >= 1 and s[0] == opcode
            and (is_p2pkh(s[1:]) or is_p2sh(s[1:])))

def is_tadd(tx) -> bool:
    if tx.version != 3:                         return False
    if len(tx.inputs) < 1:                      return False
    if len(tx.outputs) not in (1, 2):           return False
    for out in tx.outputs:
        if out.script_version != 0 or len(out.pk_script) == 0:
            return False
    if tx.outputs[0].pk_script != bytes([0xc1]): return False    # OP_TADD only
    if len(tx.outputs) == 2 and not is_tagged(tx.outputs[1], 0xbd):
        return False                                            # OP_SSTXCHANGE
    return True

dcrd: blockchain/stake/treasury.go · CheckTAdd | blockchain/stake/scripttype.go · isTaggedScript

Rule 12.11 · Treasury add change

If a treasury add has two outputs, the value of output 1 MUST NOT be zero.

dcrd: internal/blockchain/validate.go · checkTransactionContext

Rule 12.12 · Treasury add inputs

No input of a treasury add MAY reference the null outpoint. Its inputs are subject to every input rule that applies to stake transactions (Chapter 7): they MUST reference existing unspent outputs, with correct fraud-proof fields, satisfying all maturity requirements; they MUST NOT spend outputs created in the same block (in either tree), except the historical outputs of Rule 8.23; they MUST NOT spend ticket (OP_SSTX) outputs; and the sum of the output values MUST NOT exceed the sum of the input values.

dcrd: internal/blockchain/validate.go · checkTransactionContext | internal/blockchain/validate.go · CheckTransactionInputs

Rule 12.13 · Treasury add limit

A block MUST NOT contain more than MaxTAddsPerBlock = 20 treasury adds.

dcrd: internal/blockchain/validate.go · checkBlockContext

Rule 12.14 · Treasury add outputs are unspendable

Output 0 of a treasury add is never added to the set of unspent transaction outputs. In addition, when the agenda is active for a block, no input of any transaction in it MAY spend an output whose script version is 0 and whose script is exactly the single byte 0xc1. (This matters only for such outputs created by regular transactions before activation, when 0xc1 was an unknown opcode.)

dcrd: internal/blockchain/utxoviewpoint.go · addTxOuts | internal/blockchain/validate.go · CheckTransactionInputs

The fee of a treasury add (inputs minus outputs) is a stake-tree fee and is available to the block’s coinbase. The change output is an ordinary OP_SSTXCHANGE output and matures under the general rule for stake change, after SStxChangeMaturity blocks, or after CoinbaseMaturity blocks if the treasury add has a nonzero Expiry (Chapter 7). The amount of output 0 may be zero; no rule forbids it. Treasury adds are permitted below stake validation height.

12.7 Treasury Spend

A treasury spend debits the account. It has a single input that references no previous output. Its ValueIn is the total amount taken from the treasury, and its signature script carries a Schnorr signature by one of the Pi keys. Output 0 commits to that amount and makes the transaction unique. Each further output pays a recipient.

12.7.1 Format

Table 12.7. Treasury spend transaction
FieldTypeBytesDescription
Versionuint1623.
TxIn[0].PreviousOutPointoutpoint37Null outpoint: hash all zero, index 0xffffffff, tree 0.
TxIn[0].Sequenceuint324Bit 31 (0x80000000, relative lock time disabled) must be set (Rule 12.19). dcrd writes 0xffffffff.
TxIn[0].ValueInint648Total debited from the treasury: sum of payouts plus fee.
TxIn[0].BlockHeightuint3240x00000000 (null fraud proof).
TxIn[0].BlockIndexuint3240xffffffff (null fraud proof).
TxIn[0].SignatureScriptvarbytes101Exactly 100 bytes, Table 12.8.
TxOut[0]output45Value: any (normally 0). Script version 0. Script: 34 bytes, Table 12.9.
TxOut[1..n]outputsvarAt least one. Script version 0. Script: OP_TGEN (0xc3) followed by a P2PKH (25-byte) or P2SH (23-byte) script.
LockTimeuint324Subject to the general finality rule.
Expiryuint324Determines the voting window (Section 12.8.1).
Table 12.8. Treasury spend signature script (100 bytes)
OffsetBytesContent
010x40 (OP_DATA_64)
164Schnorr signature, EC-Schnorr-DCRv0 encoding 𝑟‖𝑠 (Chapter 3). No hash-type byte.
6510x21 (OP_DATA_33)
6633Pi public key, compressed: first byte 0x02 or 0x03.
9910xc2 (OP_TSPEND)
Table 12.9. Treasury spend output 0 script (34 bytes)
OffsetBytesContent
010x6a (OP_RETURN)
110x20 (OP_DATA_32)
28LE64 of TxIn[0].ValueIn (two’s complement).
1024Arbitrary bytes. dcrd uses random bytes so that otherwise identical spends have distinct hashes.

Algorithm 12.4 · Treasury spend structure

def check_tspend(tx) -> tuple[bytes, bytes] | None:
    """Returns (signature, pubkey) if tx has the treasury spend form, else None."""
    if tx.version != 3:                              return None
    if len(tx.inputs) != 1 or len(tx.outputs) < 2:   return None
    for out in tx.outputs:
        if out.script_version != 0 or len(out.pk_script) == 0:
            return None
    s = tx.inputs[0].signature_script
    if len(s) != 100 or s[0] != 0x40 or s[65] != 0x21 or s[99] != 0xc2:
        return None
    signature, pubkey = s[1:65], s[66:99]
    if pubkey[0] not in (0x02, 0x03):                return None
    if not is_strict_null_data(tx.outputs[0], 32):   return None
    for out in tx.outputs[1:]:
        p = out.pk_script
        if p[0] != 0xc3:                             return None   # OP_TGEN
        if not (is_p2pkh(p[1:]) or is_p2sh(p[1:])):  return None
    return signature, pubkey

def is_tspend(tx) -> bool:
    return check_tspend(tx) is not None

dcrd: blockchain/stake/treasury.go · CheckTSpend

Note that the structural predicate does not test the previous outpoint of the input. It is tested by the next rule, so a transaction of the treasury spend form whose input references a real output is classified as a treasury spend and then rejected.

12.7.2 Transaction rules

Rule 12.15 · Treasury spend input

The input of a treasury spend MUST reference the null outpoint (all-zero hash, index 0xffffffff, tree 0), MUST have a null fraud proof (BlockHeight = 0, BlockIndex = 0xffffffff), and its signature script MUST be exactly 100 bytes long.

dcrd: internal/blockchain/validate.go · checkTransactionContext

Rule 12.16 · Treasury spend key

If the agenda is active for the block, the 33-byte public key at offset 66 of a treasury spend’s signature script MUST be byte-for-byte equal to one of the network’s PiKeys.

dcrd: internal/blockchain/validate.go · CheckTransactionInputs | chaincfg/params.go · PiKeyExists

Rule 12.17 · Treasury spend signature

If the agenda is active for the block, the 64 bytes at offset 1 of the signature script MUST parse as an EC-Schnorr-DCRv0 signature, the public key MUST parse as a secp256k1 point, and the signature MUST verify under that key for the message hash

𝑚=SigHash(SigHashAll,tx,0,subscript=empty),

(12.2)

that is, the signature hash of type SigHashAll (0x01) for input index 0 computed as specified in Chapter 6 with an empty subscript. Signature parsing and verification are specified in Chapter 3.

dcrd: internal/blockchain/treasury.go · verifyTSpendSignature | txscript/sign/sign.go · TSpendSignatureScript

The signature hash does not cover the input’s ValueIn (no Decred signature hash does). It covers every output, and output 0 commits to ValueIn, which Rule 12.18 requires to match; the key holder therefore fixes the exact amount, the recipients and the window (through Expiry). The signature script is not covered (signature scripts never are), and it is never executed by the script engine: script validation skips every input whose previous outpoint index is 0xffffffff (Chapter 6), so the signature is checked only by Rule 12.17.

Rule 12.18 · Treasury spend amounts

For a treasury spend in a block for which the agenda is active:

  • its ValueIn MUST satisfy 0≤ValueIn≤MaxAmount;
  • the eight bytes at offsets 2 to 9 of the output 0 script, read as a little-endian uint64 and reinterpreted as int64, MUST equal ValueIn;
  • the sum of all its output values MUST NOT exceed ValueIn. The difference is the fee.

dcrd: internal/blockchain/validate.go · checkTreasurySpendInputs | internal/blockchain/validate.go · CheckTransactionInputs

Rule 12.19 · Treasury spend sequence number

If the lnfeatures agenda (relative lock times, Chapter 7) is active for the block, bit 31 (0x80000000, SequenceLockTimeDisabled) of the Sequence field of a treasury spend’s input MUST be set.

dcrd: internal/blockchain/sequencelock.go · calcSequenceLock | internal/blockchain/validate.go · checkConnectBlock

Implementation pitfall

Rule 12.19 is not stated in DCP-0006. It follows from the general relative lock-time rule. That rule is evaluated for every stake transaction of version 2 or higher that is neither a coinbase nor a vote, and for each input without the disable bit it looks up the referenced output. A treasury spend is not a coinbase (Rule 12.4) and its input references the null outpoint, which never exists, so the block is rejected (dcrd reports ErrMissingTxOut). The behaviour was confirmed by running dcrd with a treasury spend whose sequence number is 0. The treasurybase is a coinbase under Rule 12.4 and is exempt. On the main network lnfeatures became active long before treasury, so the rule applies to every treasury spend there. dcrd’s memory pool does not evaluate sequence locks for treasury spends (policy), so it may accept treasury spends that no block may contain.

12.7.3 Inclusion in a block

The following rules restrict where a treasury spend may appear. They reference the voting window and vote tally defined in Section 12.8 and the expenditure check of Section 12.9.

Rule 12.20 · Treasury spends only on a TVI

If the agenda is active for a block at height 𝐻>1 and 𝐻modTVI≠0, the block MUST NOT contain any treasury spend.

dcrd: internal/blockchain/validate.go · checkBlockContext

Rule 12.21 · Full voting window after stake validation height

If the agenda is active for a block at height 𝐻>1 with 𝐻modTVI=0, every treasury spend in the block MUST have Expiry≥2+SVH+TVI⋅TVIM (compared as unsigned 64-bit integers), so that its voting window starts at or after stake validation height.

dcrd: internal/blockchain/validate.go · checkBlockContext

Rule 12.22 · Treasury spend inside its window

Every treasury spend in a block at height 𝐻 MUST have a valid expiry (Rule 12.27) and MUST satisfy start≤𝐻≤end, where (start,end) is its voting window and the comparison is on the uint32 value of 𝐻.

dcrd: internal/blockchain/validate.go · tspendChecks | blockchain/standalone/treasury.go · InsideTSpendWindow

Rule 12.23 · Treasury spend not previously mined

A block MUST NOT contain a treasury spend whose transaction hash equals that of a treasury spend contained in any of the block’s ancestors. Within a single block the general rule against duplicate transactions applies (Chapter 10).

dcrd: internal/blockchain/validate.go · tspendChecks | internal/blockchain/treasury.go · checkTSpendExists

Rule 12.24 · Treasury spend approved

Every treasury spend in a block MUST pass the vote check of Algorithm 12.8 for that block.

dcrd: internal/blockchain/validate.go · tspendChecks | internal/blockchain/treasury.go · checkTSpendHasVotes

Rule 12.25 · Treasury expenditure

For a block at height 𝐻 with 𝐻modTVI=0 for which the agenda is active, let 𝑇 be the sum of the ValueIn of all treasury spends in the block (as int64; the block is invalid if the sum overflows). If 𝑇>0, the block MUST pass Algorithm 12.10.

dcrd: internal/blockchain/validate.go · tspendChecks | internal/blockchain/treasury.go · checkTSpendsExpenditure

A treasury spend has no inputs to spend, so connecting it adds its outputs to the set of unspent outputs and marks nothing spent. Output 0 is a null-data script and is never added, and neither is a payout of value zero (Chapter 7).

Rule 12.26 · Maturity of treasury payouts

If the agenda is active for a block, an input in it that spends an output whose script is OP_TGEN-tagged (script version 0, first byte 0xc3, followed by a P2PKH or P2SH script) MUST satisfy ℎspend−ℎorigin≥CM, where ℎspend is the height of the spending block and ℎorigin the height of the block containing the treasury spend.

dcrd: internal/blockchain/validate.go · CheckTransactionInputs

Because a treasury spend always has a nonzero Expiry, its outputs are also subject to the general rule that outputs of transactions with an expiry require CoinbaseMaturity confirmations (Chapter 7), which imposes the same bound.

Test vector: Signed treasury spend (simnet)

Simnet Pi key 0, private key 62deae1ab2b1ebd96a28c80e870aee325bed359e83d8db2464ef999e616a9eef, public key 02a36b785d584555696b69d1b2bbeff4010332b301e3edd316d79438554cacb3e7. One payout of 10000000000 atoms to the P2PKH hash 11×20, fee 10000, so ValueIn = 10000010000. The arbitrary bytes of output 0 are 00 01 ... 17. Expiry 1154 (computed for a next block height of 1000 on simnet: window [1008, 1152]). Sequence 0xffffffff, lock time 0.

Unsigned serialization (empty signature script): 03000000010000000000000000000000000000000000000000000000000000000000000000ffffffff00ffffffff0200000000000000000000226a20100b0c5402000000000102030405060708090a0b0c0d0e0f101112131415161700e40b540200000000001ac376a914111111111111111111111111111111111111111188ac000000008204000001100b0c540200000000000000ffffffff00

Signature hash (SigHashAll, input 0, empty subscript): 49e42bae2fc61c807b3f3e8dd9cc67b3fdc04bc9da01084731c97d256e0dae8d

Signature (𝑟‖𝑠, deterministic): bdf258f7e1441340a762bac301884a2237b1b05c3e26a58487258e6c360f1bdc7ee535af48c50bbb1f59a61c09fc0024c578b41ec2e1e61aca7c08f704671780

Signed serialization: 03000000010000000000000000000000000000000000000000000000000000000000000000ffffffff00ffffffff0200000000000000000000226a20100b0c5402000000000102030405060708090a0b0c0d0e0f101112131415161700e40b540200000000001ac376a914111111111111111111111111111111111111111188ac000000008204000001100b0c540200000000000000ffffffff6440bdf258f7e1441340a762bac301884a2237b1b05c3e26a58487258e6c360f1bdc7ee535af48c50bbb1f59a61c09fc0024c578b41ec2e1e61aca7c08f7046717802102a36b785d584555696b69d1b2bbeff4010332b301e3edd316d79438554cacb3e7c2

Transaction hash (display form): 8dfae941b11684372a19d55c100ef79c130ab7676b8cd546f89664e7b0b2a6ea

Decreasing the payout value by one atom without re-signing makes verification fail.

12.8 Treasury Spend Voting

12.8.1 The voting window

A treasury spend carries no explicit window. The window is derived from its Expiry field, which therefore has a restricted form: it must be exactly two more than a nonzero multiple of TVI and large enough for a whole window to fit above height zero.

Rule 12.27 · Treasury spend expiry and window

The expiry 𝑒 (a uint32) of a treasury spend is valid if and only if 𝑒≥TVI⋅TVIM+2 and (𝑒−2)modTVI=0. The voting window of a treasury spend with a valid expiry is the pair

start=𝑒−TVI⋅TVIM−2,end=𝑒−2.

(12.3)

A treasury spend with an invalid expiry is outside every window and can never be included in a block.

dcrd: blockchain/standalone/treasury.go · CalcTSpendWindow

Both bounds are multiples of TVI, and end−start=TVI⋅TVIM. The window is used in two different ways:

  • Votes are counted from blocks at heights start through 𝐻−1, where 𝐻≤end is the height of the block that includes the spend. Votes in a block at height end or above can never count, so for voting the window is the half-open interval [start,end).
  • Inclusion is allowed in TVI blocks at heights start≤𝐻≤end, an interval closed at both ends. Since no votes have been counted at 𝐻=start and the quorum is positive on every network, a spend can never be included at 𝐻=start. Even if every ticket votes yes, the earliest inclusion is at the first TVI 𝐻 with TPB⋅(𝐻−start)≥⌊TPB⋅TVI⋅TVIM⋅TVRMTVRD⌋ (start+2304 on the main network, see Algorithm 12.8).

The + 2 exists because of transaction expiry. A transaction is invalid in a block at height ℎ when Expiry≠0 and ℎ≥Expiry (Chapter 7), and the memory pool removes transactions one block early. With end=𝑒−2, a spend remains valid, and in the memory pool, at its last possible inclusion height. The general expiry rule never rejects a treasury spend that satisfies Rule 12.22, since then 𝐻≤𝑒−2<𝑒.

Wallets and the Pi key holders compute the expiry for a new spend from the height of the next block 𝑛 as in Algorithm 12.5. Nothing requires this choice; it yields the earliest window that starts strictly after 𝑛.

Algorithm 12.5 · Window computation and conventional expiry

def tspend_window(expiry: uint32) -> tuple[uint32, uint32] | None:
    if expiry < TVI * TVIM + 2:
        return None                                  # invalid expiry
    if (expiry - 2) % TVI != 0:                     # expiry - 2 > 0 here
        return None
    return expiry - TVI * TVIM - 2, expiry - 2      # (start, end)

def inside_tspend_window(height: int64, expiry: uint32) -> bool:
    w = tspend_window(expiry)
    if w is None:
        return False
    start, end = w
    return start <= uint32(height) <= end

# Non-normative: the expiry chosen by wallets for a spend created when the
# next block will be at height n (n >= 0).
def tspend_expiry(n: int) -> uint32:
    next_tvi = n + (TVI - n % TVI)                  # strictly greater than n
    return uint32(next_tvi + TVI * TVIM + 2)

dcrd: blockchain/standalone/treasury.go · CalcTSpendWindow | blockchain/standalone/treasury.go · CalcTSpendExpiry | blockchain/standalone/treasury.go · InsideTSpendWindow

Test vector: Voting windows (main network: TVI 288, TVIM 12)
next height n   expiry    start     end       note
1052415         1056098   1052640   1056096
1052416         1056098   1052640   1056096   (activation block of DCP-0013)
1052640         1056386   1052928   1056384   n is itself a TVI

expiry 3457     invalid   (below TVI*TVIM + 2 = 3458)
expiry 3458     start 0, end 3456
expiry 3459     invalid   (3457 not a multiple of 288)
expiry 1056097  invalid;  expiry 1056096  invalid

inside(h, expiry 1056098): h=1052640 true, 1052641 true, 1056096 true, 1056097 false

12.8.2 The treasury vote output

A ticket holder votes on treasury spends through the vote transaction it already casts when its ticket is selected (Chapter 8). With the treasury agenda, a vote transaction may end with one extra null-data output that lists (treasury spend hash, vote) pairs. Chapter 8 specifies the rest of the vote format and refers here for this output: its vote predicate calls parse_treasury_votes of Algorithm 12.6. In a vote with only two outputs the last output is the vote bits output itself, so that output is then the one parsed (Chapter 8).

Table 12.10. Treasury vote output (last output of a vote)
OffsetBytesContent
010x6a (OP_RETURN)
11 or 2Push opcode: OP_DATA_N with 𝑁=2+33𝑘≤75 (so 𝑘≤2), or 0x4c (OP_PUSHDATA1) followed by a length byte 𝐿=2+33𝑘≤255 (so 𝑘≤7).
𝑝2Discriminator 54 56 (ASCII TV), where 𝑝 = 2 for OP_DATA_N and 3 for OP_PUSHDATA1.
𝑝+2+33𝑖32Hash of the 𝑖-th treasury spend voted on, in internal byte order (not reversed).
𝑝+34+33𝑖1Vote: 0x01 yes or 0x02 no.

Algorithm 12.6 · Treasury vote output parsing

def is_null_data(out) -> bool:
    # Script version 0 and: OP_RETURN alone, or OP_RETURN followed by
    # exactly one push (OP_0, OP_1..OP_16, OP_DATA_1..OP_DATA_75,
    # OP_PUSHDATA1/2/4) that consumes the
    # rest of the script and pushes at most 256 bytes. Non-canonical pushes
    # are allowed. Parsing is as in the script chapter.
    ...

def parse_treasury_votes(s: bytes) -> list[tuple[bytes, int]]:
    # s is a script already known to be null data
    if len(s) < 4 or s[1] > 0x4c:                   # beyond OP_PUSHDATA1
        reject("ErrSSGenInvalidDiscriminatorLength")
    p = 3 if s[1] == 0x4c else 2
    if p + 2 > len(s):
        reject("ErrSSGenInvalidNullScript")
    if s[p:p+2] != b"TV":                           # 0x54 0x56
        reject("ErrSSGenUnknownDiscriminator")
    body = s[p+2:]
    if len(body) < 33 or len(body) % 33 != 0:
        reject("ErrSSGenInvalidTVLength")
    votes, seen = [], set()
    for i in range(0, len(body), 33):
        h, v = body[i:i+32], body[i+32]
        if v not in (0x01, 0x02):                   # 0x01 yes, 0x02 no
            reject("ErrSSGenInvalidTreasuryVote")
        if h in seen:                               # no duplicate tspend
            reject("ErrSSGenDuplicateTreasuryVote")
        seen.add(h)
        votes.append((h, v))
    return votes

def treasury_votes(vote_tx) -> list[tuple[bytes, int]]:
    last = vote_tx.outputs[-1]
    if not is_null_data(last):
        return []                                   # no treasury vote output
    votes = parse_treasury_votes(last.pk_script)
    if vote_tx.version != 3:                        # TxVersionTreasury
        reject("ErrSSGenInvalidTxVersion")
    return votes

dcrd: blockchain/stake/staketx.go · CheckSSGenVotes | blockchain/stake/staketx.go · GetSSGenTreasuryVotes | blockchain/stake/staketx.go · IsNullDataScript

Rule 12.28 · Treasury vote output

If the last output of a vote transaction is a null-data script (as defined in Algorithm 12.6), the vote MUST pass every check of Algorithm 12.6: the output MUST be a well-formed treasury vote output listing at least one pair, every vote byte MUST be 0x01 or 0x02, no treasury spend hash MAY appear twice, and the vote transaction’s version MUST be 3. A transaction that fails these checks is not a vote at all; it is then classified as regular, and a block containing it in its stake tree is invalid because the stake tree may not contain regular transactions (Chapter 10).

dcrd: blockchain/stake/staketx.go · CheckSSGenVotes | blockchain/stake/staketx.go · GetSSGenTreasuryVotes

The number of pairs is limited only by the push encoding: at most 2 with OP_DATA_N and at most 7 with OP_PUSHDATA1, since its length byte cannot exceed 255 and pushes larger than OP_PUSHDATA1 are rejected. No rule requires a hash to identify an existing treasury spend: a vote may name any 32 bytes. Pairs whose hash matches no includable spend are simply never counted. A vote byte of 0x00 is invalid; to abstain, a voter omits the spend.

Implementation pitfall

The treasury vote output counts toward the vote’s limit of MaxOutputsPerSSGen = 66 outputs (Chapter 8), which dcrd’s source notes “should technically be increased by 1” but cannot be without a consensus vote. When the agenda is active the output is excluded from the count of payment outputs that must match the ticket’s commitments. When the agenda is not active it is not excluded, so a vote carrying a treasury vote output then fails the payee checks of Chapter 8. Treasury vote outputs are therefore effectively invalid before activation.
Test vector: Treasury vote outputs

One yes vote for the treasury spend of the previous vector (OP_RETURN OP_DATA_35 'T' 'V' <hash> 01): 6a235456eaa6b2b0e76496f846d58c6b67b70a139cf70e105cd5192a378416b141e9fa8d01

Note the internal byte order of the hash; its display form is 8dfae941b11684372a19d55c100ef79c130ab7676b8cd546f89664e7b0b2a6ea. Three pairs (104-byte script, OP_PUSHDATA1 with length 101) and seven pairs (236-byte script, length 233) both parse. The same hash listed twice fails with ErrSSGenDuplicateTreasuryVote; a vote byte of 0x03 fails with ErrSSGenInvalidTreasuryVote.

12.8.3 Tallying and approval

The tally for a treasury spend 𝑋 considered for inclusion in block 𝐵 at height 𝐻 counts every yes and no pair naming 𝑋’s hash in every vote transaction in the stake trees of 𝐵’s ancestors at heights start through 𝐻−1. Votes in 𝐵 itself are not counted. Each ticket votes at most once, so no further deduplication is needed. Votes are counted by inclusion height, regardless of maturity and regardless of whether the regular tree of the block containing them was approved.

Algorithm 12.7 · Treasury spend vote tally

def tally(B, X) -> tuple[uint32, uint32, uint32, uint32]:
    w = tspend_window(X.expiry)
    if w is None:
        reject("ErrInvalidTSpendWindow")    # or ErrInvalidTreasurySpendExpiry
    start, end = w
    if not inside_tspend_window(B.height, X.expiry):
        reject("ErrInvalidTSpendWindow")
    yes: uint32 = 0
    no: uint32 = 0
    n = B.parent
    while n is not None and n.height >= start:
        for stx in n.stake_transactions:
            if not is_vote(stx):            # staking chapter's vote predicate
                continue
            for (h, v) in treasury_votes(stx):
                if h == txhash(X):
                    if v == 0x01: yes += 1  # overflow would reject the block
                    if v == 0x02: no += 1   # (unreachable in practice)
        n = n.parent
    return start, end, yes, no

dcrd: internal/blockchain/treasury.go · tSpendCountVotes

The approval test requires a quorum of all possible votes in the window and a yes count of at least TVRM/TVRD of the votes already cast plus all votes that could still be cast before the end of the window. Counting the remaining votes as potential no votes lets a spend with an insurmountable yes majority be approved at an earlier TVI (“short-circuiting”). There is no corresponding early rejection in consensus. A spend that fails simply cannot be included, and once its window has passed it can never be included.

Algorithm 12.8 · Treasury spend approval

def check_tspend_votes(B, X):
    start, end, yes, no = tally(B, X)
    max_votes = uint32(uint32(TPB) * (end - start))           # uint32 product
    quorum = uint64(max_votes) * TVQM // TVQD                 # uint64
    cast = uint64(uint32(yes + no))
    if cast < quorum:
        reject("ErrNotEnoughTSpendVotes")                     # quorum not met
    remaining_blocks = uint32(end - uint32(B.height))         # >= 0, see tally
    max_remaining = uint64(uint32(remaining_blocks * uint32(TPB)))
    required = (cast + max_remaining) * TVRM // TVRD           # uint64
    if uint64(yes) < required:
        reject("ErrNotEnoughTSpendVotes")                     # not enough yes votes

dcrd: internal/blockchain/treasury.go · checkTSpendHasVotes

In Algorithm 12.8 remaining_blocks is end−𝐻, which is non-negative because the tally has already checked 𝐻≤end. All products fit easily in their types on every network. The widths are stated because dcrd computes them that way.

Note

With the main-network values the threshold has a simple form when every ticket votes on the spend: cast+remaining=17280, so the required number of yes votes is ⌊17280⋅35⌋=10368, a constant. The earliest approval with unanimous yes votes from a window starting at height 𝑠 is at the first TVI 𝐻 with 5(𝐻−𝑠)≥10368, that is 𝐻=𝑠+2304 (8 TVIs).
Test vector: Approval at each TVI of a main-network window

Expiry 7778, the smallest valid on the main network, window [4320, 7776]. Votes per block in heights 4320 to 7775. Each entry gives the TVI block height and the counted yes/no votes, followed by “pass” or the reason for failure.

5 yes per block
  4320  0/0      quorum            5184  4320/0    yes < 10368
  4608  1440/0   quorum            5760  7200/0    yes < 10368
  4896  2880/0   quorum            6336  10080/0   yes < 10368
                                   6624  11520/0   pass (and every later TVI)
3 yes, 2 no per block
  6624  6912/4608   yes < 10368 (remaining 5760)
  7488  9504/6336   yes < 10368 (remaining 1440)
  7776  10368/6912  pass (exactly 60%)
1 yes, 4 abstaining per block
  7488  3168/0   quorum (3456)    7776  3456/0   pass (quorum exactly; required 2073)
as above but no vote at height 4320
  7776  3455/0   quorum

12.8.4 Summary of inclusion conditions

A treasury spend 𝑋 may be included in block 𝐵 at height 𝐻 exactly when all of the following hold, in addition to the transaction rules of Section 12.7.2 and the general rules for stake transactions:

Table 12.11. Conditions for including a treasury spend
ConditionRule
The treasury agenda is active for 𝐵 and 𝐻≥SVH.Rule 12.2, Rule 12.3
𝐻modTVI=0.Rule 12.20
𝑋.Expiry≥2+SVH+TVI⋅TVIM.Rule 12.21
𝑋.Expiry is valid and start≤𝐻≤end.Rule 12.27, Rule 12.22
𝑋 is not in any ancestor of 𝐵.Rule 12.23
Quorum and yes threshold are met, counting votes in [start,𝐻−1].Rule 12.24
The total of all spends in 𝐵 passes the balance and policy checks.Rule 12.25

There is no consensus limit on the number of treasury spends in a block other than the block size and signature operation limits. (The memory pool holds at most seven, see Section 12.10.5.) A spend that is mined on one chain may be mined again on a competing chain that does not contain it, since Rule 12.23 considers only ancestors.

12.9 Expenditure Policy

Even an approved treasury spend may be included only if the treasury can afford it and the total spent in the recent past stays below a limit. The limit has had three definitions, each selected by an agenda. All three work on expenditure policy windows of 𝑊=TVI⋅TVIM⋅TEW consecutive blocks counted backwards from the parent of the TVI block being validated, and all three sum treasury values by inclusion height (the block containing the transaction), not by maturity.

12.9.1 Common procedure

Algorithm 12.9 · Window sums

def window_sums(n, count: int) -> tuple[int64, int64, Block | None]:
    """Sums the treasury values of `count` blocks: n and its ancestors, newest
    first. Returns (spent, added, next older block or None)."""
    spent = added = 0
    for _ in range(count):
        if n is None:
            break
        if not treasury_active(n):       # no treasury values: stop for good
            n = None
            break
        for (kind, amount) in treasury_values(n):
            if is_debit(kind):
                spent += -amount         # treasury spend payouts and fees
            else:
                added += amount          # treasurybases and treasury adds
        n = n.parent
    return spent, added, n

dcrd: internal/blockchain/treasury.go · sumPastTreasuryChanges

For each treasury spend, spent includes exactly its ValueIn. Since the agenda never becomes inactive again, stopping at the first block without treasury values is the same as letting all earlier blocks contribute nothing.

Algorithm 12.10 · Expenditure check

def check_expenditure(B, total: int64):
    # B: a block at a TVI height for which the treasury agenda is active.
    # total: sum of ValueIn of all treasury spends in B (> 0).
    bal = treasury_balance(B)                  # balance as of B (rule above)
    if bal - total < 0:
        reject("ErrInvalidExpenditure")        # treasury may not go negative
    P = B.parent
    if agenda_active("maxtreasuryspend", B):          # DCP-0013
        allowed = max_spend_dcp0013(P)
    elif agenda_active("reverttreasurypolicy", B):    # DCP-0007
        allowed = max_spend_dcp0007(P)
    else:                                             # DCP-0006
        allowed = max_spend_dcp0006(P)
    if total > allowed:
        reject("ErrInvalidExpenditure")

dcrd: internal/blockchain/treasury.go · checkTSpendsExpenditure | internal/blockchain/treasury.go · maxTreasuryExpenditure

The policy is selected by the agendas active for 𝐵 (asked of 𝑃 in dcrd’s terms), with maxtreasuryspend taking precedence over reverttreasurypolicy regardless of whether the latter is active. In every policy the recent window covers heights 𝐻−𝑊 through 𝐻−1 for a TVI block at height 𝐻.

12.9.2 The original policy (DCP-0006)

The original policy limits the spends in the recent window to 150% of the average spending of the TEP preceding windows, ignoring windows without any spending. When none of them has spending, the bootstrap value TEB is used as the average.

Algorithm 12.11 · Maximum expenditure, DCP-0006

def max_spend_dcp0006(P) -> int64:
    W = TVI * TVIM * TEW
    spent_recent, _, n = window_sums(P, W)          # heights H-W .. H-1
    prior_total = 0
    nonempty = 0
    # iteration i = 0..TEP-1 covers heights H-(i+2)W .. H-(i+1)W-1
    for _ in range(TEP):
        if n is None:
            break
        spent, _, n = window_sums(n, W)
        if spent > 0:
            prior_total += spent
            nonempty += 1
    if nonempty > 0:
        avg = prior_total // nonempty
    else:
        avg = TEB
    allowance = avg + avg // 2
    return allowance - spent_recent if allowance > spent_recent else 0

dcrd: internal/blockchain/treasury.go · maxTreasuryExpenditureDCP0006

History

The DCP-0006 policy bases the limit on past spending rather than on income, unlike the policy in the original Politeia proposal for the decentralized treasury, and according to DCP-0007 it prevented payments from the treasury from being made. The reverttreasurypolicy agenda replaced it. On the main network it governs TVI blocks from 552448 up to but not including 657280.

12.9.3 The reverted policy (DCP-0007)

The reverttreasurypolicy agenda (DCP-0007 [41]) limits spends in the recent window to 150% of the treasury’s income (treasurybases and treasury adds) in the same window.

Algorithm 12.12 · Maximum expenditure, DCP-0007

def max_spend_dcp0007(P) -> int64:
    W = TVI * TVIM * TEW
    spent, added, _ = window_sums(P, W)             # heights H-W .. H-1
    allowance = added + added // 2
    return allowance - spent if allowance > spent else 0

dcrd: internal/blockchain/treasury.go · maxTreasuryExpenditureDCP0007

12.9.4 The balance-based policy (DCP-0013)

The maxtreasuryspend agenda (DCP-0013 [42]) limits the spends in a policy window to 4% of the balance the treasury would have had without those spends, but never less than a fixed floor and never more than the balance itself. The floor is the treasury subsidy of one voting window at the initial, unreduced subsidy rate. It adds no network parameter: the floor is computed from BaseSubsidy, TVI and TVIM.

𝐹=⌊BaseSubsidy10⌋⋅TVI⋅TVIM

(12.4)

Algorithm 12.13 · Maximum expenditure, DCP-0013

FLOOR = (BaseSubsidy // 10) * (TVI * TVIM)      # 1078127767296 on mainnet

def max_spend_dcp0013(P) -> int64:
    W = TVI * TVIM * TEW
    spent, _, _ = window_sums(P, W)                 # heights H-W .. H-1
    bal = treasury_balance(child_of(P))             # balance as of the TVI block
    max_spendable = (bal + spent) * 4 // 100        # int64; operands non-negative
    if max_spendable < FLOOR:
        max_spendable = FLOOR
    allowed = max_spendable - spent if max_spendable > spent else 0
    if allowed > bal:
        allowed = bal
    return allowed

dcrd: internal/blockchain/treasury.go · maxTreasuryExpenditureDCP0013 | internal/blockchain/chain.go · New

child_of(P) is the TVI block being validated, so bal is the same balance used by the non-negativity check of Algorithm 12.10. Adding spent back approximates the balance before the window’s spends. It is exact only if those spends have already matured, which on the main network holds for spends in all earlier TVI blocks. The division by 10 in the floor is part of the definition. It is not tied to the treasury proportion of the subsidy.

History

Under DCP-0007 the limit shrinks with the block subsidy and would eventually leave most of the accumulated balance unspendable. DCP-0013 targets a maximum loss of about 20% of the treasury in the event of a key compromise (five policy windows of 4% each during the roughly four months a consensus change takes) while the floor keeps the limit stable over the emission schedule. On the main network the DCP-0013 policy governs TVI blocks from 1052416 on.

12.9.5 Test vectors

The three policy functions were evaluated by dcrd’s own code on synthetic main-network treasury states: every block from height 2 is given a treasurybase of 108 atoms (the agenda is never active for block 1, Section 12.1.3). The round amount stands in for the subsidy schedule; the vectors exercise the policy arithmetic only. The block being validated is the TVI block at height 48384 (the parent is at 48383). The windows are therefore: recent [41472,48383], and prior windows [34560,41471], [27648,34559], [20736,27647], [13824,20735], [6912,13823] and [0,6911]. Each treasury spend below has a fee of 10000 atoms included in the stated ValueIn.

Test vector: Expenditure limits for the TVI block at height 48384
S0: no treasury spends or adds.
    balance 4812700000000 (48127 tbases), recent spent 0, added 691200000000
    DCP-0006  2400000000000   (bootstrap: 16000 DCR * 1.5)
    DCP-0007  1036800000000   (6912 DCR * 1.5)
    DCP-0013  1078127767296   (4% of balance below floor; floor < balance)

S1: spends with ValueIn 12000 DCR at 20160, 9000 DCR at 34560, 5000 DCR at 43200;
    treasury add 500 DCR at 45000.
    balance 2262700000000, recent spent 500000000000, added 741200000000
    DCP-0006  1075000000000   (avg of 2 non-empty windows 10500 DCR; 15750 - 5000)
    DCP-0007  611800000000    (7412 * 1.5 = 11118 DCR; minus 5000)
    DCP-0013  578127767296    (floor - 5000 DCR)

S2: as S1 plus a treasury add of 1000000 DCR at height 1000.
    balance 102262700000000, recent spent 500000000000
    DCP-0006  1075000000000,  DCP-0007  611800000000 (unchanged)
    DCP-0013  3610508000000   ((1022627 + 5000) * 4% = 41105.08 DCR; minus 5000)

A block at height 48384 whose treasury spends total exactly the stated limit passes the policy check, and one atom more fails it.

12.10 Interactions with Other Rules

12.10.1 Signature operations

The signature operation limits of Chapter 10 apply to treasury transactions with the following treasury-specific counting, specified in full in Chapter 6:

Rule 12.29 · Signature operations of treasury transactions

When the agenda is active: a treasurybase counts zero signature operations; each OP_TSPEND in a script counts one signature operation (so the input of a treasury spend counts one); outputs are counted as for any transaction (an OP_TGEN-tagged P2PKH output counts one for its OP_CHECKSIG; an OP_TGEN-tagged P2SH output counts zero); and treasury spends and treasurybases contribute no pay-to-script-hash signature operations. A treasury add is counted like any other transaction.

dcrd: internal/blockchain/validate.go · countSigOps | internal/blockchain/validate.go · countP2SHSigOps | txscript/script.go · countSigOpsV0

Treasury transactions count toward the block size like any other transaction. There is no separate size limit.

12.10.2 Regular transactions and treasury opcodes

Rule 12.30 · No treasury opcodes in regular outputs

When the agenda is active for a block, no output script of a transaction classified as regular MAY contain any of the opcodes 0xc1, 0xc2 or 0xc3, in addition to the stake opcodes 0xba to 0xbd that are always forbidden there (Chapter 7). Scripts are parsed as in Chapter 6. A parse failure rejects the block.

dcrd: internal/blockchain/validate.go · checkTransactionContext | txscript/script.go · ContainsStakeOpCodes

When the agenda is active, scripts are executed with the treasury script flag, under which 0xc1 to 0xc3 are the treasury opcodes rather than unknown opcodes reserved for upgrades. Their execution semantics, and the handling of OP_TGEN-tagged scripts when their outputs are spent, belong to Chapter 6.

12.10.3 Maturity of vote and revocation outputs

When the treasury agenda is active for the spending block, an output whose script is tagged with OP_SSGEN or OP_SSRTX matures after CoinbaseMaturity blocks instead of SStxChangeMaturity. The rule is Rule 8.22.

Note

This change is not mentioned in DCP-0006 but is part of the code that implements it. On the main network it raised the maturity of vote and revocation outputs from 1 to 256 blocks.

12.10.4 Other interactions

  • Disapproval. A treasurybase, treasury add or treasury spend is never undone by disapproval of its block’s regular tree. Treasury adds may spend outputs of the parent’s regular tree like any stake transaction; if the parent is disapproved, those outputs do not exist and the treasury add is invalid (Chapter 10).
  • Fees. The fees of treasury adds and treasury spends are stake-tree fees available to the coinbase. The treasurybase has no fee.
  • Header commitments. The version 2 compact filters committed to by the block header include the payout scripts of treasury spends, the previous output scripts spent by treasury adds and the change scripts of treasury adds (Chapter 16).

12.10.5 Memory pool and mining policy (non-normative)

The following is dcrd policy, not consensus:

  • A treasurybase is never accepted into the memory pool.
  • A treasury spend is accepted only if the treasury agenda is active, the next block is at or above stake validation height, its expiry is valid, its voting window does not start 2⋅TVI⋅TVIM or more blocks after the next block, its Pi key is known and its signature valid, and it has not been mined in an ancestor of the current tip. The memory pool holds at most seven treasury spends at a time (MempoolMaxConcurrentTSpends), matching the maximum number of pairs in one treasury vote output.
  • Treasury adds and treasury spends must pay at least the minimum relay fee.
  • Voting wallets append treasury votes for the spends in their memory pool according to their configured policy.
  • The block template generator includes, in TVI blocks, those treasury spends that pass the vote check, subject to the maximum expenditure for the block. It creates the treasurybase with random bytes after the height.

12.11 Error Kinds

Table 12.12 maps the error kinds that dcrd reports for violations of the rules in this chapter to the rules. It is informative: only validity matters for consensus, not which error is reported.

Table 12.12. dcrd error kinds and the rules they correspond to
Error kindRule
ErrStakeTxInRegularTree, ErrNonstandardStakeTx, ErrInvalidEarlyStakeTxRule 12.1, Rule 12.2, Rule 12.3
ErrFirstTxNotTreasurybase, ErrMultipleTreasurybasesRule 12.6, Rule 12.8
ErrTreasuryBaseInvalid* (stake), ErrBadTreasurybaseOutpoint, ErrBadTreasurybaseFraudProof, ErrBadTreasurybaseScriptLenRule 12.7
ErrTreasurybaseTxNotOpReturn, ErrTreasurybaseHeightRule 12.8
ErrInvalidTreasurybaseTxOutputs, ErrInvalidTreasurybaseVersion, ErrInvalidTreasurybaseScript, ErrTreasurybaseOutValue, ErrBadTreasurybaseAmountIn, ErrSpendTooHighRule 12.9
ErrTAddInvalid* (stake)Algorithm 12.3 (classification)
ErrInvalidTAddChangeRule 12.11
ErrTooManyTAddsRule 12.13
ErrBadTxInput (spending an OP_TADD output)Rule 12.14
ErrTSpendInvalid* (stake)Algorithm 12.4 (classification)
ErrBadTSpendOutpoint, ErrBadTSpendFraudProof, ErrBadTSpendScriptLenRule 12.15
ErrUnknownPiKeyRule 12.16
ErrInvalidPiSignatureRule 12.17
ErrBadTxInput, ErrInvalidTSpendValueIn, ErrSpendTooHighRule 12.18
ErrMissingTxOut (sequence lock)Rule 12.19
ErrNotTVIRule 12.20
ErrInvalidTVoteWindowRule 12.21
ErrInvalidTSpendWindow, ErrInvalidTreasurySpendExpiryRule 12.27, Rule 12.22
ErrTSpendExistsRule 12.23
ErrNotEnoughTSpendVotes, ErrTooManyTreasurySpendVotes (surfaced by block validation as ErrNotEnoughTSpendVotes)Rule 12.24
ErrInvalidExpenditure, ErrBadTxOutValue (sum overflow)Rule 12.25
ErrImmatureSpend, ErrExpiryTxSpentEarlyRule 12.26, Rule 8.22
ErrSSGenInvalidDiscriminatorLength, ErrSSGenInvalidNullScript, ErrSSGenUnknownDiscriminator, ErrSSGenInvalidTVLength, ErrSSGenInvalidTreasuryVote, ErrSSGenDuplicateTreasuryVote, ErrSSGenInvalidTxVersionRule 12.28
ErrRegTxCreateStakeOut, ErrScriptMalformedRule 12.30
ErrTooManySigOpsRule 12.29