Back to godoc.org

Package api

v0.2011.3
Latest Go to latest

The latest major version is .

Published: Oct 16, 2020 | License: Apache-2.0 | Module: github.com/oasisprotocol/oasis-core/go

Overview

Package api implements the staking backend API.

Package api implements the staking backend API.

Index

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
	KindNodeStorage       ThresholdKind = 3
	KindNodeKeyManager    ThresholdKind = 4
	KindRuntimeCompute    ThresholdKind = 5
	KindRuntimeKeyManager ThresholdKind = 6

	KindMax = KindRuntimeKeyManager

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

Variables

var (
	// AddressV0Context is the unique context for v0 staking account addresses.
	AddressV0Context = address.NewContext("oasis-core/address: staking", 0)
	// AddressBech32HRP is the unique human readable part of Bech32 encoded
	// staking account addresses.
	AddressBech32HRP = address.NewBech32HRP("oasis")
)
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"),
	)

	// 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")

	// 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{})

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

RewardAmountDenominator is the denominator for the reward rate.

func NewAddEscrowTx

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

NewAddEscrowTx creates a new add escrow 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 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

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

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

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

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 (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 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)

	// 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)

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

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

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

	// Paremeters 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.

type CommissionRateBoundStep

type CommissionRateBoundStep struct {
	// Epoch when the commission rate bound will go in effect.
	Start epochtime.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 epochtime.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 epochtime.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 epochtime.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 epochtime.EpochTime)

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

func (*CommissionSchedule) PruneAndValidateForGenesis

func (cs *CommissionSchedule) PruneAndValidateForGenesis(rules *CommissionScheduleRules, now epochtime.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 epochtime.EpochTime `json:"rate_change_interval,omitempty"`
	// Number of epochs a commission rate bound change must specified in advance.
	RateBoundLead epochtime.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                 epochtime.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"`

	DisableTransfers       bool             `json:"disable_transfers,omitempty"`
	DisableDelegation      bool             `json:"disable_delegation,omitempty"`
	UndisableTransfersFrom map[Address]bool `json:"undisable_transfers_from,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 epochtime.EpochTime `json:"debond_end"`
}

DebondingDelegation is a debonding delegation descriptor.

type Delegation

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

Delegation is a delegation descriptor.

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

Event signifies a staking event, returned via GetEvents.

type GeneralAccount

type GeneralAccount struct {
	Balance quantity.Quantity `json:"balance,omitempty"`
	Nonce   uint64            `json:"nonce,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"`

	// 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 epochtime.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"`
}

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

type RewardStep

type RewardStep struct {
	Until epochtime.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) error

Deposit moves stake into the combined balance, raising the shares. 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) 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 epochtime.EpochTime `json:"freeze_interval"`
}

Slash is the per-reason slashing configuration.

type SlashReason

type SlashReason int

SlashReason is the reason why a node was slashed.

const (
	// SlashDoubleSigning is slashing due to double signing.
	SlashDoubleSigning SlashReason = 0

	SlashMax = SlashDoubleSigning
)

func (SlashReason) String

func (s SlashReason) String() string

String returns a string representation of 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

GlobalStakeTreshold creates a new global StakeThreshold.

func GlobalStakeThresholds

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

GlobalStakeTresholds 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).

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

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier