validators

Documentation

Overview

Package validators contain the "validator store" for persistent storage of active validators, and candidate validators along with approval tx records. This facilitates reloading validator state, which includes active votes.

When a prospective validator submits a join tx, they are inserted into the validators table with a power of 0. When current validators submit an approve tx, the

Package validators provides a federated network validator manager that persists the validator set and computes validator updates as transactions are processed and blocks finalized. In this system, nodes may request to join the validator set, and the existing nodes approve (or not) the request. The request passes if 2/3 of the validator set at the time of the request approves. A validator is identified by their public key. A node's power is intended weight their approvals, and to indicate if they are to be removed. Removal is typically initiated from a leave transaction or the consensus engine punishing a validator for some bad behavior.

Index

• type Committable
• type Datastore
• type JoinRequest
• type Validator
• type ValidatorMgr
  • func NewValidatorMgr(ctx context.Context, datastore Datastore, committable Committable, ...) (*ValidatorMgr, error)
  • func (vm *ValidatorMgr) ActiveVotes(ctx context.Context) ([]*JoinRequest, []*ValidatorRemoveProposal, error)
  • func (vm *ValidatorMgr) Approve(ctx context.Context, joiner, approver []byte) error
  • func (vm *ValidatorMgr) CurrentSet(ctx context.Context) ([]*Validator, error)
  • func (vm *ValidatorMgr) CurrentValidators(ctx context.Context) ([]*Validator, error)
  • func (vm *ValidatorMgr) Finalize(ctx context.Context) ([]*Validator, error)
  • func (vm *ValidatorMgr) GenesisInit(ctx context.Context, vals []*Validator, blockHeight int64) error
  • func (vm *ValidatorMgr) Join(ctx context.Context, joiner []byte, power int64) error
  • func (vm *ValidatorMgr) Leave(ctx context.Context, leaver []byte) error
  • func (mgr *ValidatorMgr) PriceApprove(ctx context.Context) (price *big.Int, err error)
  • func (mgr *ValidatorMgr) PriceJoin(ctx context.Context) (price *big.Int, err error)
  • func (mgr *ValidatorMgr) PriceLeave(ctx context.Context) (price *big.Int, err error)
  • func (mgr *ValidatorMgr) PriceRemove(ctx context.Context) (price *big.Int, err error)
  • func (vm *ValidatorMgr) Remove(ctx context.Context, target, remover []byte) error
  • func (vm *ValidatorMgr) Update(ctx context.Context, validator []byte, newPower int64) error
  • func (mgr *ValidatorMgr) UpdateBlockHeight(height int64)
• type ValidatorMgrOpt
  • func WithFeeMultiplier(multiplier int64) ValidatorMgrOpt
  • func WithJoinExpiry(joinExpiry int64) ValidatorMgrOpt
  • func WithLogger(logger log.Logger) ValidatorMgrOpt
• type ValidatorRemoveProposal
• type ValidatorStore

Types

type Committable

type Committable interface {
	SetIDFunc(func() ([]byte, error))
	Skip() bool
}

type Datastore

type Datastore interface {
	Execute(ctx context.Context, stmt string, args map[string]any) ([]map[string]any, error)
	Query(ctx context.Context, query string, args map[string]any) ([]map[string]any, error)
}

type JoinRequest

type JoinRequest = types.JoinRequest

type Validator

type Validator = types.Validator

type ValidatorMgr

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

ValidatorMgr defines specific validator join/approve/leave mechanics for a federated network.

func NewValidatorMgr

func NewValidatorMgr(ctx context.Context, datastore Datastore, committable Committable, opts ...ValidatorMgrOpt) (*ValidatorMgr, error)

func (*ValidatorMgr) ActiveVotes

func (vm *ValidatorMgr) ActiveVotes(ctx context.Context) ([]*JoinRequest, []*ValidatorRemoveProposal, error)

ActiveVotes returns the current committed validator join requests.

func (*ValidatorMgr) Approve

func (vm *ValidatorMgr) Approve(ctx context.Context, joiner, approver []byte) error

Approve records an approval transaction from a current validator.

func (*ValidatorMgr) CurrentSet

func (vm *ValidatorMgr) CurrentSet(ctx context.Context) ([]*Validator, error)

CurrentSet returns the current validator list. This may be used on construction of a resuming application.

func (*ValidatorMgr) CurrentValidators

func (vm *ValidatorMgr) CurrentValidators(ctx context.Context) ([]*Validator, error)

CurrentValidators returns the current validator set.

func (*ValidatorMgr) Finalize

func (vm *ValidatorMgr) Finalize(ctx context.Context) ([]*Validator, error)

Finalize is used at the end of block processing to retrieve the validator updates to be provided to the consensus client for the next block. This is not idempotent. The modules working list of updates is reset until subsequent join/approves are processed for the next block. end of block processing requires providing list of updates to the node's consensus client

func (*ValidatorMgr) GenesisInit

func (vm *ValidatorMgr) GenesisInit(ctx context.Context, vals []*Validator, blockHeight int64) error

GenesisInit is called at the genesis block to set an initial list of validators.

func (*ValidatorMgr) Join

func (vm *ValidatorMgr) Join(ctx context.Context, joiner []byte, power int64) error

Join creates a join request for a prospective validator.

func (*ValidatorMgr) Leave

func (vm *ValidatorMgr) Leave(ctx context.Context, leaver []byte) error

Leave processes a leave request for a current validator.

func (*ValidatorMgr) PriceApprove

func (mgr *ValidatorMgr) PriceApprove(ctx context.Context) (price *big.Int, err error)

PriceApprove returns the price of approving a join request.

func (*ValidatorMgr) PriceJoin

func (mgr *ValidatorMgr) PriceJoin(ctx context.Context) (price *big.Int, err error)

PriceJoin returns the price of issuing a join request.

func (*ValidatorMgr) PriceLeave

func (mgr *ValidatorMgr) PriceLeave(ctx context.Context) (price *big.Int, err error)

PriceLeave returns the price of issuing a leave request.

func (*ValidatorMgr) PriceRemove

func (mgr *ValidatorMgr) PriceRemove(ctx context.Context) (price *big.Int, err error)

PriceRemove returns the price of a remove request.

func (*ValidatorMgr) Remove

func (vm *ValidatorMgr) Remove(ctx context.Context, target, remover []byte) error

Remove stores a remove proposal. It should check that both the remover and target are both current validators. There should not already be a removal proposal recorded from this remover for this target. It should insert a row into the removals table. Finalize should do the removal counting and if the threshold is reached, the target validator should be removed and all the entries in the removals table for this target validator deleted.

func (*ValidatorMgr) Update

func (vm *ValidatorMgr) Update(ctx context.Context, validator []byte, newPower int64) error

Update may be used at the start of block processing when byzantine validators are listed by the consensus client, or to process a leave request.

func (*ValidatorMgr) UpdateBlockHeight

func (mgr *ValidatorMgr) UpdateBlockHeight(height int64)

type ValidatorMgrOpt

type ValidatorMgrOpt func(*ValidatorMgr)

func WithFeeMultiplier

func WithFeeMultiplier(multiplier int64) ValidatorMgrOpt

func WithJoinExpiry

func WithJoinExpiry(joinExpiry int64) ValidatorMgrOpt

func WithLogger

func WithLogger(logger log.Logger) ValidatorMgrOpt

WithLogger sets the logger

type ValidatorRemoveProposal

type ValidatorRemoveProposal = types.ValidatorRemoveProposal

type ValidatorStore

type ValidatorStore interface {
	Init(ctx context.Context, vals []*Validator) error
	CurrentValidators(ctx context.Context) ([]*Validator, error)
	UpdateValidatorPower(ctx context.Context, validator []byte, power int64) error
	ActiveVotes(ctx context.Context) ([]*JoinRequest, []*ValidatorRemoveProposal, error)
	StartJoinRequest(ctx context.Context, joiner []byte, approvers [][]byte, power int64, expiresAt int64) error
	DeleteJoinRequest(ctx context.Context, joiner []byte) error
	AddApproval(ctx context.Context, joiner, approver []byte) error
	AddRemoval(ctx context.Context, target, validator []byte) error
	DeleteRemoval(ctx context.Context, target, validator []byte) error
	AddValidator(ctx context.Context, joiner []byte, power int64) error
	RemoveValidator(ctx context.Context, validator []byte) error
}