voting

Documentation

Overview

package events is used to track events that need to be included in a Kwil block. It contains an event store that is outside of consensus. The event store's primary purpose is to store events that are heard from other chains, and delete them once the node can verify that their event vote has been included in a block.

Index

• Constants
• Variables
• func ApproveResolution(ctx context.Context, db sql.TxMaker, resolutionID *types.UUID, from []byte) error
• func CreateResolution(ctx context.Context, db sql.TxMaker, event *types.VotableEvent, ...) error
• func DeleteEvent(ctx context.Context, db sql.Executor, id *types.UUID) error
• func DeleteEvents(ctx context.Context, db sql.DB, ids ...*types.UUID) error
• func DeleteResolutions(ctx context.Context, db sql.Executor, ids ...*types.UUID) error
• func FilterNotProcessed(ctx context.Context, db sql.Executor, ids []*types.UUID) ([]*types.UUID, error)
• func GetEvents(ctx context.Context, db sql.Executor) ([]*types.VotableEvent, error)
• func GetExpired(ctx context.Context, db sql.Executor, blockHeight int64) ([]*resolutions.Resolution, error)
• func GetResolutionIDsByTypeAndProposer(ctx context.Context, db sql.Executor, resType string, proposer []byte) ([]*types.UUID, error)
• func GetResolutionInfo(ctx context.Context, db sql.Executor, id *types.UUID) (*resolutions.Resolution, error)
• func GetResolutionsByThresholdAndType(ctx context.Context, db sql.TxMaker, threshold *big.Rat, resType string, ...) ([]*resolutions.Resolution, error)
• func GetResolutionsByType(ctx context.Context, db sql.Executor, resType string) ([]*resolutions.Resolution, error)
• func GetValidatorPower(ctx context.Context, db sql.Executor, identifier []byte) (power int64, err error)
• func GetValidators(ctx context.Context, db sql.Executor) ([]*types.Validator, error)
• func IsProcessed(ctx context.Context, tx sql.Executor, resolutionID *types.UUID) (bool, error)
• func MarkProcessed(ctx context.Context, db sql.Executor, ids ...*types.UUID) error
• func RequiredPower(ctx context.Context, db sql.Executor, threshold *big.Rat, totalPower int64) int64
• func SetValidatorPower(ctx context.Context, db sql.Executor, recipient []byte, power int64) error
• type DB
• type EventStore
  • func NewEventStore(ctx context.Context, eventWriterDB DB) (*EventStore, error)
  • func (e *EventStore) GetUnbroadcastedEvents(ctx context.Context) ([]*types.UUID, error)
  • func (e *EventStore) KV(prefix []byte) *KV
  • func (e *EventStore) MarkBroadcasted(ctx context.Context, ids []*types.UUID) error
  • func (e *EventStore) MarkRebroadcast(ctx context.Context, ids []*types.UUID) error
  • func (e *EventStore) Store(ctx context.Context, data []byte, eventType string) error
• type KV
  • func (s *KV) Delete(ctx context.Context, key []byte) error
  • func (s *KV) Get(ctx context.Context, key []byte) ([]byte, error)
  • func (s *KV) Set(ctx context.Context, key, value []byte) error
• type UpdatePowerRequest
  • func (j *UpdatePowerRequest) MarshalBinary() ([]byte, error)
  • func (j *UpdatePowerRequest) UnmarshalBinary(data []byte) error

Constants

const (
	ValidatorJoinEventType   = "validator_join"
	ValidatorRemoveEventType = "validator_remove"
)

const (
	ValidatorVoteBodyBytePrice = 1000      // Per byte cost
	ValidatorVoteIDPrice       = 1000 * 16 // 16 bytes for the UUID
)

Variables

var (
	ErrAlreadyProcessed         = errors.New("resolution already processed")
	ErrResolutionAlreadyHasBody = errors.New("resolution already has a body")
)

Functions

func ApproveResolution

func ApproveResolution(ctx context.Context, db sql.TxMaker, resolutionID *types.UUID, from []byte) error

ApproveResolution approves a resolution from a voter. If the resolution does not yet exist, it will be errored, Validators should only vote on existing resolutions. If the voter does not exist, an error will be returned. If the voter has already approved the resolution, no error will be returned. This should not be used if the resolution has already been processed (see FilterNotProcessed)

func CreateResolution

func CreateResolution(ctx context.Context, db sql.TxMaker, event *types.VotableEvent, expiration int64, voteBodyProposer []byte) error

CreateResolution creates a resolution for a votable event. The expiration should be a block height. If the resolution already exists do nothing. We should not add resolutions that have been processed, but we will because it will be cleaned out after they reach expiry without being processed.

func DeleteEvent

func DeleteEvent(ctx context.Context, db sql.Executor, id *types.UUID) error

DeleteEvent deletes an event from the event store. It is idempotent. If the event does not exist, it will not return an error.

func DeleteEvents

func DeleteEvents(ctx context.Context, db sql.DB, ids ...*types.UUID) error

DeleteEvents deletes a list of events from the event store. It is idempotent. If the event does not exist, it will not return an error.

func DeleteResolutions

func DeleteResolutions(ctx context.Context, db sql.Executor, ids ...*types.UUID) error

DeleteResolutions deletes a slice of resolution IDs from the database. It will mark the resolutions as processed in the processed table.

func FilterNotProcessed

func FilterNotProcessed(ctx context.Context, db sql.Executor, ids []*types.UUID) ([]*types.UUID, error)

FilterNotProcessed takes a set of resolutions and returns the ones that have not been processed. If a resolution does not exist, it WILL be included in the result.

func GetEvents

