delegation

Documentation

Index

• Variables
• type Broker
• type Config
  • func NewDefaultConfig() Config
• type Engine
  • func New(log *logging.Logger, config Config, broker Broker, topology ValidatorTopology, ...) *Engine
  • func (e *Engine) Checkpoint() ([]byte, error)
  • func (e *Engine) Delegate(ctx context.Context, party string, nodeID string, amount *num.Uint) error
  • func (e *Engine) GetState(k string) ([]byte, []types.StateProvider, error)
  • func (e *Engine) GetValidatorData() []*types.ValidatorData
  • func (e *Engine) HasChanged(k string) bool
  • func (e *Engine) Hash() []byte
  • func (e *Engine) Keys() []string
  • func (e *Engine) Load(ctx context.Context, data []byte) error
  • func (e *Engine) LoadState(ctx context.Context, p *types.Payload) ([]types.StateProvider, error)
  • func (e *Engine) Name() types.CheckpointName
  • func (e *Engine) Namespace() types.SnapshotNamespace
  • func (e *Engine) OnMinAmountChanged(ctx context.Context, minAmount num.Decimal) error
  • func (e *Engine) OnTick(ctx context.Context, t time.Time)
  • func (e *Engine) ProcessEpochDelegations(ctx context.Context, epoch types.Epoch) []*types.ValidatorData
  • func (e *Engine) Stopped() bool
  • func (e *Engine) UndelegateAtEndOfEpoch(ctx context.Context, party string, nodeID string, amount *num.Uint) error
  • func (e *Engine) UndelegateNow(ctx context.Context, party string, nodeID string, amount *num.Uint) error
  • func (e *Engine) ValidatorKeyChanged(ctx context.Context, oldKey, newKey string)
• type EpochEngine
• type StakingAccounts
• type TimeService
• type ValidatorTopology

Variables

var (
	// ErrPartyHasNoStakingAccount is returned when the staking account for the party cannot be found.
	ErrPartyHasNoStakingAccount = errors.New("cannot find staking account for the party")
	// ErrInvalidNodeID is returned when the node id passed for delegation/undelegation is not a validator node identifier.
	ErrInvalidNodeID = errors.New("invalid node ID")
	// ErrInsufficientBalanceForDelegation is returned when the balance in the staking account is insufficient to cover all committed and pending delegations.
	ErrInsufficientBalanceForDelegation = errors.New("insufficient balance for delegation")
	// ErrIncorrectTokenAmountForUndelegation is returned when the amount to undelegation doesn't match the delegation balance (pending + committed) for the party and validator.
	ErrIncorrectTokenAmountForUndelegation = errors.New("incorrect token amount for undelegation")
	// ErrAmountLTMinAmountForDelegation is returned when the amount to delegate to a node is lower than the minimum allowed amount from network params.
	ErrAmountLTMinAmountForDelegation = errors.New("delegation amount is lower than the minimum amount for delegation for a validator")
)

Types

type Broker

type Broker interface {
	Send(event events.Event)
	SendBatch(events []events.Event)
}

Broker send events we no longer need to generate this mock here, we can use the broker/mocks package instead.

type Config

type Config struct {
	Level encoding.LogLevel `long:"log-level"`
}

Config represent the configuration of the collateral engine.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig creates an instance of the package specific configuration, given a pointer to a logger instance to be used for logging within the package.

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is handling the delegations balances from parties to validators The delegation engine is designed in the following way with the following assumptions: 1. during epoch it is called with delegation requests that update the delegation balance of the party for the next epoch 2. At the end of the epoch: 2.1 updates the delegated balances to reconcile the epoch's staking account balance for each party such that if a party withdrew from their

staking account during the epoch it will not count for them for rewarding

2.2 capture the state after 2.1 to be returned to the rewarding engine 2.3 process all pending delegations.

func New

func New(log *logging.Logger, config Config, broker Broker, topology ValidatorTopology, stakingAccounts StakingAccounts, epochEngine EpochEngine, ts TimeService) *Engine

