Documentation ¶
Overview ¶
Package api implements the staking backend API.
Package api implements the staking backend API.
Index ¶
- Constants
- Variables
- type Account
- type AddEscrowEvent
- type AddEscrowResult
- type Address
- type Allow
- type AllowanceChangeEvent
- type AllowanceQuery
- type AmendCommissionSchedule
- type Burn
- type BurnEvent
- type CommissionRateBoundStep
- type CommissionRateStep
- type CommissionSchedule
- type CommissionScheduleRules
- type ConsensusParameterChanges
- type ConsensusParameters
- type DebondingDelegation
- type DebondingDelegationInfo
- type DebondingStartEscrowEvent
- type Delegation
- type DelegationInfo
- type Escrow
- type EscrowAccount
- type EscrowEvent
- type Event
- type GeneralAccount
- type Genesis
- type OwnerQuery
- type ReclaimEscrow
- type ReclaimEscrowEvent
- type ReclaimEscrowResult
- type RewardStep
- type SharePool
- type Slash
- type SlashReason
- type StakeAccumulator
- type StakeClaim
- type StakeThreshold
- type TakeEscrowEvent
- type ThresholdKind
- type ThresholdQuery
- type Transfer
- type TransferEvent
- type TransferResult
- type Withdraw
- type WithdrawResult
Constants ¶
const ( // ModuleName is a unique module name for the staking module. ModuleName = "staking" // LogEventGeneralAdjustment is a log event value that signals adjustment // of an account's general balance due to a roothash message. LogEventGeneralAdjustment = "staking/general_adjustment" )
const ( KindEntity ThresholdKind = 0 KindNodeValidator ThresholdKind = 1 KindNodeCompute ThresholdKind = 2 KindNodeObserver ThresholdKind = 3 KindNodeKeyManager ThresholdKind = 4 KindRuntimeCompute ThresholdKind = 5 KindRuntimeKeyManager ThresholdKind = 6 KindEntityName = "entity" KindNodeValidatorName = "node-validator" KindNodeComputeName = "node-compute" KindNodeObserverName = "node-observer" KindNodeKeyManagerName = "node-keymanager" KindRuntimeComputeName = "runtime-compute" KindRuntimeKeyManagerName = "runtime-keymanager" )
nolint: revive
const ( // GasOpTransfer is the gas operation identifier for transfer. GasOpTransfer transaction.Op = "transfer" // GasOpBurn is the gas operation identifier for burn. GasOpBurn transaction.Op = "burn" // GasOpAddEscrow is the gas operation identifier for add escrow. GasOpAddEscrow transaction.Op = "add_escrow" // GasOpReclaimEscrow is the gas operation identifier for reclaim escrow. GasOpReclaimEscrow transaction.Op = "reclaim_escrow" // GasOpAmendCommissionSchedule is the gas operation identifier for amend commission schedule. GasOpAmendCommissionSchedule transaction.Op = "amend_commission_schedule" // GasOpAllow is the gas operation identifier for allow. GasOpAllow transaction.Op = "allow" // GasOpWithdraw is the gas operation identifier for withdraw. GasOpWithdraw transaction.Op = "withdraw" )
const ( // SlashConsensusEquivocation is slashing due to equivocation. SlashConsensusEquivocation SlashReason = 0x00 // SlashBeaconInvalidCommit is slashing due to invalid commit behavior. SlashBeaconInvalidCommit SlashReason = 0x01 // SlashBeaconInvalidReveal is slashing due to invalid reveal behavior. SlashBeaconInvalidReveal SlashReason = 0x02 // SlashBeaconNonparticipation is slashing due to nonparticipation. SlashBeaconNonparticipation SlashReason = 0x03 // SlashConsensusLightClientAttack is slashing due to light client attacks. SlashConsensusLightClientAttack SlashReason = 0x04 // SlashRuntimeIncorrectResults is slashing due to submission of incorrect // results in runtime executor commitments. SlashRuntimeIncorrectResults SlashReason = 0x80 // SlashRuntimeEquivocation is slashing due to signing two different // executor commits or proposed batches for the same round. SlashRuntimeEquivocation SlashReason = 0x81 // SlashRuntimeLiveness is slashing due to not doing the required work. SlashRuntimeLiveness SlashReason = 0x82 // SlashConsensusEquivocationName is the string representation of SlashConsensusEquivocation. SlashConsensusEquivocationName = "consensus-equivocation" // SlashConsensusLightClientAttackName is the string representation of SlashConsensusLightClientAttack. SlashConsensusLightClientAttackName = "consensus-light-client-attack" // SlashRuntimeIncorrectResultsName is the string representation of SlashRuntimeIncorrectResultsName. SlashRuntimeIncorrectResultsName = "runtime-incorrect-results" // SlashRuntimeEquivocationName is the string representation of SlashRuntimeEquivocation. SlashRuntimeEquivocationName = "runtime-equivocation" // SlashRuntimeLivenessName is the string representation of SlashRuntimeLiveness. SlashRuntimeLivenessName = "runtime-liveness" )
Variables ¶
var RewardAmountDenominator *quantity.Quantity
RewardAmountDenominator is the denominator for the reward rate.
Functions ¶
This section is empty.
Types ¶
type Account ¶
type Account struct { General GeneralAccount `json:"general,omitempty"` Escrow EscrowAccount `json:"escrow,omitempty"` }
Account is an entry in the staking ledger.
The same ledger entry can hold both general and escrow accounts. Escrow accounts are used to hold funds delegated for staking.
type AddEscrowEvent ¶
type AddEscrowEvent struct { Owner Address `json:"owner"` Escrow Address `json:"escrow"` Amount quantity.Quantity `json:"amount"` }
AddEscrowEvent is the event emitted when stake is transferred into an escrow account.
type AddEscrowResult ¶
type AddEscrowResult struct { Owner Address `json:"owner"` Escrow Address `json:"escrow"` Amount quantity.Quantity `json:"amount"` }
AddEscrowResult is the result of add escrow.
type Allow ¶
type Allow struct { Beneficiary Address `json:"beneficiary"` Negative bool `json:"negative,omitempty"` AmountChange quantity.Quantity `json:"amount_change"` }
Allow is a beneficiary allowance configuration.
type AllowanceChangeEvent ¶
type AllowanceChangeEvent struct { Owner Address `json:"owner"` Beneficiary Address `json:"beneficiary"` Allowance quantity.Quantity `json:"allowance"` Negative bool `json:"negative,omitempty"` AmountChange quantity.Quantity `json:"amount_change"` }
AllowanceChangeEvent is the event emitted when allowance is changed for a beneficiary.
type AllowanceQuery ¶
type AllowanceQuery struct { Height int64 `json:"height"` Owner Address `json:"owner"` Beneficiary Address `json:"beneficiary"` }
AllowanceQuery is an allowance query.
type AmendCommissionSchedule ¶
type AmendCommissionSchedule struct {
Amendment CommissionSchedule `json:"amendment"`
}
AmendCommissionSchedule is an amendment to a commission schedule.
type CommissionRateBoundStep ¶
type CommissionRateBoundStep struct { // Epoch when the commission rate bound will go in effect. Start beacon.EpochTime `json:"start,omitempty"` // Minimum commission rate numerator. The minimum rate is this value divided by CommissionRateDenominator. RateMin quantity.Quantity `json:"rate_min,omitempty"` // Maximum commission rate numerator. The maximum rate is this value divided by CommissionRateDenominator. RateMax quantity.Quantity `json:"rate_max,omitempty"` }
CommissionRateBoundStep sets a commission rate bound (i.e. the minimum and maximum commission rate) and its starting time.
type CommissionRateStep ¶
type CommissionRateStep struct { // Epoch when the commission rate will go in effect. Start beacon.EpochTime `json:"start,omitempty"` // Commission rate numerator. The rate is this value divided by CommissionRateDenominator. Rate quantity.Quantity `json:"rate,omitempty"` }
CommissionRateStep sets a commission rate and its starting time.
type CommissionSchedule ¶
type CommissionSchedule struct { // List of commission rates and their starting times. Rates []CommissionRateStep `json:"rates,omitempty"` // List of commission rate bounds and their starting times. Bounds []CommissionRateBoundStep `json:"bounds,omitempty"` }
CommissionSchedule defines a list of commission rates and commission rate bounds and their starting times.
type CommissionScheduleRules ¶
type CommissionScheduleRules struct { // Epoch period when commission rates are allowed to be changed (e.g. // setting it to 3 means they can be changed every third epoch). RateChangeInterval beacon.EpochTime `json:"rate_change_interval,omitempty"` // Number of epochs a commission rate bound change must specified in advance. RateBoundLead beacon.EpochTime `json:"rate_bound_lead,omitempty"` // Maximum number of commission rate steps a commission schedule can specify. MaxRateSteps uint16 `json:"max_rate_steps,omitempty"` // Maximum number of commission rate bound steps a commission schedule can specify. MaxBoundSteps uint16 `json:"max_bound_steps,omitempty"` // MinCommissionRate is the minimum commission rate an account can configure. // The rate is obtained by dividing this value with the `CommissionRateDenominator`. MinCommissionRate quantity.Quantity `json:"min_commission_rate"` }
CommissionScheduleRules controls how commission schedule rates and rate bounds are allowed to be changed.
type ConsensusParameterChanges ¶
type ConsensusParameterChanges struct { // DebondingInterval is the new debonding interval. DebondingInterval *beacon.EpochTime `json:"debonding_interval,omitempty"` // RewardSchedule is the new reward schedule. RewardSchedule *[]RewardStep `json:"reward_schedule,omitempty"` // GasCosts are the new gas costs. GasCosts transaction.Costs `json:"gas_costs,omitempty"` // MinDelegationAmount is the new minimum delegation amount. MinDelegationAmount *quantity.Quantity `json:"min_delegation"` // MinTransferAmount is the new minimum transfer amount. MinTransferAmount *quantity.Quantity `json:"min_transfer"` // MinTransactBalance is the new minimum transact balance. MinTransactBalance *quantity.Quantity `json:"min_transact_balance"` // MinCommissionRate is the new minimum commission rate. MinCommissionRate *quantity.Quantity `json:"min_commission_rate"` // DisableTransfers is the new disable transfers flag. DisableTransfers *bool `json:"disable_transfers,omitempty"` // DisableDelegation is the new disable delegation flag. DisableDelegation *bool `json:"disable_delegation,omitempty"` // AllowEscrowMessages is the new allow escrow messages flag. AllowEscrowMessages *bool `json:"allow_escrow_messages,omitempty"` // MaxAllowances is the new maximum number of allowances. MaxAllowances *uint32 `json:"max_allowances,omitempty"` // FeeSplitWeightPropose is the new propose fee split weight. FeeSplitWeightPropose *quantity.Quantity `json:"fee_split_weight_propose"` // FeeSplitWeightVote is the new vote fee split weight. FeeSplitWeightVote *quantity.Quantity `json:"fee_split_weight_vote"` // FeeSplitWeightNextPropose is the new next propose fee split weight. FeeSplitWeightNextPropose *quantity.Quantity `json:"fee_split_weight_next_propose"` // RewardFactorEpochSigned is the new epoch signed reward factor. RewardFactorEpochSigned *quantity.Quantity `json:"reward_factor_epoch_signed"` // RewardFactorBlockProposed is the new block proposed reward factor. RewardFactorBlockProposed *quantity.Quantity `json:"reward_factor_block_proposed"` }
ConsensusParameterChanges are allowed staking consensus parameter changes.
type ConsensusParameters ¶
type ConsensusParameters struct { Thresholds map[ThresholdKind]quantity.Quantity `json:"thresholds,omitempty"` DebondingInterval beacon.EpochTime `json:"debonding_interval,omitempty"` RewardSchedule []RewardStep `json:"reward_schedule,omitempty"` SigningRewardThresholdNumerator uint64 `json:"signing_reward_threshold_numerator,omitempty"` SigningRewardThresholdDenominator uint64 `json:"signing_reward_threshold_denominator,omitempty"` CommissionScheduleRules CommissionScheduleRules `json:"commission_schedule_rules,omitempty"` Slashing map[SlashReason]Slash `json:"slashing,omitempty"` GasCosts transaction.Costs `json:"gas_costs,omitempty"` MinDelegationAmount quantity.Quantity `json:"min_delegation"` MinTransferAmount quantity.Quantity `json:"min_transfer"` MinTransactBalance quantity.Quantity `json:"min_transact_balance"` DisableTransfers bool `json:"disable_transfers,omitempty"` DisableDelegation bool `json:"disable_delegation,omitempty"` UndisableTransfersFrom map[Address]bool `json:"undisable_transfers_from,omitempty"` // AllowEscrowMessages can be used to allow runtimes to perform AddEscrow // and ReclaimEscrow via runtime messages. AllowEscrowMessages bool `json:"allow_escrow_messages,omitempty"` // MaxAllowances is the maximum number of allowances an account can have. Zero means disabled. MaxAllowances uint32 `json:"max_allowances,omitempty"` // FeeSplitWeightPropose is the proportion of block fee portions that go to the proposer. FeeSplitWeightPropose quantity.Quantity `json:"fee_split_weight_propose"` // FeeSplitWeightVote is the proportion of block fee portions that go to the validator that votes. FeeSplitWeightVote quantity.Quantity `json:"fee_split_weight_vote"` // FeeSplitWeightNextPropose is the proportion of block fee portions that go to the next block's proposer. FeeSplitWeightNextPropose quantity.Quantity `json:"fee_split_weight_next_propose"` // RewardFactorEpochSigned is the factor for a reward distributed per epoch to // entities that have signed at least a threshold fraction of the blocks. RewardFactorEpochSigned quantity.Quantity `json:"reward_factor_epoch_signed"` // RewardFactorBlockProposed is the factor for a reward distributed per block // to the entity that proposed the block. RewardFactorBlockProposed quantity.Quantity `json:"reward_factor_block_proposed"` }
ConsensusParameters are the staking consensus parameters.
type DebondingDelegation ¶
DebondingDelegation is a debonding delegation descriptor.
type DebondingDelegationInfo ¶
type DebondingDelegationInfo struct { DebondingDelegation Pool SharePool `json:"pool"` }
DebondingDelegationInfo is a debonding delegation descriptor with additional information.
Additional information contains the share pool the debonding delegation belongs to.
type DebondingStartEscrowEvent ¶
type DebondingStartEscrowEvent struct { Owner Address `json:"owner"` Escrow Address `json:"escrow"` Amount quantity.Quantity `json:"amount"` DebondEndTime beacon.EpochTime `json:"debond_end_time"` }
DebondingStartEscrowEvent is the event emitted when the debonding process has started and the given number of active shares have been moved into the debonding pool and started debonding.
Note that the given amount is valid at the time of debonding start and may not correspond to the final debonded amount in case any escrowed stake is subject to slashing.
type DelegationInfo ¶
type DelegationInfo struct { Delegation Pool SharePool `json:"pool"` }
DelegationInfo is a delegation descriptor with additional information.
Additional information contains the share pool the delegation belongs to.
type EscrowAccount ¶
type EscrowAccount struct { Active SharePool `json:"active,omitempty"` Debonding SharePool `json:"debonding,omitempty"` CommissionSchedule CommissionSchedule `json:"commission_schedule,omitempty"` StakeAccumulator StakeAccumulator `json:"stake_accumulator,omitempty"` }
EscrowAccount is an escrow account the balance of which is subject to special delegation provisions and a debonding period.
type EscrowEvent ¶
type EscrowEvent struct { Add *AddEscrowEvent `json:"add,omitempty"` Take *TakeEscrowEvent `json:"take,omitempty"` DebondingStart *DebondingStartEscrowEvent `json:"debonding_start,omitempty"` Reclaim *ReclaimEscrowEvent `json:"reclaim,omitempty"` }
EscrowEvent is an escrow event.
type Event ¶
type Event struct { Height int64 `json:"height,omitempty"` TxHash hash.Hash `json:"tx_hash,omitempty"` Transfer *TransferEvent `json:"transfer,omitempty"` Burn *BurnEvent `json:"burn,omitempty"` Escrow *EscrowEvent `json:"escrow,omitempty"` AllowanceChange *AllowanceChangeEvent `json:"allowance_change,omitempty"` }
Event signifies a staking event, returned via GetEvents.
type GeneralAccount ¶
type GeneralAccount struct { Balance quantity.Quantity `json:"balance,omitempty"` Nonce uint64 `json:"nonce,omitempty"` Allowances map[Address]quantity.Quantity `json:"allowances,omitempty"` }
GeneralAccount is a general-purpose account.
type Genesis ¶
type Genesis struct { // Parameters are the staking consensus parameters. Parameters ConsensusParameters `json:"params"` // TokenSymbol is the token's ticker symbol. // Only upper case A-Z characters are allowed. TokenSymbol string `json:"token_symbol"` // TokenValueExponent is the token's value base-10 exponent, i.e. // 1 token = 10**TokenValueExponent base units. TokenValueExponent uint8 `json:"token_value_exponent"` // TokenSupply is the network's total amount of stake in base units. TotalSupply quantity.Quantity `json:"total_supply"` // CommonPool is the network's common stake pool. CommonPool quantity.Quantity `json:"common_pool"` // LastBlockFees are the collected fees for previous block. LastBlockFees quantity.Quantity `json:"last_block_fees"` // GovernanceDeposits are network's governance deposits. GovernanceDeposits quantity.Quantity `json:"governance_deposits"` // Ledger is a map of staking accounts. Ledger map[Address]*Account `json:"ledger,omitempty"` // Delegations is a nested map of staking delegations of the form: // DELEGATEE-ACCOUNT-ADDRESS: DELEGATOR-ACCOUNT-ADDRESS: DELEGATION. Delegations map[Address]map[Address]*Delegation `json:"delegations,omitempty"` // DebondingDelegations is a nested map of staking delegations of the form: // DEBONDING-DELEGATEE-ACCOUNT-ADDRESS: DEBONDING-DELEGATOR-ACCOUNT-ADDRESS: list of DEBONDING-DELEGATIONs. DebondingDelegations map[Address]map[Address][]*DebondingDelegation `json:"debonding_delegations,omitempty"` }
Genesis is the initial staking state for use in the genesis block.
type OwnerQuery ¶
OwnerQuery is an owner query.
type ReclaimEscrow ¶
type ReclaimEscrow struct { Account Address `json:"account"` }
ReclaimEscrow is a reclamation of stake from an escrow.
type ReclaimEscrowEvent ¶
type ReclaimEscrowEvent struct { Owner Address `json:"owner"` Escrow Address `json:"escrow"` Amount quantity.Quantity `json:"amount"` }
ReclaimEscrowEvent is the event emitted when stake is reclaimed from an escrow account back into owner's general account.
type ReclaimEscrowResult ¶
type ReclaimEscrowResult struct { Owner Address `json:"owner"` Escrow Address `json:"escrow"` Amount quantity.Quantity `json:"amount"` DebondEndTime beacon.EpochTime `json:"debond_end_time"` }
ReclaimEscrowResult is the result of reclaim escrow.
type RewardStep ¶
type RewardStep struct { Until beacon.EpochTime `json:"until"` Scale quantity.Quantity `json:"scale"` }
RewardStep is one of the time periods in the reward schedule.
type SharePool ¶
type SharePool struct {}
SharePool is a combined balance of several entries, the relative sizes of which are tracked through shares.
type Slash ¶
type Slash struct { Amount quantity.Quantity `json:"amount"` FreezeInterval beacon.EpochTime `json:"freeze_interval"` }
Slash is the per-reason slashing configuration.
type SlashReason ¶
type SlashReason uint8
SlashReason is the reason why a node was slashed.
func (SlashReason) MarshalText ¶
func (s SlashReason) MarshalText() ([]byte, error)
MarshalText encodes a SlashReason into text form.
func (SlashReason) String ¶
func (s SlashReason) String() string
String returns a string representation of a SlashReason.
func (*SlashReason) UnmarshalText ¶
func (s *SlashReason) UnmarshalText(text []byte) error
UnmarshalText decodes a text slice into a SlashReason.
type StakeAccumulator ¶
type StakeAccumulator struct { // Claims are the stake claims that must be satisfied at any given point. Adding a new claim is // only possible if all of the existing claims plus the new claim is satisfied. Claims map[StakeClaim][]StakeThreshold `json:"claims,omitempty"` }
StakeAccumulator is a per-escrow-account stake accumulator.
type StakeThreshold ¶
type StakeThreshold struct { // Global is a reference to a global stake threshold. Global *ThresholdKind `json:"global,omitempty"` // Constant is the value for a specific threshold. Constant *quantity.Quantity `json:"const,omitempty"` }
StakeThreshold is a stake threshold as used in the stake accumulator.
func (StakeThreshold) String ¶
func (st StakeThreshold) String() string
String returns a string representation of a stake threshold.
type TakeEscrowEvent ¶
type TakeEscrowEvent struct { Owner Address `json:"owner"` // The sum of amounts slashed from active and debonding escrow balances. Amount quantity.Quantity `json:"amount"` // The amount slashed from debonding escrow balances. DebondingAmount quantity.Quantity `json:"debonding_amount"` }
TakeEscrowEvent is the event emitted when stake is taken from an escrow account (i.e. stake is slashed).
type ThresholdKind ¶
type ThresholdKind int
ThresholdKind is the kind of staking threshold.
func (ThresholdKind) MarshalText ¶
func (k ThresholdKind) MarshalText() ([]byte, error)
MarshalText encodes a ThresholdKind into text form.
func (ThresholdKind) String ¶
func (k ThresholdKind) String() string
String returns the string representation of a ThresholdKind.
func (*ThresholdKind) UnmarshalText ¶
func (k *ThresholdKind) UnmarshalText(text []byte) error
UnmarshalText decodes a text slice into a ThresholdKind.
type ThresholdQuery ¶
type ThresholdQuery struct { Height int64 `json:"height"` Kind ThresholdKind `json:"kind"` }
ThresholdQuery is a threshold query.
type TransferEvent ¶
type TransferEvent struct { From Address `json:"from"` To Address `json:"to"` Amount quantity.Quantity `json:"amount"` }
TransferEvent is the event emitted when stake is transferred, either by a call to Transfer or Withdraw.
type TransferResult ¶
type TransferResult struct { From Address `json:"from"` To Address `json:"to"` Amount quantity.Quantity `json:"amount"` }
TransferResult is the result of staking transfer.