func GetEvents(ctx context.Context, db sql.Executor) ([]*types.VotableEvent, error)

GetEvents gets all events in the event store to which resolutions have not yet been created.

func GetExpired

func GetExpired(ctx context.Context, db sql.Executor, blockHeight int64) ([]*resolutions.Resolution, error)

GetExpired returns all resolutions with an expiration less than or equal to the given block height.

func GetResolutionIDsByTypeAndProposer

func GetResolutionIDsByTypeAndProposer(ctx context.Context, db sql.Executor, resType string, proposer []byte) ([]*types.UUID, error)

GetResolutionIDsByTypeAndProposer gets all resolution ids of a specific type and the body proposer.

func GetResolutionInfo

func GetResolutionInfo(ctx context.Context, db sql.Executor, id *types.UUID) (*resolutions.Resolution, error)

GetResolutionInfo gets a resolution, identified by the ID.

func GetResolutionsByThresholdAndType

func GetResolutionsByThresholdAndType(ctx context.Context, db sql.TxMaker, threshold *big.Rat, resType string, totalPower int64) ([]*resolutions.Resolution, error)

GetResolutionsByThresholdAndType gets all resolutions that have reached the threshold of votes and are of a specific type.

func GetResolutionsByType

func GetResolutionsByType(ctx context.Context, db sql.Executor, resType string) ([]*resolutions.Resolution, error)

GetResolutionsByType gets all resolutions of a specific type.

func GetValidatorPower

func GetValidatorPower(ctx context.Context, db sql.Executor, identifier []byte) (power int64, err error)

GetValidatorPower gets the power of a voter. If the voter does not exist, it will return 0.

func GetValidators

func GetValidators(ctx context.Context, db sql.Executor) ([]*types.Validator, error)

GetValidators gets all voters in the vote store, along with their power.

func IsProcessed

func IsProcessed(ctx context.Context, tx sql.Executor, resolutionID *types.UUID) (bool, error)

IsProcessed checks if a vote has been marked as processed.

func MarkProcessed

func MarkProcessed(ctx context.Context, db sql.Executor, ids ...*types.UUID) error

MarkProcessed marks a set of resolutions as processed.

func RequiredPower

func RequiredPower(ctx context.Context, db sql.Executor, threshold *big.Rat, totalPower int64) int64

RequiredPower gets the required power to meet the threshold requirements.

func SetValidatorPower

func SetValidatorPower(ctx context.Context, db sql.Executor, recipient []byte, power int64) error

SetValidatorPower sets the power of a voter. It will create the voter if it does not exist. It will return an error if a negative power is given. If set to 0, the voter will be deleted.

Types

type DB

type DB interface {
	sql.ReadTxMaker // i.e. outer! cannot be the consensus connection
	sql.DB          // make txns, and run bare execute
}

DB is a database connection.

type EventStore

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

EventStore stores events from external sources. Kwil uses the event store to track received events, and ensure that they are broadcasted to the network. It follows an at-least-once semantic, and so each event body should be unique. Events can be added idempotently; calling StoreEvent for an event that has already been stored or processed will incur some computational overhead, but will not cause any issues. Voters would then create resolutions for these events, and vote on them.

func NewEventStore

func NewEventStore(ctx context.Context, eventWriterDB DB) (*EventStore, error)

NewEventStore will initialize the event and vote store with the provided DB connection, which is retained by the EventStore. This must not be the writer connection used to update state by the consensus application. Updates that are to be performed in the same transaction that updates state are done in functions that are passed the consensus DB connection.

func (*EventStore) GetUnbroadcastedEvents

func (e *EventStore) GetUnbroadcastedEvents(ctx context.Context) ([]*types.UUID, error)

GetUnbroadcastedEvents filters out the events observed by the validator that are not previously broadcasted.

func (*EventStore) KV

func (e *EventStore) KV(prefix []byte) *KV

KV returns a kv store that is scoped to the given prefix. It allows the user to define their own semantics for tracking committed data. For example, it can be used to track the latest block number of some other chain. This allows users to implement complex logic for efficient restart, to avoid re-processing events. Key uniqueness is scoped to the event type.

func (*EventStore) MarkBroadcasted

func (e *EventStore) MarkBroadcasted(ctx context.Context, ids []*types.UUID) error

MarkBroadcasted marks the event as broadcasted.

func (*EventStore) MarkRebroadcast

func (e *EventStore) MarkRebroadcast(ctx context.Context, ids []*types.UUID) error

MarkRebroadcast marks the event to be rebroadcasted. Usually in scenarios where the transaction was rejected by mempool due to invalid nonces.

func (*EventStore) Store

func (e *EventStore) Store(ctx context.Context, data []byte, eventType string) error

Store stores an event in the event store. It uses the local connection to the event store, instead of the consensus connection. It only stores unprocessed events. If an event is already processed.

type KV

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

KV is a KVStore that is scoped to an event type.

func (*KV) Delete

func (s *KV) Delete(ctx context.Context, key []byte) error

func (*KV) Get

func (s *KV) Get(ctx context.Context, key []byte) ([]byte, error)

func (*KV) Set

func (s *KV) Set(ctx context.Context, key, value []byte) error

type UpdatePowerRequest

type UpdatePowerRequest struct {
	PubKey []byte
	Power  int64
}

UpdatePowerRequest is a request to update a validator's power.

func (*UpdatePowerRequest) MarshalBinary

func (j *UpdatePowerRequest) MarshalBinary() ([]byte, error)

MarshalBinary returns the binary representation of the join request It is deterministic

func (*UpdatePowerRequest) UnmarshalBinary

func (j *UpdatePowerRequest) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshals the join request from its binary representation