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:
| Type | Created by | Per block | Effect on the treasury account |
|---|---|---|---|
| Treasurybase | The block’s miner | exactly one, first in the stake tree | Credits the treasury share of the block subsidy. Replaces the legacy coinbase output. |
| Treasury add (TAdd) | Anyone | at most 20 | Burns 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 blocks | Debits 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 thetreasury 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.
treasury agenda| Change | Specified 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.
| Name | Symbol | Value | Meaning |
|---|---|---|---|
TreasuryVoteInterval | TVI | 288 | Treasury spends may only be included in blocks whose height is a nonzero multiple of TVI. |
TreasuryVoteIntervalMultiplier | TVIM | 12 | Length of a voting window in TVIs. |
TreasuryVoteQuorumMultiplier | TVQM | 1 | Quorum numerator. |
TreasuryVoteQuorumDivisor | TVQD | 5 | Quorum denominator (quorum 20%). |
TreasuryVoteRequiredMultiplier | TVRM | 3 | Required yes fraction numerator. |
TreasuryVoteRequiredDivisor | TVRD | 5 | Required yes fraction denominator (60%). |
TreasuryExpenditureWindow | TEW | 2 | Length of an expenditure policy window in voting windows. |
TreasuryExpenditurePolicy | TEP | 6 | Number of prior policy windows averaged (DCP-0006 policy only). |
TreasuryExpenditureBootstrap | TEB | 1600000000000 | Average assumed when no prior window has spends (DCP-0006 policy only), in atoms (16000 DCR). |
PiKeys | 2 keys | Compressed secp256k1 public keys allowed to sign treasury spends (Table 12.4). | |
CoinbaseMaturity | CM | 256 | Maturity of treasury credits and debits and of OP_TGEN outputs. |
TicketsPerBlock | TPB | 5 | Votes per block; bounds the treasury vote count. |
StakeValidationHeight | SVH | 4096 | Treasury spend voting windows may not start before this height. |
BaseSubsidy | 3119582664 | Initial block subsidy; defines the DCP-0013 floor. | |
TxVersionTreasury | 3 | Transaction version of all treasury transactions. | |
MaxTAddsPerBlock | 20 | Maximum number of treasury adds per block. | |
TSpendScriptLen | 100 | Exact length of a treasury spend signature script. | |
OP_TADD, OP_TSPEND, OP_TGEN | 0xc1, 0xc2, 0xc3 | Treasury opcodes (Chapter 6). |
PiKeys), as 33-byte compressed public keys| Index | Public key |
|---|---|
| 0 | 03f6e7041f1cf51ee10e0a01cd2b0385ce3cd9debaabb2296f7e9dee9329da946c |
| 1 | 0319a37405cb4d1691971847d7719cfce70857c0f6e97d7c9174a3998cf0ab86dd |
Several derived quantities recur. With the main-network values:
- Voting window length
- blocks.
- Expenditure policy window
- blocks.
- Maximum votes in a window
- .
- Quorum
- votes.
- Lower bound on the expiry of an includable spend
- (Rule 12.21). The bound is not itself a valid expiry, because must be a multiple of TVI; the smallest valid expiry is 7778, with window .
- DCP-0013 spend floor
- 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 144bound is ; minExp is the smallest expiry at or above it with 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 thetreasury agenda is active for the block.dcrd: internal/blockchain/validate.go · checkBlockContext
Rule 12.2 · No treasury transactions before activation
If thetreasury 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 belowStakeValidationHeight, 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 thetreasury 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 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
(12.1)
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 most recent blocks, itself included. Credits (treasurybases and treasury adds) and debits (treasury spends and their fees) mature alike. With , 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 blocks, because they have not yet matured. On the main network, testnet and simnet , so the spends of one TVI block have matured by the next. On regnet (, ) 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.
| Field | Type | Bytes | Description |
|---|---|---|---|
| Version | uint16 | 2 | 3. |
| TxIn[0].PreviousOutPoint | outpoint | 37 | Null outpoint: hash all zero, index 0xffffffff, tree 0 (regular). |
| TxIn[0].Sequence | uint32 | 4 | Unconstrained by consensus (dcrd writes 0xffffffff). |
| TxIn[0].ValueIn | int64 | 8 | The treasury subsidy for the block. |
| TxIn[0].BlockHeight | uint32 | 4 | 0x00000000 (null fraud proof). |
| TxIn[0].BlockIndex | uint32 | 4 | 0xffffffff (null fraud proof). |
| TxIn[0].SignatureScript | varbytes | 1 | Empty. |
| TxOut[0].Value | int64 | 8 | The treasury subsidy for the block. |
| TxOut[0].Version | uint16 | 2 | 0. |
| TxOut[0].PkScript | varbytes | 2 | c1 (OP_TADD), exactly one byte. |
| TxOut[1].Value | int64 | 8 | 0 (implied by the amount rules). |
| TxOut[1].Version | uint16 | 2 | 0. |
| TxOut[1].PkScript | varbytes | 15 | 14 bytes: 6a 0c followed by (height) and 8 arbitrary bytes. |
| LockTime, Expiry | uint32 | 8 | Subject 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 thetreasury 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 for which the agenda is active, output 1 of the treasurybase MUST have script version 0 and a script of exactly 14 bytes beginning6a 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 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
ValueInof 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.
| Field | Type | Bytes | Description |
|---|---|---|---|
| Version | uint16 | 2 | 3. |
| TxIn[0..n-1] | inputs | var | One or more ordinary inputs spending existing outputs, with ordinary signature scripts. |
| TxOut[0] | output | var | Value: the amount credited to the treasury. Script version 0, script exactly c1 (OP_TADD). |
| TxOut[1] | output | var | Optional. 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 Truedcrd: 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 thanMaxTAddsPerBlock = 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¶
| Field | Type | Bytes | Description |
|---|---|---|---|
| Version | uint16 | 2 | 3. |
| TxIn[0].PreviousOutPoint | outpoint | 37 | Null outpoint: hash all zero, index 0xffffffff, tree 0. |
| TxIn[0].Sequence | uint32 | 4 | Bit 31 (0x80000000, relative lock time disabled) must be set (Rule 12.19). dcrd writes 0xffffffff. |
| TxIn[0].ValueIn | int64 | 8 | Total debited from the treasury: sum of payouts plus fee. |
| TxIn[0].BlockHeight | uint32 | 4 | 0x00000000 (null fraud proof). |
| TxIn[0].BlockIndex | uint32 | 4 | 0xffffffff (null fraud proof). |
| TxIn[0].SignatureScript | varbytes | 101 | Exactly 100 bytes, Table 12.8. |
| TxOut[0] | output | 45 | Value: any (normally 0). Script version 0. Script: 34 bytes, Table 12.9. |
| TxOut[1..n] | outputs | var | At least one. Script version 0. Script: OP_TGEN (0xc3) followed by a P2PKH (25-byte) or P2SH (23-byte) script. |
| LockTime | uint32 | 4 | Subject to the general finality rule. |
| Expiry | uint32 | 4 | Determines the voting window (Section 12.8.1). |
| Offset | Bytes | Content |
|---|---|---|
| 0 | 1 | 0x40 (OP_DATA_64) |
| 1 | 64 | Schnorr signature, EC-Schnorr-DCRv0 encoding (Chapter 3). No hash-type byte. |
| 65 | 1 | 0x21 (OP_DATA_33) |
| 66 | 33 | Pi public key, compressed: first byte 0x02 or 0x03. |
| 99 | 1 | 0xc2 (OP_TSPEND) |
| Offset | Bytes | Content |
|---|---|---|
| 0 | 1 | 0x6a (OP_RETURN) |
| 1 | 1 | 0x20 (OP_DATA_32) |
| 2 | 8 | of TxIn[0].ValueIn (two’s complement). |
| 10 | 24 | Arbitrary 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 Nonedcrd: 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’sPiKeys.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
(12.2)
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
ValueInMUST satisfy ; - the eight bytes at offsets 2 to 9 of the output 0 script, read as a little-endian
uint64and reinterpreted asint64, MUST equalValueIn; - 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 thelnfeatures 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 reportsErrMissingTxOut). 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 and , 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 with , every treasury spend in the block MUST have (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 , where is its voting window and the comparison is on theuint32 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 for which the agenda is active, let be the sum of theValueIn of all treasury spends in the block (as int64; the block is invalid if the sum overflows). If , 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 isOP_TGEN-tagged (script version 0, first byte 0xc3, followed by a P2PKH or P2SH script) MUST satisfy , where is the height of the spending block and 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 1120, 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 and . The voting window of a treasury spend with a valid expiry is the pair
(12.3)
dcrd: blockchain/standalone/treasury.go · CalcTSpendWindow
Both bounds are multiples of TVI, and . The window is used in two different ways:
- Votes are counted from blocks at heights through , where is the height of the block that includes the spend. Votes in a block at height or above can never count, so for voting the window is the half-open interval .
- Inclusion is allowed in TVI blocks at heights , an interval closed at both ends. Since no votes have been counted at and the quorum is positive on every network, a spend can never be included at . Even if every ticket votes yes, the earliest inclusion is at the first TVI with ( 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 and (Chapter 7), and the memory pool removes transactions one block early. With , 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 .
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 false12.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).
| Offset | Bytes | Content |
|---|---|---|
| 0 | 1 | 0x6a (OP_RETURN) |
| 1 | 1 or 2 | Push opcode: OP_DATA_N with (so ), or 0x4c (OP_PUSHDATA1) followed by a length byte (so ). |
| 2 | Discriminator 54 56 (ASCII TV), where = 2 for OP_DATA_N and 3 for OP_PUSHDATA1. | |
| 32 | Hash of the -th treasury spend voted on, in internal byte order (not reversed). | |
| 1 | Vote: 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 votesdcrd: 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 ofMaxOutputsPerSSGen = 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 through . 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, nodcrd: 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 votesdcrd: internal/blockchain/treasury.go · checkTSpendHasVotes
In Algorithm 12.8 remaining_blocks is , which is non-negative because the tally has already checked . 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: , so the required number of yes votes is , a constant. The earliest approval with unanimous yes votes from a window starting at height is at the first TVI with , that is (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 quorum12.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:
| Condition | Rule |
|---|---|
The treasury agenda is active for and . | Rule 12.2, Rule 12.3 |
| . | Rule 12.20 |
| . | Rule 12.21 |
| is valid and . | Rule 12.27, Rule 12.22 |
| is not in any ancestor of . | Rule 12.23 |
| Quorum and yes threshold are met, counting votes in . | 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 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, ndcrd: 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 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 0dcrd: 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. Thereverttreasurypolicy 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 0dcrd: 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.
(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 alloweddcrd: 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 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 , and prior windows , , , , and . 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; eachOP_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 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.
| Error kind | Rule |
|---|---|
ErrStakeTxInRegularTree, ErrNonstandardStakeTx, ErrInvalidEarlyStakeTx | Rule 12.1, Rule 12.2, Rule 12.3 |
ErrFirstTxNotTreasurybase, ErrMultipleTreasurybases | Rule 12.6, Rule 12.8 |
ErrTreasuryBaseInvalid* (stake), ErrBadTreasurybaseOutpoint, ErrBadTreasurybaseFraudProof, ErrBadTreasurybaseScriptLen | Rule 12.7 |
ErrTreasurybaseTxNotOpReturn, ErrTreasurybaseHeight | Rule 12.8 |
ErrInvalidTreasurybaseTxOutputs, ErrInvalidTreasurybaseVersion, ErrInvalidTreasurybaseScript, ErrTreasurybaseOutValue, ErrBadTreasurybaseAmountIn, ErrSpendTooHigh | Rule 12.9 |
ErrTAddInvalid* (stake) | Algorithm 12.3 (classification) |
ErrInvalidTAddChange | Rule 12.11 |
ErrTooManyTAdds | Rule 12.13 |
ErrBadTxInput (spending an OP_TADD output) | Rule 12.14 |
ErrTSpendInvalid* (stake) | Algorithm 12.4 (classification) |
ErrBadTSpendOutpoint, ErrBadTSpendFraudProof, ErrBadTSpendScriptLen | Rule 12.15 |
ErrUnknownPiKey | Rule 12.16 |
ErrInvalidPiSignature | Rule 12.17 |
ErrBadTxInput, ErrInvalidTSpendValueIn, ErrSpendTooHigh | Rule 12.18 |
ErrMissingTxOut (sequence lock) | Rule 12.19 |
ErrNotTVI | Rule 12.20 |
ErrInvalidTVoteWindow | Rule 12.21 |
ErrInvalidTSpendWindow, ErrInvalidTreasurySpendExpiry | Rule 12.27, Rule 12.22 |
ErrTSpendExists | Rule 12.23 |
ErrNotEnoughTSpendVotes, ErrTooManyTreasurySpendVotes (surfaced by block validation as ErrNotEnoughTSpendVotes) | Rule 12.24 |
ErrInvalidExpenditure, ErrBadTxOutValue (sum overflow) | Rule 12.25 |
ErrImmatureSpend, ErrExpiryTxSpentEarly | Rule 12.26, Rule 8.22 |
ErrSSGenInvalidDiscriminatorLength, ErrSSGenInvalidNullScript, ErrSSGenUnknownDiscriminator, ErrSSGenInvalidTVLength, ErrSSGenInvalidTreasuryVote, ErrSSGenDuplicateTreasuryVote, ErrSSGenInvalidTxVersion | Rule 12.28 |
ErrRegTxCreateStakeOut, ErrScriptMalformed | Rule 12.30 |
ErrTooManySigOps | Rule 12.29 |