Documentation ¶
Overview ¶
Package standalone provides standalone functions useful for working with the Decred blockchain consensus rules.
The primary goal of offering these functions via a separate module is to reduce the required dependencies to a minimum as compared to the blockchain module.
It is ideal for applications such as lightweight clients that need to ensure basic security properties hold and calculate appropriate vote subsidies and block explorers.
For example, some things an SPV wallet needs to prove are that the block headers all connect together, that they satisfy the proof of work requirements, and that a given transaction tree is valid for a given header.
Function categories ¶
The provided functions fall into the following categories:
- Proof-of-work
- Merkle root calculation
- Subsidy calculation
- Coinbase transaction identification
- Merkle tree inclusion proofs
- Transaction sanity checking
Proof-of-work ¶
- Converting to and from the compact target difficulty representation
- Calculating work values based on the compact target difficulty
- Checking a block hash satisfies a target difficulty and that target difficulty is within a valid range
- Calculating required target difficulties using the ASERT algorithm
Merkle root calculation ¶
- Calculation from individual leaf hashes
- Calculation from a slice of transactions
Subsidy calculation ¶
- Proof-of-work subsidy for a given height and number of votes
- Stake vote subsidy for a given height
- Treasury subsidy for a given height and number of votes
Merkle tree inclusion proofs ¶
- Generate an inclusion proof for a given tree and leaf index
- Verify a leaf is a member of the tree at a given index via the proof
Errors ¶
The errors returned by this package are of type standalone.RuleError. This allows the caller to differentiate between errors further up the call stack through type assertions. In addition, callers can programmatically determine the specific rule violation by examining the ErrorCode field of the type asserted standalone.RuleError.
Index ¶
- Constants
- func BigToCompact(n *big.Int) uint32
- func CalcASERTDiff(startDiffBits uint32, powLimit *big.Int, ...) uint32
- func CalcCombinedTxTreeMerkleRoot(regularTxns, stakeTxns []*wire.MsgTx) chainhash.Hash
- func CalcMerkleRoot(leaves []chainhash.Hash) chainhash.Hash
- func CalcMerkleRootInPlace(leaves []chainhash.Hash) chainhash.Hash
- func CalcTSpendExpiry(nextBlockHeight int64, tvi, multiplier uint64) uint32
- func CalcTSpendWindow(expiry uint32, tvi, multiplier uint64) (uint32, uint32, error)
- func CalcTxTreeMerkleRoot(transactions []*wire.MsgTx) chainhash.Hash
- func CalcWork(bits uint32) *big.Int
- func CheckProofOfWork(powHash *chainhash.Hash, difficultyBits uint32, powLimit *big.Int) error
- func CheckProofOfWorkHash(powHash *chainhash.Hash, difficultyBits uint32) error
- func CheckProofOfWorkRange(difficultyBits uint32, powLimit *big.Int) error
- func CheckTransactionSanity(tx *wire.MsgTx, maxTxSize uint64) error
- func CompactToBig(compact uint32) *big.Int
- func GenerateInclusionProof(leaves []chainhash.Hash, leafIndex uint32) []chainhash.Hash
- func HashToBig(hash *chainhash.Hash) *big.Int
- func InsideTSpendWindow(blockHeight int64, expiry uint32, tvi, multiplier uint64) bool
- func IsCoinBaseTx(tx *wire.MsgTx, isTreasuryEnabled bool) bool
- func IsTreasuryBase(tx *wire.MsgTx) bool
- func IsTreasuryVoteInterval(height, tvi uint64) bool
- func VerifyInclusionProof(root, leaf *chainhash.Hash, leafIndex uint32, proof []chainhash.Hash) bool
- type ErrorKind
- type RuleError
- type SubsidyCache
- func (c *SubsidyCache) CalcBlockSubsidy(height int64) int64
- func (c *SubsidyCache) CalcStakeVoteSubsidy(height int64) int64deprecated
- func (c *SubsidyCache) CalcStakeVoteSubsidyV2(height int64, useDCP0010 bool) int64deprecated
- func (c *SubsidyCache) CalcStakeVoteSubsidyV3(height int64, splitVariant SubsidySplitVariant) int64
- func (c *SubsidyCache) CalcTreasurySubsidy(height int64, voters uint16, isTreasuryEnabled bool) int64
- func (c *SubsidyCache) CalcWorkSubsidy(height int64, voters uint16) int64deprecated
- func (c *SubsidyCache) CalcWorkSubsidyV2(height int64, voters uint16, useDCP0010 bool) int64deprecated
- func (c *SubsidyCache) CalcWorkSubsidyV3(height int64, voters uint16, splitVariant SubsidySplitVariant) int64
- type SubsidyParams
- type SubsidySplitVariant
Examples ¶
Constants ¶
const ( // ErrUnexpectedDifficulty indicates specified bits do not align with // the expected value either because it doesn't match the calculated // value based on difficulty rules or it is out of the valid range. ErrUnexpectedDifficulty = ErrorKind("ErrUnexpectedDifficulty") // ErrHighHash indicates the block does not hash to a value which is // lower than the required target difficultly. ErrHighHash = ErrorKind("ErrHighHash") // ErrInvalidTSpendExpiry indicates that an invalid expiry was // provided when calculating the treasury spend voting window. ErrInvalidTSpendExpiry = ErrorKind("ErrInvalidTSpendExpiry") // ErrNoTxInputs indicates a transaction does not have any inputs. A valid // transaction must have at least one input. ErrNoTxInputs = ErrorKind("ErrNoTxInputs") // ErrNoTxOutputs indicates a transaction does not have any outputs. A // valid transaction must have at least one output. ErrNoTxOutputs = ErrorKind("ErrNoTxOutputs") // ErrTxTooBig indicates a transaction exceeds the maximum allowed size when // serialized. ErrTxTooBig = ErrorKind("ErrTxTooBig") // ErrBadTxOutValue indicates an output value for a transaction is // invalid in some way such as being out of range. ErrBadTxOutValue = ErrorKind("ErrBadTxOutValue") // ErrDuplicateTxInputs indicates a transaction references the same // input more than once. ErrDuplicateTxInputs = ErrorKind("ErrDuplicateTxInputs") )
These constants are used to identify a specific RuleError.
Variables ¶
This section is empty.
Functions ¶
func BigToCompact ¶
BigToCompact converts a whole number N to a compact representation using an unsigned 32-bit number. The compact representation only provides 23 bits of precision, so values larger than (2^23 - 1) only encode the most significant digits of the number. See CompactToBig for details.
Example ¶
This example demonstrates how to convert a target difficulty into the compact "bits" in a block header which represent that target difficulty.
// Convert the target difficulty from block 1 in the main chain to compact // form. t := "000000000001ffff000000000000000000000000000000000000000000000000" targetDifficulty, success := new(big.Int).SetString(t, 16) if !success { fmt.Println("invalid target difficulty") return } bits := standalone.BigToCompact(targetDifficulty) fmt.Println(bits)
Output: 453115903
func CalcASERTDiff ¶ added in v2.2.0
func CalcASERTDiff(startDiffBits uint32, powLimit *big.Int, targetSecsPerBlock, timeDelta, heightDelta, halfLife int64) uint32
CalcASERTDiff calculates an absolutely scheduled exponentially weighted target difficulty for the given set of parameters using the algorithm defined in DCP0011.
The Absolutely Scheduled Exponentially weighted Rising Targets (ASERT) algorithm defines an ideal schedule for block issuance and calculates the difficulty based on how far the most recent block's timestamp is ahead or behind that schedule.
The target difficulty is set exponentially such that it is doubled or halved for every multiple of the half life the most recent block is ahead or behind the ideal schedule.
The starting difficulty bits parameter is the initial target difficulty all calculations use as a reference. This value is defined on a per-chain basis. It must be non-zero and less than or equal to the provided proof of work limit or the function will panic.
The time delta is the number of seconds that have elapsed between the most recent block and an initial reference timestamp.
The height delta is the number of blocks between the most recent block height and an initial reference height. It must be non-negative or the function will panic.
NOTE: This only performs the primary target difficulty calculation and does not include any additional special network rules such as enforcing a maximum allowed test network difficulty. It is up to the caller to impose any such additional restrictions.
This function is safe for concurrent access.
func CalcCombinedTxTreeMerkleRoot ¶
CalcCombinedTxTreeMerkleRoot calculates and returns the combined merkle root for the provided regular and stake transaction trees in accordance with DCP0005.
In particular, the final merkle root is the result of a merkle tree that itself has the individual merkle roots of the two transaction trees as leaves. The full (including witness data) hashes for the transactions are used as required for merkle roots.
A diagram depicting this follows:
root = blake256(regularTreeRoot || stakeTreeRoot) / \ regularTreeRoot stakeTreeRoot
It is also worth noting that it also happens to be exactly equivalent to the blake256 hash of the concatenation of the two individual merkle roots due to the way two leaf merkle trees are calculated:
blake256(regularTreeRoot || stakeTreeRoot)
func CalcMerkleRoot ¶
CalcMerkleRoot treats the provided slice of hashes as leaves of a merkle tree and returns the resulting merkle root.
A merkle tree is a tree in which every non-leaf node is the hash of its children nodes. A diagram depicting how this works for Decred transactions where h(x) is a blake256 hash follows:
root = h1234 = h(h12 + h34) / \ h12 = h(h1 + h2) h34 = h(h3 + h4) / \ / \ h1 = h(tx1) h2 = h(tx2) h3 = h(tx3) h4 = h(tx4)
The number of inputs is not always a power of two which results in a balanced tree structure as above. In that case, parent nodes with no children are also zero and parent nodes with only a single left node are calculated by concatenating the left node with itself before hashing.
Example ¶
This example demonstrates calculating a merkle root from a slice of leaf hashes.
// Create a slice of the leaf hashes. leaves := make([]chainhash.Hash, 3) for i := range leaves { // The hash would ordinarily be calculated from the TxHashFull function // on a transaction, however, it's left as a zero hash for the purposes // of this example. leaves[i] = chainhash.Hash{} } merkleRoot := standalone.CalcMerkleRoot(leaves) fmt.Printf("Result: %s", merkleRoot)
Output: Result: 5fdfcaba377aefc1bfc4af5ef8e0c2a61656e10e8105c4db7656ae5d58f8b77f
func CalcMerkleRootInPlace ¶
CalcMerkleRootInPlace is an in-place version of CalcMerkleRoot that reuses the backing array of the provided slice to perform the calculation thereby preventing extra allocations. It is the caller's responsibility to ensure it is safe to mutate the entries in the provided slice.
The function internally appends an additional entry in the case the number of provided leaves is odd, so the caller may wish to pre-allocate space for one additional element in the backing array in that case to ensure it doesn't need to be reallocated to expand it.
For example:
allocLen := len(leaves) + len(leaves)&1 leaves := make([]chainhash.Hash, len(leaves), allocLen) // populate the leaves
See CalcMerkleRoot for more details on how the merkle root is calculated.
func CalcTSpendExpiry ¶
CalcTSpendExpiry returns the only valid value relative to the next block height where the transaction will expire. Two blocks are added in the end because transaction expiry is inclusive (>=) relative to block height.
func CalcTSpendWindow ¶
CalcTSpendWindow calculates the start and end of a treasury voting window based on the parameters that are passed. An error will be returned if the provided expiry is not two more than a treasury vote interval (TVI) or before a single voting window is possible.
func CalcTxTreeMerkleRoot ¶
CalcTxTreeMerkleRoot calculates and returns the merkle root for the provided transactions. The full (including witness data) hashes for the transactions are used as required for merkle roots.
See CalcMerkleRoot for more details on how the merkle root is calculated.
func CalcWork ¶
CalcWork calculates a work value from difficulty bits. Decred increases the difficulty for generating a block by decreasing the value which the generated hash must be less than. This difficulty target is stored in each block header using a compact representation as described in the documentation for CompactToBig. The main chain is selected by choosing the chain that has the most proof of work (highest difficulty). Since a lower target difficulty value equates to higher actual difficulty, the work value which will be accumulated must be the inverse of the difficulty. Also, in order to avoid potential division by zero and really small floating point numbers, the result adds 1 to the denominator and multiplies the numerator by 2^256.
func CheckProofOfWork ¶
CheckProofOfWork ensures the provided hash is less than the provided compact target difficulty and that the target difficulty is in min/max range per the provided proof-of-work limit.
This is semantically equivalent to and slightly more efficient than calling CheckProofOfWorkRange followed by CheckProofOfWorkHash.
Example ¶
This example demonstrates checking the proof of work of a block hash against a target difficulty.
// This is the pow limit for mainnet and would ordinarily come from chaincfg // params, however, it is hard coded here for the purposes of the example. l := "00000000ffffffffffffffffffffffffffffffffffffffffffffffffffffffff" powLimit, success := new(big.Int).SetString(l, 16) if !success { fmt.Println("invalid pow limit") return } // Check the proof of work for block 1 in the main chain. h := "000000000000437482b6d47f82f374cde539440ddb108b0a76886f0d87d126b9" hash, err := chainhash.NewHashFromStr(h) if err != nil { fmt.Printf("failed to parse hash: %v\n", err) return } bits := uint32(453115903) if err := standalone.CheckProofOfWork(hash, bits, powLimit); err != nil { fmt.Printf("proof of work check failed: %v\n", err) return }
Output:
func CheckProofOfWorkHash ¶ added in v2.2.0
CheckProofOfWorkHash ensures the provided hash is less than the provided compact target difficulty.
func CheckProofOfWorkRange ¶
CheckProofOfWorkRange ensures the provided compact target difficulty is in min/max range per the provided proof-of-work limit.
func CheckTransactionSanity ¶ added in v2.2.0
CheckTransactionSanity performs some preliminary checks on a transaction to ensure it is sane. These checks are context free.
func CompactToBig ¶
CompactToBig converts a compact representation of a whole number N to an unsigned 32-bit number. The representation is similar to IEEE754 floating point numbers.
Like IEEE754 floating point, there are three basic components: the sign, the exponent, and the mantissa. They are broken out as follows:
- the most significant 8 bits represent the unsigned base 256 exponent
- zero-based bit 23 (the 24th bit) represents the sign bit
- the least significant 23 bits represent the mantissa
Diagram:
------------------------------------------------- | Exponent | Sign | Mantissa | |-----------------------------------------------| | 8 bits [31-24] | 1 bit [23] | 23 bits [22-00] | -------------------------------------------------
The formula to calculate N is:
N = (-1^sign) * mantissa * 256^(exponent-3)
This compact form is only used in Decred to encode unsigned 256-bit numbers which represent difficulty targets, thus there really is not a need for a sign bit, but it is implemented here to stay consistent with legacy code.
Example ¶
This example demonstrates how to convert the compact "bits" in a block header which represent the target difficulty to a big integer and display it using the typical hex notation.
// Convert the bits from block 1 in the main chain. bits := uint32(453115903) targetDifficulty := standalone.CompactToBig(bits) // Display it in hex. fmt.Printf("%064x\n", targetDifficulty.Bytes())
Output: 000000000001ffff000000000000000000000000000000000000000000000000
func GenerateInclusionProof ¶
GenerateInclusionProof treats the provided slice of hashes as leaves of a merkle tree and generates and returns a merkle tree inclusion proof for the given leaf index. The proof can be used to efficiently prove the leaf associated with given leaf index is a member of the tree.
A merkle tree inclusion proof consists of the ceil(log2(x)) intermediate sibling hashes along the path from the target leaf to prove through the root node. The sibling hashes, along with the original leaf hash (and its original leaf index), can be used to recalculate the merkle root which, in turn, can be verified against a known good merkle root in order to prove the leaf is actually a member of the tree at that position.
For example, consider the following merkle tree:
root = h1234 = h(h12 + h34) / \ h12 = h(h1 + h2) h34 = h(h3 + h4) / \ / \ h1 h2 h3 h4
Further, consider the goal is to prove inclusion of h3 at the 0-based leaf index of 2. The proof will consist of the sibling hashes h4 and h12. On the other hand, if the goal were to prove inclusion of h2 at the 0-based leaf index of 1, the proof would consist of the sibling hashes h1 and h34.
Specifying a leaf index that is out of range will return nil.
func HashToBig ¶
HashToBig converts a chainhash.Hash into a big.Int that can be used to perform math comparisons.
func InsideTSpendWindow ¶
InsideTSpendWindow returns true if the provided block height is inside the treasury vote window of the provided expiry. This function should only be called with an expiry that is on a TVI. Proper care must be taken to call this function with the correct block height. It is incumbent on the caller to determine if the block height is for the previous, current, or next block.
Note: The end is INCLUSIVE in order to determine if a treasury spend is allowed in a block despite the fact that the voting window is EXCLUSIVE.
func IsCoinBaseTx ¶
IsCoinBaseTx determines whether or not a transaction is a coinbase. A coinbase is a special transaction created by miners that has no inputs. This is represented in the block chain by a transaction with a single input that has a previous output transaction index set to the maximum value along with a zero hash.
func IsTreasuryBase ¶
IsTreasuryBase does a minimal check to see if a transaction is a treasury base.
func IsTreasuryVoteInterval ¶
IsTreasuryVoteInterval returns true if the passed height is on a treasury vote interval (TVI) and is not 0.
func VerifyInclusionProof ¶
func VerifyInclusionProof(root, leaf *chainhash.Hash, leafIndex uint32, proof []chainhash.Hash) bool
VerifyInclusionProof returns whether or not the given leaf hash, original leaf index, and inclusion proof result in recalculating a merkle root that matches the provided merkle root. See GenerateInclusionProof for details about the proof.
For example, consider a provided root hash denoted by "h1234o", a leaf hash to verify inclusion for denoted by "h2" with a leaf index of 2, and an inclusion proof consisting of hashes denoted by "h1o", and "h34o". The "o" here stands for original, as in the original hashes calculated while generating the proof.
These values would form the following merkle tree:
root = h1234 = h(h12 + h34o) / \ h12 = h(h1o + h2) h34o / \ h1o h2
The verification will succeed if the root of the new partial merkle tree, "h1234", matches the provided root hash "h1234o".
Types ¶
type ErrorKind ¶
type ErrorKind string
ErrorKind identifies a kind of error. It has full support for errors.Is and errors.As, so the caller can directly check against an error kind when determining the reason for an error.
type RuleError ¶
RuleError identifies a rule violation. It has full support for errors.Is and errors.As, so the caller can ascertain the specific reason for the error by checking the underlying error.
type SubsidyCache ¶
type SubsidyCache struct {
// contains filtered or unexported fields
}
SubsidyCache provides efficient access to consensus-critical subsidy calculations for blocks and votes, including the max potential subsidy for given block heights, the proportional proof-of-work subsidy, the proportional proof of stake per-vote subsidy, and the proportional treasury subsidy.
It makes using of caching to avoid repeated calculations.
func NewSubsidyCache ¶
func NewSubsidyCache(params SubsidyParams) *SubsidyCache
NewSubsidyCache creates and initializes a new subsidy cache instance. See the SubsidyCache documentation for more details.
func (*SubsidyCache) CalcBlockSubsidy ¶
func (c *SubsidyCache) CalcBlockSubsidy(height int64) int64
CalcBlockSubsidy returns the max potential subsidy for a block at the provided height. This value is reduced over time based on the height and then split proportionally between PoW, PoS, and the Treasury.
Subsidy calculation for exponential reductions:
subsidy := BaseSubsidyValue() for i := 0; i < (height / SubsidyReductionIntervalBlocks()); i++ { subsidy *= SubsidyReductionMultiplier() subsidy /= SubsidyReductionDivisor() }
This function is safe for concurrent access.
func (*SubsidyCache) CalcStakeVoteSubsidy
deprecated
func (c *SubsidyCache) CalcStakeVoteSubsidy(height int64) int64
CalcStakeVoteSubsidy returns the subsidy for a single stake vote for a block using the subsidy split that was in effect prior to the modifed value defined in DCP0010.
It is calculated as a proportion of the total subsidy and max potential number of votes per block.
Unlike the Proof-of-Work and Treasury subsidies, the subsidy that votes receive is not reduced when a block contains less than the maximum number of votes. Consequently, this does not accept the number of votes. However, it is important to note that blocks that do not receive the minimum required number of votes for a block to be valid by consensus won't actually produce any vote subsidy either since they are invalid.
This function is safe for concurrent access.
Deprecated: Use CalcStakeVoteSubsidyV3 instead.
func (*SubsidyCache) CalcStakeVoteSubsidyV2
deprecated
added in
v2.1.0
func (c *SubsidyCache) CalcStakeVoteSubsidyV2(height int64, useDCP0010 bool) int64
CalcStakeVoteSubsidyV2 returns the subsidy for a single stake vote for a block using either the original subsidy split that was in effect at Decred launch or the modified subsidy split defined in DCP0010 according to the provided flag.
It is calculated as a proportion of the total subsidy and max potential number of votes per block.
Unlike the Proof-of-Work and Treasury subsidies, the subsidy that votes receive is not reduced when a block contains less than the maximum number of votes. Consequently, this does not accept the number of votes. However, it is important to note that blocks that do not receive the minimum required number of votes for a block to be valid by consensus won't actually produce any vote subsidy either since they are invalid.
This function is safe for concurrent access.
Deprecated: Use CalcStakeVoteSubsidyV3 instead.
func (*SubsidyCache) CalcStakeVoteSubsidyV3 ¶ added in v2.2.0
func (c *SubsidyCache) CalcStakeVoteSubsidyV3(height int64, splitVariant SubsidySplitVariant) int64
CalcStakeVoteSubsidyV3 returns the subsidy for a single stake vote for a block using the subsidy split determined by the provided subsidy split variant parameter.
It is calculated as a proportion of the total subsidy and max potential number of votes per block.
Unlike the Proof-of-Work and Treasury subsidies, the subsidy that votes receive is not reduced when a block contains less than the maximum number of votes. Consequently, this does not accept the number of votes. However, it is important to note that blocks that do not receive the minimum required number of votes for a block to be valid by consensus won't actually produce any vote subsidy either since they are invalid.
Passing an invalid subsidy split variant will be treated the same as the SSVOriginal variant.
This function is safe for concurrent access.
func (*SubsidyCache) CalcTreasurySubsidy ¶
func (c *SubsidyCache) CalcTreasurySubsidy(height int64, voters uint16, isTreasuryEnabled bool) int64
CalcTreasurySubsidy returns the subsidy required to go to the treasury for a block. It is calculated as a proportion of the total subsidy and further reduced proportionally depending on the number of votes once the height at which voting begins has been reached.
Note that passing a number of voters fewer than the minimum required for a block to be valid by consensus along with a height greater than or equal to the height at which voting begins will return zero.
When the treasury agenda is active the subsidy rule changes from paying out a proportion based on the number of votes to always pay the full subsidy.
This function is safe for concurrent access.
func (*SubsidyCache) CalcWorkSubsidy
deprecated
func (c *SubsidyCache) CalcWorkSubsidy(height int64, voters uint16) int64
CalcWorkSubsidy returns the proof of work subsidy for a block for a given number of votes using the subsidy split that was in effect prior to the modifed value defined in DCP0010.
It is calculated as a proportion of the total subsidy and further reduced proportionally depending on the number of votes once the height at which voting begins has been reached.
Note that passing a number of voters fewer than the minimum required for a block to be valid by consensus along with a height greater than or equal to the height at which voting begins will return zero.
This function is safe for concurrent access.
Deprecated: Use CalcWorkSubsidyV3 instead.
func (*SubsidyCache) CalcWorkSubsidyV2
deprecated
added in
v2.1.0
func (c *SubsidyCache) CalcWorkSubsidyV2(height int64, voters uint16, useDCP0010 bool) int64
CalcWorkSubsidyV2 returns the proof of work subsidy for a block for a given number of votes using either the original subsidy split that was in effect at Decred launch or the modified subsidy split defined in DCP0010 according to the provided flag.
It is calculated as a proportion of the total subsidy and further reduced proportionally depending on the number of votes once the height at which voting begins has been reached.
Note that passing a number of voters fewer than the minimum required for a block to be valid by consensus along with a height greater than or equal to the height at which voting begins will return zero.
This function is safe for concurrent access.
Deprecated: Use CalcWorkSubsidyV3 instead.
func (*SubsidyCache) CalcWorkSubsidyV3 ¶ added in v2.2.0
func (c *SubsidyCache) CalcWorkSubsidyV3(height int64, voters uint16, splitVariant SubsidySplitVariant) int64
CalcWorkSubsidyV3 returns the proof of work subsidy for a block for a given number of votes using the subsidy split determined by the provided subsidy split variant parameter.
It is calculated as a proportion of the total subsidy and further reduced proportionally depending on the number of votes once the height at which voting begins has been reached.
Note that passing a number of voters fewer than the minimum required for a block to be valid by consensus along with a height greater than or equal to the height at which voting begins will return zero.
Passing an invalid subsidy split variant will be treated the same as the SSVOriginal variant.
This function is safe for concurrent access.
type SubsidyParams ¶
type SubsidyParams interface { // BlockOneSubsidy returns the total subsidy of block height 1 for the // network. This is separate since it encompasses the initial coin // distribution. BlockOneSubsidy() int64 // BaseSubsidyValue returns the starting base max potential subsidy amount // for mined blocks. This value is reduced over time and then split // proportionally between PoW, PoS, and the Treasury. The reduction is // controlled by the SubsidyReductionInterval, SubsidyReductionMultiplier, // and SubsidyReductionDivisor parameters. // // NOTE: BaseSubsidy must be a max of 140,739,635,871,744 atoms or incorrect // results will occur due to int64 overflow. This value comes from // MaxInt64/MaxUint16 = (2^63 - 1)/(2^16 - 1) = 2^47 + 2^31 + 2^15. BaseSubsidyValue() int64 // SubsidyReductionMultiplier returns the multiplier to use when performing // the exponential subsidy reduction described by the CalcBlockSubsidy // documentation. SubsidyReductionMultiplier() int64 // SubsidyReductionDivisor returns the divisor to use when performing the // exponential subsidy reduction described by the CalcBlockSubsidy // documentation. SubsidyReductionDivisor() int64 // SubsidyReductionIntervalBlocks returns the reduction interval in number // of blocks. SubsidyReductionIntervalBlocks() int64 // WorkSubsidyProportion returns the comparative proportion of the subsidy // generated for creating a block (PoW) that was in effect prior to the // modified value defined in DCP0010. // // The proportional split between PoW, PoS, and the Treasury is calculated // by treating each of the proportional parameters as a ratio to the sum of // the three proportional parameters: WorkSubsidyProportion, // StakeSubsidyProportion, and TreasurySubsidyProportion. // // For example: // WorkSubsidyProportion: 6 => 6 / (6+3+1) => 6/10 => 60% // StakeSubsidyProportion: 3 => 3 / (6+3+1) => 3/10 => 30% // TreasurySubsidyProportion: 1 => 1 / (6+3+1) => 1/10 => 10% WorkSubsidyProportion() uint16 // StakeSubsidyProportion returns the comparative proportion of the subsidy // generated for casting stake votes (collectively, per block) that was in // effect prior to the modified value defined in DCP0010. See the // documentation for WorkSubsidyProportion for more details on how the // parameter is used. StakeSubsidyProportion() uint16 // TreasurySubsidyProportion returns the comparative proportion of the // subsidy allocated to the project treasury. See the documentation for // WorkSubsidyProportion for more details on how the parameter is used. TreasurySubsidyProportion() uint16 // StakeValidationBeginHeight returns the height at which votes become // required to extend a block. This height is the first that will be voted // on, but will not include any votes itself. StakeValidationBeginHeight() int64 // VotesPerBlock returns the maximum number of votes a block must contain to // receive full subsidy once voting begins at StakeValidationBeginHeight. VotesPerBlock() uint16 }
SubsidyParams defines an interface that is used to provide the parameters required when calculating block and vote subsidies. These values are typically well-defined and unique per network.
type SubsidySplitVariant ¶ added in v2.2.0
type SubsidySplitVariant uint8
SubsidySplitVariant defines the available variants for subsidy split calculations.
const ( // SSVOriginal specifies the original subsidy split that was in effect at // initial launch. In particular, 60% PoW, 40% PoS, and 10% Treasury. SSVOriginal SubsidySplitVariant = iota // SSVDCP0010 specifies the modified subsidy split specified by DCP0010. // In particular, 10% PoW, 80% PoS, and 10% Treasury. SSVDCP0010 // SSVDCP0012 specifies the modified subsidy split specified by DCP0012. // In particular, 1% PoW, 89% PoS, and 10% Treasury. SSVDCP0012 )