api

package
v0.2201.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2022 License: Apache-2.0 Imports: 22 Imported by: 46

Documentation

Overview

Package api implements the staking backend API.

Package api implements the staking backend API.

Index

Constants

View Source 
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"
)
View Source 
const (
	KindEntity        ThresholdKind = 0
	KindNodeValidator ThresholdKind = 1
	KindNodeCompute   ThresholdKind = 2
	// Threshold kind 3 is reserved for future use.
	KindNodeKeyManager    ThresholdKind = 4
	KindRuntimeCompute    ThresholdKind = 5
	KindRuntimeKeyManager ThresholdKind = 6

	KindEntityName            = "entity"
	KindNodeValidatorName     = "node-validator"
	KindNodeComputeName       = "node-compute"
	KindNodeKeyManagerName    = "node-keymanager"
	KindRuntimeComputeName    = "runtime-compute"
	KindRuntimeKeyManagerName = "runtime-keymanager"
)
View Source 
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"
)
View Source 
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

View Source 
var (
	// AddressV0Context is the unique context for v0 staking account addresses.
	AddressV0Context = address.NewContext("oasis-core/address: staking", 0)
	// AddressRuntimeV0Context is the unique context for v0 runtime account addresses.
	AddressRuntimeV0Context = address.NewContext("oasis-core/address: runtime", 0)
	// AddressBech32HRP is the unique human readable part of Bech32 encoded
	// staking account addresses.
	AddressBech32HRP = address.NewBech32HRP("oasis")
)
View Source 
var (
	// CommonPoolAddress is the common pool address.
	// The address is reserved to prevent it being accidentally used in the actual ledger.
	CommonPoolAddress = NewReservedAddress(
		signature.NewPublicKey("1abe11edc001ffffffffffffffffffffffffffffffffffffffffffffffffffff"),
	)

	// FeeAccumulatorAddress is the per-block fee accumulator address.
	// It holds all fees from txs in a block which are later disbursed to validators appropriately.
	// The address is reserved to prevent it being accidentally used in the actual ledger.
	FeeAccumulatorAddress = NewReservedAddress(
		signature.NewPublicKey("1abe11edfeeaccffffffffffffffffffffffffffffffffffffffffffffffffff"),
	)

	// GovernanceDepositsAddress is the governance deposits address.
	// This address is reserved to prevent it from being accidentally used in the actual ledger.
	GovernanceDepositsAddress = NewReservedAddress(
		signature.NewPublicKey("1abe11eddeaccfffffffffffffffffffffffffffffffffffffffffffffffffff"),
	)

	// ErrInvalidArgument is the error returned on malformed arguments.
	ErrInvalidArgument = errors.New(ModuleName, 1, "staking: invalid argument")

	// ErrInvalidSignature is the error returned on invalid signature.
	ErrInvalidSignature = errors.New(ModuleName, 2, "staking: invalid signature")

	// ErrInsufficientBalance is the error returned when an operation
	// fails due to insufficient balance.
	ErrInsufficientBalance = errors.New(ModuleName, 3, "staking: insufficient balance")

	// ErrInsufficientStake is the error returned when an operation fails
	// due to insufficient stake.
	ErrInsufficientStake = errors.New(ModuleName, 4, "staking: insufficient stake")

	// ErrForbidden is the error returned when an operation is forbidden by
	// policy.
	ErrForbidden = errors.New(ModuleName, 5, "staking: forbidden by policy")

	// ErrInvalidThreshold is the error returned when an invalid threshold kind
	// is specified in a query.
	ErrInvalidThreshold = errors.New(ModuleName, 6, "staking: invalid threshold")

	// ErrTooManyAllowances is the error returned when the number of allowances per account would
	// exceed the maximum allowed number.
	ErrTooManyAllowances = errors.New(ModuleName, 7, "staking: too many allowances")

	// ErrUnderMinDelegationAmount is the error returned when the given escrow
	// amount is lower than the minimum delegation amount specified in the
	// consensus parameters.
	ErrUnderMinDelegationAmount = errors.New(ModuleName, 8, "staking: amount is lower than the minimum delegation amount")

	// ErrUnderMinTransferAmount is the error returned when the given transfer
	// or burn or withdrawal amount is lower than the minimum transfer amount
	// specified in the consensus parameters.
	ErrUnderMinTransferAmount = errors.New(ModuleName, 9, "staking: amount is lower than the minimum transfer amount")

	// ErrBalanceTooLow is the error returned when an account's balance is
	// below the minimum allowed amount.
	ErrBalanceTooLow = errors.New(ModuleName, 10, "staking: balance too low")

	// MethodTransfer is the method name for transfers.
	MethodTransfer = transaction.NewMethodName(ModuleName, "Transfer", Transfer{})
	// MethodBurn is the method name for burns.
	MethodBurn = transaction.NewMethodName(ModuleName, "Burn", Burn{})
	// MethodAddEscrow is the method name for escrows.
	MethodAddEscrow = transaction.NewMethodName(ModuleName, "AddEscrow", Escrow{})
	// MethodReclaimEscrow is the method name for escrow reclamations.
	MethodReclaimEscrow = transaction.NewMethodName(ModuleName, "ReclaimEscrow", ReclaimEscrow{})
	// MethodAmendCommissionSchedule is the method name for amending commission schedules.
	MethodAmendCommissionSchedule = transaction.NewMethodName(ModuleName, "AmendCommissionSchedule", AmendCommissionSchedule{})
	// MethodAllow is the method name for setting a beneficiary allowance.
	MethodAllow = transaction.NewMethodName(ModuleName, "Allow", Allow{})
	// MethodWithdraw is the method name for
	MethodWithdraw = transaction.NewMethodName(ModuleName, "Withdraw", Withdraw{})

	// Methods is the list of all methods supported by the staking backend.
	Methods = []transaction.MethodName{
		MethodTransfer,
		MethodBurn,
		MethodAddEscrow,
		MethodReclaimEscrow,
		MethodAmendCommissionSchedule,
		MethodAllow,
		MethodWithdraw,
	}
)
View Source 
var (
	// CommissionRateDenominator is the denominator for the commission rate.
	CommissionRateDenominator *quantity.Quantity
)
View Source 
var RewardAmountDenominator *quantity.Quantity

