api

package
v0.0.0-...-9865f5a Latest Latest
Warning

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

 Go to latest Published: Jun 1, 2020 License: Apache-2.0 Imports: 12 Imported by: 0

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

View Source 
var (
	// CommonPoolAccountID signifies the common pool in staking events.
	// The ID is invalid to prevent it being accidentally used in the
	// actual ledger.
	CommonPoolAccountID = signature.NewBlacklistedKey("1abe11edc001ffffffffffffffffffffffffffffffffffffffffffffffffffff")

	// FeeAccumulatorAccountID signifies the staking fee accumulator in
	// staking events.
	// The ID is invalid to prevent it being accidentally used in the
	// actual ledger.
	FeeAccumulatorAccountID = signature.NewBlacklistedKey("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 forbiden 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,
	}
)
View Source 
var CommissionRateDenominator *quantity.Quantity

CommissionRateDenominator is the denominator for the commission rate.

View Source 
var RewardAmountDenominator *quantity.Quantity

RewardAmountDenominator is the denominator for the reward rate.

Functions

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 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, id signature.PublicKey, acct *Account) error

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

func SanityCheckAccountShares 

func SanityCheckAccountShares(id signature.PublicKey, acct *Account, delegations map[signature.PublicKey]*Delegation, debondingDelegations map[signature.PublicKey][]*DebondingDelegation) error

SanityCheckAccountShares examines an account's share pools.

func SanityCheckDebondingDelegations 

func SanityCheckDebondingDelegations(id signature.PublicKey, account *Account, delegations map[signature.PublicKey][]*DebondingDelegation) error

SanityCheckDebondingDelegations examines an account's debonding delegations.

func SanityCheckDelegations 

func SanityCheckDelegations(id signature.PublicKey, account *Account, delegations map[signature.PublicKey]*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 acounts are used to hold funds delegated for staking.

type AddEscrowEvent 

type AddEscrowEvent struct {
	Owner  signature.PublicKey `json:"owner"`
	Escrow signature.PublicKey `json:"escrow"`
	Tokens quantity.Quantity   `json:"tokens"`
}

AddEscrowEvent is the event emitted when a balance is transfered into an escrow balance.

type AmendCommissionSchedule 

type AmendCommissionSchedule struct {
	Amendment CommissionSchedule `json:"amendment"`
}

AmendCommissionSchedule is an amendment to a commission schedule.

type Backend 

type Backend interface {
	// TotalSupply returns the total number of tokens.
	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)

	// Accounts returns the IDs of all accounts with a non-zero general
	// or escrow balance.
	Accounts(ctx context.Context, height int64) ([]signature.PublicKey, error)

	// AccountInfo returns the account descriptor for the given account.
	AccountInfo(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[signature.PublicKey]*Delegation, error)

	// DebondingDelegations returns the list of debonding delegations for
	// the given owner (delegator).
	DebondingDelegations(ctx context.Context, query *OwnerQuery) (map[signature.PublicKey][]*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)

	// WatchTransfers returns a channel that produces a stream of TranserEvent
	// on all balance transfers.
	WatchTransfers(ctx context.Context) (<-chan *TransferEvent, pubsub.ClosableSubscription, error)

	// WatchBurns returns a channel of BurnEvent on token destruction.
	WatchBurns(ctx context.Context) (<-chan *BurnEvent, pubsub.ClosableSubscription, error)

	// WatchEscrows returns a channel that produces a stream of EscrowEvent
	// when entities add to their escrow balance, get tokens deducted from
	// their escrow balance, and have their escrow balance released into their
	// general balance.
	WatchEscrows(ctx context.Context) (<-chan *EscrowEvent, pubsub.ClosableSubscription, error)

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

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

Backend is a staking token implementation.

func NewStakingClient 

func NewStakingClient(c *grpc.ClientConn) Backend

NewStakingClient creates a new gRPC staking client service.

type Burn 

type Burn struct {
	Tokens quantity.Quantity `json:"burn_tokens"`
}

Burn is a token burn (destruction).

type BurnEvent 

type BurnEvent struct {
	Owner  signature.PublicKey `json:"owner"`
	Tokens quantity.Quantity   `json:"tokens"`
}

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

type CommissionRateBoundStep 

type CommissionRateBoundStep struct {
	Start   epochtime.EpochTime `json:"start,omitempty"`
	RateMin quantity.Quantity   `json:"rate_min,omitempty"`
	RateMax quantity.Quantity   `json:"rate_max,omitempty"`
}

type CommissionRateStep 

type CommissionRateStep struct {
	Start epochtime.EpochTime `json:"start,omitempty"`
	Rate  quantity.Quantity   `json:"rate,omitempty"`
}

type CommissionSchedule 

type CommissionSchedule struct {
	Rates  []CommissionRateStep      `json:"rates,omitempty"`
	Bounds []CommissionRateBoundStep `json:"bounds,omitempty"`
}

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) 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 {
	RateChangeInterval epochtime.EpochTime `json:"rate_change_interval,omitempty"`
	RateBoundLead      epochtime.EpochTime `json:"rate_bound_lead,omitempty"`
	MaxRateSteps       uint16              `json:"max_rate_steps,omitempty"`
	MaxBoundSteps      uint16              `json:"max_bound_steps,omitempty"`
}

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[signature.PublicKey]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 signature.PublicKey `json:"escrow_account"`
	Tokens  quantity.Quantity   `json:"escrow_tokens"`
}