New instantiates a new delegation engine.

func (*Engine) Checkpoint

func (e *Engine) Checkpoint() ([]byte, error)

func (*Engine) Delegate

func (e *Engine) Delegate(ctx context.Context, party string, nodeID string, amount *num.Uint) error

Delegate updates the delegation balance for the next epoch.

func (*Engine) GetState

func (e *Engine) GetState(k string) ([]byte, []types.StateProvider, error)

func (*Engine) GetValidatorData

func (e *Engine) GetValidatorData() []*types.ValidatorData

GetValidatorData returns the current state of the delegation per node.

func (*Engine) HasChanged

func (e *Engine) HasChanged(k string) bool

func (*Engine) Hash

func (e *Engine) Hash() []byte

func (*Engine) Keys

func (e *Engine) Keys() []string

func (*Engine) Load

func (e *Engine) Load(ctx context.Context, data []byte) error

func (*Engine) LoadState

func (e *Engine) LoadState(ctx context.Context, p *types.Payload) ([]types.StateProvider, error)

func (*Engine) Name

func (e *Engine) Name() types.CheckpointName

func (*Engine) Namespace

func (e *Engine) Namespace() types.SnapshotNamespace

func (*Engine) OnMinAmountChanged

func (e *Engine) OnMinAmountChanged(ctx context.Context, minAmount num.Decimal) error

OnMinAmountChanged updates the network parameter for minDelegationAmount.

func (*Engine) OnTick

func (e *Engine) OnTick(ctx context.Context, t time.Time)

every few blocks try to reconcile the association and nomination for the current and next epoch.

func (*Engine) ProcessEpochDelegations

func (e *Engine) ProcessEpochDelegations(ctx context.Context, epoch types.Epoch) []*types.ValidatorData

ProcessEpochDelegations updates the delegation engine state at the end of a given epoch and returns the validation-delegation data for rewarding for that epoch step 1: process delegation data for the epoch - undelegate if the balance of the staking account doesn't cover all delegations step 2: capture validator delegation data to be returned step 3: apply pending undelegations step 4: apply pending delegations step 5: apply auto delegations epoch here is the epoch that ended.

func (*Engine) Stopped

func (e *Engine) Stopped() bool

func (*Engine) UndelegateAtEndOfEpoch

func (e *Engine) UndelegateAtEndOfEpoch(ctx context.Context, party string, nodeID string, amount *num.Uint) error

UndelegateAtEndOfEpoch increases the pending undelegation balance and potentially decreases the pending delegation balance for a given validator node and party.

func (*Engine) UndelegateNow

func (e *Engine) UndelegateNow(ctx context.Context, party string, nodeID string, amount *num.Uint) error

UndelegateNow changes the balance of delegation immediately without waiting for the end of the epoch if possible it removed balance from pending delegated, if not enough it removes balance from the current epoch delegated amount.

func (*Engine) ValidatorKeyChanged

func (e *Engine) ValidatorKeyChanged(ctx context.Context, oldKey, newKey string)

ValidatorKeyChanged is called when the validator public key (aka party) is changed we need to update all delegation information to use the new key.

type EpochEngine

type EpochEngine interface {
	NotifyOnEpoch(f func(context.Context, types.Epoch), r func(context.Context, types.Epoch))
}

type StakingAccounts

type StakingAccounts interface {
	GetAvailableBalance(party string) (*num.Uint, error)
	GetAvailableBalanceInRange(party string, from, to time.Time) (*num.Uint, error)
}

StakingAccounts provides access to the staking balance of a given party now and within a duration of an epoch.

type TimeService

type TimeService interface {
	GetTimeNow() time.Time
}

TimeService notifies the reward engine on time updates

type ValidatorTopology

type ValidatorTopology interface {
	IsValidatorNodeID(nodeID string) bool
	AllNodeIDs() []string
	Get(key string) *validators.ValidatorData
}

ValidatorTopology represents the topology of validators and can check if a given node is a validator.