RewardAmountDenominator is the denominator for the reward rate.

View Source 
var ThresholdKinds = []ThresholdKind{
	KindEntity,
	KindNodeValidator,
	KindNodeCompute,
	KindNodeKeyManager,
	KindRuntimeCompute,
	KindRuntimeKeyManager,
}

ThresholdKinds are the valid threshold kinds.

Functions

func NewAddEscrowTx 

func NewAddEscrowTx(nonce uint64, fee *transaction.Fee, escrow *Escrow) *transaction.Transaction

NewAddEscrowTx creates a new add escrow transaction.

func NewAllowTx added in v0.2100.0 

func NewAllowTx(nonce uint64, fee *transaction.Fee, allow *Allow) *transaction.Transaction

NewAllowTx creates a new beneficiary allowance configuration transaction.

func NewAmendCommissionScheduleTx 

func NewAmendCommissionScheduleTx(nonce uint64, fee *transaction.Fee, amend *AmendCommissionSchedule) *transaction.Transaction

NewAmendCommissionScheduleTx creates a new amend commission schedule transaction.

func NewBurnTx 

func NewBurnTx(nonce uint64, fee *transaction.Fee, burn *Burn) *transaction.Transaction

NewBurnTx creates a new burn transaction.

func NewReclaimEscrowTx 

func NewReclaimEscrowTx(nonce uint64, fee *transaction.Fee, reclaim *ReclaimEscrow) *transaction.Transaction

NewReclaimEscrowTx creates a new reclaim escrow transaction.

func NewTransferTx 

func NewTransferTx(nonce uint64, fee *transaction.Fee, xfer *Transfer) *transaction.Transaction