Escrow is a token escrow.

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 []ThresholdKind) 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) 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 {
	TxHash hash.Hash `json:"tx_hash,omitempty"`

	TransferEvent *TransferEvent `json:"transfer,omitempty"`
	BurnEvent     *BurnEvent     `json:"burn,omitempty"`
	EscrowEvent   *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.

type Genesis 

type Genesis struct {
	Parameters ConsensusParameters `json:"params"`

	TotalSupply   quantity.Quantity `json:"total_supply"`
	CommonPool    quantity.Quantity `json:"common_pool"`
	LastBlockFees quantity.Quantity `json:"last_block_fees"`

	Ledger map[signature.PublicKey]*Account `json:"ledger,omitempty"`

	Delegations          map[signature.PublicKey]map[signature.PublicKey]*Delegation            `json:"delegations,omitempty"`
	DebondingDelegations map[signature.PublicKey]map[signature.PublicKey][]*DebondingDelegation `json:"debonding_delegations,omitempty"`
}

Genesis is the initial ledger balances at genesis for use in the genesis block and test cases.

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  signature.PublicKey `json:"owner"`
}

OwnerQuery is an owner query.

type ReclaimEscrow 

type ReclaimEscrow struct {
	Account signature.PublicKey `json:"escrow_account"`
	Shares  quantity.Quantity   `json:"reclaim_shares"`
}

ReclaimEscrow is a token escrow reclimation.

type ReclaimEscrowEvent 

type ReclaimEscrowEvent struct {
	Owner  signature.PublicKey `json:"owner"`
	Escrow signature.PublicKey `json:"escrow"`
	Tokens quantity.Quantity   `json:"tokens"`
}

ReclaimEscrowEvent is the event emitted when tokens are reclaimed from an escrow balance back into the entity's general balance.

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, tokenSrc, tokenAmount *quantity.Quantity) error

Deposit moves tokens into the combined balance, raising the shares. If an error occurs, the pool and affected accounts are left in an invalid state.

func (*SharePool) Withdraw 

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

Withdraw moves tokens 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][]ThresholdKind `json:"claims,omitempty"`
}

StakeAccumulator is a per-escrow-account stake accumulator.

func (*StakeAccumulator) AddClaimUnchecked 

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

AddClaimUnchecked adds a new claim without checking its validity.

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 TakeEscrowEvent 

type TakeEscrowEvent struct {
	Owner  signature.PublicKey `json:"owner"`
	Tokens quantity.Quantity   `json:"tokens"`
}

TakeEscrowEvent is the event emitted when balance is deducted from an escrow balance (stake is slashed).

type ThresholdKind 

type ThresholdKind int

ThresholdKind is the kind of staking threshold. 

const (
	KindEntity            ThresholdKind = 0
	KindNodeValidator     ThresholdKind = 1
	KindNodeCompute       ThresholdKind = 2
	KindNodeStorage       ThresholdKind = 3
	KindNodeKeyManager    ThresholdKind = 4
	KindRuntimeCompute    ThresholdKind = 5
	KindRuntimeKeyManager ThresholdKind = 6

	KindMax = KindRuntimeKeyManager
)

func (ThresholdKind) String 

func (k ThresholdKind) String() string

String returns the string representation of 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     signature.PublicKey `json:"xfer_to"`
	Tokens quantity.Quantity   `json:"xfer_tokens"`
}

Transfer is a token transfer.

type TransferEvent 

type TransferEvent struct {
	From   signature.PublicKey `json:"from"`
	To     signature.PublicKey `json:"to"`
	Tokens quantity.Quantity   `json:"tokens"`
}

TransferEvent is the event emitted when a balance is transfered, either by a call to Transfer or Withdraw.

Source Files

View all Source files

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.