NewTransferTx creates a new transfer transaction.

func NewWithdrawTx added in v0.2100.0 

func NewWithdrawTx(nonce uint64, fee *transaction.Fee, withdraw *Withdraw) *transaction.Transaction

NewWithdrawTx creates a new beneficiary allowance configuration transaction.

func PrettyPrintCommissionRatePercentage 

func PrettyPrintCommissionRatePercentage(rateNumerator quantity.Quantity) string

PrettyPrintCommissionRatePercentage returns the string representing the commission rate (bound) in percentage for the given commission rate (bound) numerator.

func PrettyPrintCommissionScheduleIndexInfixes added in v0.2010.1 

func PrettyPrintCommissionScheduleIndexInfixes(ctx context.Context) (indexInfix, emptyInfix string)

PrettyPrintCommissionScheduleIndexInfixes returns two infixes:

  • indexInfix holds the infix to use to pretty print the given commission schedule rate (bound) index
  • emptyInfix holds the infix to use to pretty print an empty string of an equivalent length

func RegisterService 

func RegisterService(server *grpc.Server, service Backend)

RegisterService registers a new staking backend service with the given gRPC server.

func SanityCheckAccount 

func SanityCheckAccount(
	total *quantity.Quantity,
	parameters *ConsensusParameters,
	now beacon.EpochTime,
	addr Address,
	acct *Account,
) error

SanityCheckAccount examines an account's balances. Adds the balances to a running total `total`.

func SanityCheckAccountShares 

func SanityCheckAccountShares(
	addr Address,
	acct *Account,
	delegations map[Address]*Delegation,
	debondingDelegations map[Address][]*DebondingDelegation,
) error

SanityCheckAccountShares examines an account's share pools.

func SanityCheckDebondingDelegations 

func SanityCheckDebondingDelegations(addr Address, account *Account, delegations map[Address][]*DebondingDelegation) error

SanityCheckDebondingDelegations examines an account's debonding delegations.

func SanityCheckDelegations 

func SanityCheckDelegations(addr Address, account *Account, delegations map[Address]*Delegation) error

SanityCheckDelegations examines an account's delegations.

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.

func (Account) PrettyPrint 

func (a Account) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of Account to the given writer.

func (Account) PrettyType 

func (a Account) PrettyType() (interface{}, error)

PrettyType returns a representation of Account that can be used for pretty printing.

type AddEscrowEvent 

type AddEscrowEvent struct {
	Owner     Address           `json:"owner"`
	Escrow    Address           `json:"escrow"`
	Amount    quantity.Quantity `json:"amount"`
	NewShares quantity.Quantity `json:"new_shares"`
}

AddEscrowEvent is the event emitted when stake is transferred into an escrow account.

func (*AddEscrowEvent) EventKind added in v0.2102.2 

func (e *AddEscrowEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type AddEscrowResult added in v0.2200.0 

type AddEscrowResult struct {
	Owner     Address           `json:"owner"`
	Escrow    Address           `json:"escrow"`
	Amount    quantity.Quantity `json:"amount"`
	NewShares quantity.Quantity `json:"new_shares"`
}

AddEscrowResult is the result of add escrow.

type Address 

type Address address.Address

Address is the staking account address.

func NewAddress 

func NewAddress(pk signature.PublicKey) (a Address)

NewAddress creates a new address from the given public key, i.e. entity ID.

func NewReservedAddress 

func NewReservedAddress(pk signature.PublicKey) (a Address)

NewReservedAddress creates a new reserved address from the given public key or panics. NOTE: The given public key is also blacklisted.

func NewRuntimeAddress added in v0.2100.0 

func NewRuntimeAddress(id common.Namespace) (a Address)

NewRuntimeAddress creates a new runtime address for the given runtime ID.

func (Address) Equal 

func (a Address) Equal(cmp Address) bool

Equal compares vs another address for equality.

func (Address) IsReserved 

func (a Address) IsReserved() bool

IsReserved returns true iff the address is reserved, prohibited from regular use.

func (Address) IsValid 

func (a Address) IsValid() bool

IsValid checks whether an address is well-formed and not reserved.

func (Address) MarshalBinary 

func (a Address) MarshalBinary() ([]byte, error)

MarshalBinary encodes an address into binary form.

func (Address) MarshalText 

func (a Address) MarshalText() ([]byte, error)

MarshalText encodes an address into text form.

func (Address) Reserve 

func (a Address) Reserve() error

Reserve adds the address to the reserved addresses list.

func (Address) String 

func (a Address) String() string

String returns the string representation of an address.

func (*Address) UnmarshalBinary 

func (a *Address) UnmarshalBinary(data []byte) error

UnMarshalBinary decodes a binary marshaled address.

func (*Address) UnmarshalText 

func (a *Address) UnmarshalText(text []byte) error

UnmarshalText decodes a text marshaled address.

type Allow added in v0.2100.0 

type Allow struct {
	Beneficiary  Address           `json:"beneficiary"`
	Negative     bool              `json:"negative,omitempty"`
	AmountChange quantity.Quantity `json:"amount_change"`
}

Allow is a beneficiary allowance configuration.

func (Allow) PrettyPrint added in v0.2100.0 

func (aw Allow) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of Allow to the given writer.

func (Allow) PrettyType added in v0.2100.0 

func (aw Allow) PrettyType() (interface{}, error)

PrettyType returns a representation of Allow that can be used for pretty printing.

type AllowanceChangeEvent added in v0.2100.0 

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.

func (*AllowanceChangeEvent) EventKind added in v0.2102.2 

func (e *AllowanceChangeEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type AllowanceQuery added in v0.2100.0 

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.

func (AmendCommissionSchedule) PrettyPrint 

func (acs AmendCommissionSchedule) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of AmendCommissionSchedule to the given writer.

func (AmendCommissionSchedule) PrettyType 

func (acs AmendCommissionSchedule) PrettyType() (interface{}, error)

PrettyType returns a representation of AmendCommissionSchedule that can be used for pretty printing.

type Backend 

type Backend interface {
	// TokenSymbol returns the token's ticker symbol.
	TokenSymbol(ctx context.Context) (string, error)

	// TokenValueExponent is the token's value base-10 exponent, i.e.
	// 1 token = 10**TokenValueExponent base units.
	TokenValueExponent(ctx context.Context) (uint8, error)

	// TotalSupply returns the total number of base units.
	TotalSupply(ctx context.Context, height int64) (*quantity.Quantity, error)

	// CommonPool returns the common pool balance.
	CommonPool(ctx context.Context, height int64) (*quantity.Quantity, error)

	// LastBlockFees returns the collected fees for previous block.
	LastBlockFees(ctx context.Context, height int64) (*quantity.Quantity, error)

	// GovernanceDeposits returns the governance deposits account balance.
	GovernanceDeposits(ctx context.Context, height int64) (*quantity.Quantity, error)

	// Threshold returns the specific staking threshold by kind.
	Threshold(ctx context.Context, query *ThresholdQuery) (*quantity.Quantity, error)

	// Addresses returns the addresses of all accounts with a non-zero general
	// or escrow balance.
	Addresses(ctx context.Context, height int64) ([]Address, error)

	// Account returns the account descriptor for the given account.
	Account(ctx context.Context, query *OwnerQuery) (*Account, error)

	// DelegationsFor returns the list of (outgoing) delegations for the given
	// owner (delegator).
	DelegationsFor(ctx context.Context, query *OwnerQuery) (map[Address]*Delegation, error)

	// DelegationsInfosFor returns (outgoing) delegations with additional
	// information for the given owner (delegator).
	DelegationInfosFor(ctx context.Context, query *OwnerQuery) (map[Address]*DelegationInfo, error)

	// DelegationsTo returns the list of (incoming) delegations to the given
	// account.
	DelegationsTo(ctx context.Context, query *OwnerQuery) (map[Address]*Delegation, error)

	// DebondingDelegationsFor returns the list of (outgoing) debonding
	// delegations for the given owner (delegator).
	DebondingDelegationsFor(ctx context.Context, query *OwnerQuery) (map[Address][]*DebondingDelegation, error)

	// DebondingDelegationsInfosFor returns (outgoing) debonding delegations
	// with additional information for the given owner (delegator).
	DebondingDelegationInfosFor(ctx context.Context, query *OwnerQuery) (map[Address][]*DebondingDelegationInfo, error)

	// DebondingDelegationsTo returns the list of (incoming) debonding
	// delegations to the given account.
	DebondingDelegationsTo(ctx context.Context, query *OwnerQuery) (map[Address][]*DebondingDelegation, error)

	// Allowance looks up the allowance for the given owner/beneficiary combination.
	Allowance(ctx context.Context, query *AllowanceQuery) (*quantity.Quantity, error)

	// StateToGenesis returns the genesis state at specified block height.
	StateToGenesis(ctx context.Context, height int64) (*Genesis, error)

	// ConsensusParameters returns the staking consensus parameters.
	ConsensusParameters(ctx context.Context, height int64) (*ConsensusParameters, error)

	// GetEvents returns the events at specified block height.
	GetEvents(ctx context.Context, height int64) ([]*Event, error)

	// WatchEvents returns a channel that produces a stream of Events.
	WatchEvents(ctx context.Context) (<-chan *Event, pubsub.ClosableSubscription, error)

	// Cleanup cleans up the backend.
	Cleanup()
}

Backend is a staking implementation.

func NewStakingClient 

func NewStakingClient(c *grpc.ClientConn) Backend

NewStakingClient creates a new gRPC staking client service.

type Burn 

type Burn struct {
	Amount quantity.Quantity `json:"amount"`
}

Burn is a stake burn (destruction).

func (Burn) PrettyPrint 

func (b Burn) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of Burn to the given writer.

func (Burn) PrettyType 

func (b Burn) PrettyType() (interface{}, error)

PrettyType returns a representation of Burn that can be used for pretty printing.

type BurnEvent 

type BurnEvent struct {
	Owner  Address           `json:"owner"`
	Amount quantity.Quantity `json:"amount"`
}

BurnEvent is the event emitted when stake is destroyed via a call to Burn.

func (*BurnEvent) EventKind added in v0.2102.2 

func (e *BurnEvent) EventKind() string

EventKind returns a string representation of this event's kind.

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.

func (CommissionRateBoundStep) PrettyPrint 

func (crbs CommissionRateBoundStep) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of CommissionRateBoundStep to the given writer.

func (CommissionRateBoundStep) PrettyType 

func (crbs CommissionRateBoundStep) PrettyType() (interface{}, error)

PrettyType returns a representation of CommissionRateBoundStep that can be used for pretty printing.

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.

func (CommissionRateStep) PrettyPrint 

func (crs CommissionRateStep) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of CommissionRateStep to the given writer.

func (CommissionRateStep) PrettyType 

func (crs CommissionRateStep) PrettyType() (interface{}, error)

PrettyType returns a representation of CommissionRateStep that can be used for pretty printing.

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.

func (*CommissionSchedule) AmendAndPruneAndValidate 

func (cs *CommissionSchedule) AmendAndPruneAndValidate(amendment *CommissionSchedule, rules *CommissionScheduleRules, now beacon.EpochTime) error

AmendAndPruneAndValidate applies a proposed amendment to a valid schedule. Returns an error if there is a validation failure. If it does, the schedule may be amended and pruned already.

func (*CommissionSchedule) CurrentRate 

func (cs *CommissionSchedule) CurrentRate(now beacon.EpochTime) *quantity.Quantity

CurrentRate returns the rate at the latest rate step that has started or nil if no step has started.

func (CommissionSchedule) PrettyPrint 

func (cs CommissionSchedule) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of CommissionSchedule to the given writer.

func (CommissionSchedule) PrettyType 

func (cs CommissionSchedule) PrettyType() (interface{}, error)

PrettyType returns a representation of CommissionSchedule that can be used for pretty printing.

func (*CommissionSchedule) Prune 

func (cs *CommissionSchedule) Prune(now beacon.EpochTime)

Prune discards past steps that aren't in effect anymore.

func (*CommissionSchedule) PruneAndValidateForGenesis 

func (cs *CommissionSchedule) PruneAndValidateForGenesis(rules *CommissionScheduleRules, now beacon.EpochTime) error

PruneAndValidateForGenesis gets a schedule ready for use in the genesis document. Returns an error if there is a validation failure. If it does, the schedule may be pruned already.

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"`
}

CommissionScheduleRules controls how commission schedule rates and rate bounds are allowed to be changed.

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.

func (*ConsensusParameters) SanityCheck 

func (p *ConsensusParameters) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameters.

type DebondingDelegation 

type DebondingDelegation struct {
	Shares        quantity.Quantity `json:"shares"`
	DebondEndTime beacon.EpochTime  `json:"debond_end"`
}

DebondingDelegation is a debonding delegation descriptor.

func (*DebondingDelegation) Merge added in v0.2100.0 

func (d *DebondingDelegation) Merge(other DebondingDelegation) error

Merge merges debonding delegations with same debond end time by summing the shares amounts.

type DebondingDelegationInfo added in v0.2100.0 

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 added in v0.2102.1 

type DebondingStartEscrowEvent struct {
	Owner           Address           `json:"owner"`
	Escrow          Address           `json:"escrow"`
	Amount          quantity.Quantity `json:"amount"`
	ActiveShares    quantity.Quantity `json:"active_shares"`
	DebondingShares quantity.Quantity `json:"debonding_shares"`
	DebondEndTime   beacon.EpochTime  `json:"debond_end_time"`
}

DebondingStartEvent 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.

func (*DebondingStartEscrowEvent) EventKind added in v0.2102.2 

func (e *DebondingStartEscrowEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type Delegation 

type Delegation struct {
	Shares quantity.Quantity `json:"shares"`
}

Delegation is a delegation descriptor.

type DelegationInfo added in v0.2100.0 

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 Escrow 

type Escrow struct {
	Account Address           `json:"account"`
	Amount  quantity.Quantity `json:"amount"`
}

Escrow is a stake escrow.

func (Escrow) PrettyPrint 

func (e Escrow) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of Escrow to the given writer.

func (Escrow) PrettyType 

func (e Escrow) PrettyType() (interface{}, error)

PrettyType returns a representation of Escrow that can be used for pretty printing.

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.

func (*EscrowAccount) AddStakeClaim 

func (e *EscrowAccount) AddStakeClaim(tm map[ThresholdKind]quantity.Quantity, claim StakeClaim, thresholds []StakeThreshold) error

AddStakeClaim attempts to add a stake claim to the given escrow account.

In case there is insufficient stake to cover the claim or an error occurrs, no modifications are made to the stake accumulator.

func (*EscrowAccount) CheckStakeClaims 

func (e *EscrowAccount) CheckStakeClaims(tm map[ThresholdKind]quantity.Quantity) error

CheckStakeClaims checks whether the escrow account balance satisfies all the stake claims.

func (EscrowAccount) PrettyPrint 

func (e EscrowAccount) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of EscrowAccount to the given writer.

func (EscrowAccount) PrettyType 

func (e EscrowAccount) PrettyType() (interface{}, error)

PrettyType returns a representation of EscrowAccount that can be used for pretty printing.

func (*EscrowAccount) RemoveStakeClaim 

func (e *EscrowAccount) RemoveStakeClaim(claim StakeClaim) error

RemoveStakeClaim removes a given stake claim.

It is an error if the stake claim does not exist.

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.

func (GeneralAccount) PrettyPrint 

func (ga GeneralAccount) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of GeneralAccount to the given writer.

func (GeneralAccount) PrettyType 

func (ga GeneralAccount) PrettyType() (interface{}, error)

PrettyType returns a representation of GeneralAccount that can be used for pretty printing.

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.

func (*Genesis) SanityCheck 

func (g *Genesis) SanityCheck(now beacon.EpochTime) error

SanityCheck does basic sanity checking on the genesis state.

type OwnerQuery 

type OwnerQuery struct {
	Height int64   `json:"height"`
	Owner  Address `json:"owner"`
}

OwnerQuery is an owner query.

type ReclaimEscrow 

type ReclaimEscrow struct {
	Account Address           `json:"account"`
	Shares  quantity.Quantity `json:"shares"`
}

ReclaimEscrow is a reclamation of stake from an escrow.

func (ReclaimEscrow) PrettyPrint 

func (re ReclaimEscrow) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of ReclaimEscrow to the given writer.

func (ReclaimEscrow) PrettyType 

func (re ReclaimEscrow) PrettyType() (interface{}, error)

PrettyType returns a representation of Transfer that can be used for pretty printing.

type ReclaimEscrowEvent 

type ReclaimEscrowEvent struct {
	Owner  Address           `json:"owner"`
	Escrow Address           `json:"escrow"`
	Amount quantity.Quantity `json:"amount"`
	Shares quantity.Quantity `json:"shares"`
}

ReclaimEscrowEvent is the event emitted when stake is reclaimed from an escrow account back into owner's general account.

func (*ReclaimEscrowEvent) EventKind added in v0.2102.2 

func (e *ReclaimEscrowEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type ReclaimEscrowResult added in v0.2200.0 

type ReclaimEscrowResult struct {
	Owner           Address           `json:"owner"`
	Escrow          Address           `json:"escrow"`
	Amount          quantity.Quantity `json:"amount"`
	DebondingShares quantity.Quantity `json:"debonding_shares"`
	RemainingShares quantity.Quantity `json:"remaining_shares"`
	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 {
	Balance     quantity.Quantity `json:"balance,omitempty"`
	TotalShares quantity.Quantity `json:"total_shares,omitempty"`
}

SharePool is a combined balance of several entries, the relative sizes of which are tracked through shares.

func (*SharePool) Deposit 

func (p *SharePool) Deposit(shareDst, stakeSrc, baseUnitsAmount *quantity.Quantity) (*quantity.Quantity, error)

Deposit moves stake into the combined balance, raising the shares.

Returns the number of new shares created as a result of the deposit.

If an error occurs, the pool and affected accounts are left in an invalid state.

func (SharePool) PrettyPrint 

func (p SharePool) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of SharePool to the given writer.

func (SharePool) PrettyType 

func (p SharePool) PrettyType() (interface{}, error)

PrettyType returns a representation of SharePool that can be used for pretty printing.

func (*SharePool) StakeForShares added in v0.2100.0 

func (p *SharePool) StakeForShares(amount *quantity.Quantity) (*quantity.Quantity, error)

StakeForShares computes the amount of base units for the given amount of shares.

func (*SharePool) Withdraw 

func (p *SharePool) Withdraw(stakeDst, shareSrc, shareAmount *quantity.Quantity) error

Withdraw moves stake out of the combined balance, reducing the shares. If an error occurs, the pool and affected accounts are left in an invalid state.

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 added in v0.2100.0 

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 added in v0.2100.0 

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.

func (*StakeAccumulator) AddClaimUnchecked 

func (sa *StakeAccumulator) AddClaimUnchecked(claim StakeClaim, thresholds []StakeThreshold)

AddClaimUnchecked adds a new claim without checking its validity.

func (StakeAccumulator) PrettyPrint 

func (sa StakeAccumulator) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of StakeAccumulator to the given writer.

func (StakeAccumulator) PrettyType 

func (sa StakeAccumulator) PrettyType() (interface{}, error)

PrettyType returns a representation of StakeAccumulator that can be used for pretty printing.

func (*StakeAccumulator) RemoveClaim 

func (sa *StakeAccumulator) RemoveClaim(claim StakeClaim) error

RemoveClaim removes a given stake claim.

It is an error if the stake claim does not exist.

func (*StakeAccumulator) TotalClaims 

func (sa *StakeAccumulator) TotalClaims(thresholds map[ThresholdKind]quantity.Quantity, exclude *StakeClaim) (*quantity.Quantity, error)

TotalClaims computes the total amount of stake claims in the accumulator.

type StakeClaim 

type StakeClaim string

StakeClaim is a unique stake claim identifier.

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 GlobalStakeThreshold 

func GlobalStakeThreshold(kind ThresholdKind) StakeThreshold

GlobalStakeThreshold creates a new global StakeThreshold.

func GlobalStakeThresholds 

func GlobalStakeThresholds(kinds ...ThresholdKind) (sts []StakeThreshold)

GlobalStakeThresholds creates a new list of global StakeThresholds.

func (*StakeThreshold) Equal 

func (st *StakeThreshold) Equal(cmp *StakeThreshold) bool

Equal compares vs another stake threshold for equality.

func (StakeThreshold) PrettyPrint 

func (st StakeThreshold) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of StakeThreshold to the given writer.

func (StakeThreshold) PrettyType 

func (st StakeThreshold) PrettyType() (interface{}, error)

PrettyType returns a representation of StakeThreshold that can be used for pretty printing.

func (StakeThreshold) String 

func (st StakeThreshold) String() string

String returns a string representation of a stake threshold.

func (*StakeThreshold) Value 

func (st *StakeThreshold) Value(tm map[ThresholdKind]quantity.Quantity) (*quantity.Quantity, error)

Value returns the value of the stake threshold.

type TakeEscrowEvent 

type TakeEscrowEvent struct {
	Owner  Address           `json:"owner"`
	Amount quantity.Quantity `json:"amount"`
}

TakeEscrowEvent is the event emitted when stake is taken from an escrow account (i.e. stake is slashed).

func (*TakeEscrowEvent) EventKind added in v0.2102.2 

func (e *TakeEscrowEvent) EventKind() string

EventKind returns a string representation of this event's kind.

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 Transfer 

type Transfer struct {
	To     Address           `json:"to"`
	Amount quantity.Quantity `json:"amount"`
}

Transfer is a stake transfer.

func (Transfer) PrettyPrint 

func (t Transfer) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of Transfer to the given writer.

func (Transfer) PrettyType 

func (t Transfer) PrettyType() (interface{}, error)

PrettyType returns a representation of Transfer that can be used for pretty printing.

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.

func (*TransferEvent) EventKind added in v0.2102.2 

func (e *TransferEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type TransferResult added in v0.2200.0 

type TransferResult struct {
	From   Address           `json:"from"`
	To     Address           `json:"to"`
	Amount quantity.Quantity `json:"amount"`
}

TransferResult is the result of staking transfer.

type Withdraw added in v0.2100.0 

type Withdraw struct {
	From   Address           `json:"from"`
	Amount quantity.Quantity `json:"amount"`
}

Withdraw is a withdrawal from an account.

func (Withdraw) PrettyPrint added in v0.2100.0 

func (wt Withdraw) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of Withdraw to the given writer.

func (Withdraw) PrettyType added in v0.2100.0 

func (wt Withdraw) PrettyType() (interface{}, error)

PrettyType returns a representation of Withdraw that can be used for pretty printing.

type WithdrawResult added in v0.2200.0 

type WithdrawResult struct {
	Owner        Address           `json:"owner"`
	Beneficiary  Address           `json:"beneficiary"`
	Allowance    quantity.Quantity `json:"allowance"`
	AmountChange quantity.Quantity `json:"amount_change"`
}

WithdrawResult is the result of withdraw.

Source Files

View all Source files

Directories

Path Synopsis
Package token implements the token-related parts of the staking API.
 Package token implements the token-related parts of the staking API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.