state

Documentation

Overview

Package state contains the metastate, which is the actual state stored by a metaapp.

It stores such data as the validator set and the height offset, and wraps the application state.

Index

• Constants
• func AtHeight(db datas.Database, ds datas.Dataset, state State, wantHeight uint64) error
• func IsStopIteration(err error) bool
• func IterHistory(db datas.Database, ds datas.Dataset, example State, ...) error
• func StopIteration() error
• func ValUpdateToVal(t *testing.T, vu abci.ValidatorUpdate) abci.Validator
• func ValUpdatesToVals(t *testing.T, vus []abci.ValidatorUpdate) []abci.Validator
• func ValidatorsAreEquivalent(t *testing.T, a, b []abci.Validator)
• type Metastate
  • func (m *Metastate) AppendRoundStats(logger log.FieldLogger, req abci.RequestBeginBlock)
  • func (state *Metastate) Commit(db datas.Database, ds datas.Dataset) (datas.Dataset, error)
  • func (state *Metastate) GetValidators() (validators []abci.Validator, err error)
  • func (state *Metastate) Load(db datas.Database, ds datas.Dataset, child State) (datas.Dataset, error)
  • func (x Metastate) MarshalNoms(vrw nt.ValueReadWriter) (metastateValue nt.Value, err error)
  • func (x *Metastate) UnmarshalNoms(value nt.Value) (err error)
  • func (state *Metastate) UpdateValidator(db datas.Database, v abci.ValidatorUpdate) error
• type NodeRoundStats
  • func (x NodeRoundStats) MarshalNoms(vrw nt.ValueReadWriter) (nodeRoundStatsValue nt.Value, err error)
  • func (x *NodeRoundStats) UnmarshalNoms(value nt.Value) (err error)
• type RoundStats
  • func MakeRoundStats(logger log.FieldLogger, req abci.RequestBeginBlock) RoundStats
  • func (x RoundStats) MarshalNoms(vrw nt.ValueReadWriter) (roundStatsValue nt.Value, err error)
  • func (x *RoundStats) UnmarshalNoms(value nt.Value) (err error)
• type State
• type VoteStats
  • func (vs *VoteStats) Append(rs RoundStats)
  • func (x VoteStats) MarshalNoms(vrw nt.ValueReadWriter) (voteStatsValue nt.Value, err error)
  • func (x *VoteStats) UnmarshalNoms(value nt.Value) (err error)

Constants

const HistorySize = 20

HistorySize is how much history we keep for node performance analysis

We may want this to be a variable stored in metastate in the future, but for now, a const is good enough.

Functions

func AtHeight

func AtHeight(
	db datas.Database, ds datas.Dataset,
	state State,
	wantHeight uint64,
) error

AtHeight retrieves the state as of a given tendermint height and puts it into the provided State object.

Runtime is O(n) where n is the difference between the current noms head height and the noms head height of the desired TM height. n is not visible to external applications, but it will always be t * m, where t is the difference between the current tendermint head height and the desired TM head height, and m is a float in the range [0,1].

func IsStopIteration

func IsStopIteration(err error) bool

IsStopIteration returns true if the supplied error is stopIteration

func IterHistory

func IterHistory(
	db datas.Database, ds datas.Dataset,
	example State,
	cb func(state State, height uint64) error,
) error

IterHistory iterates backward through history from the current head of the DB.

If the callback function returns a non-nil error, iteration is terminated. If the returned error is stopIteration, IterHistory returns nil. Otherwise, the error is propagated.

## Caution

This is fundamentlly a read-only interface. It is not impossible to get a state which is not the head, and make edits to it. However, it is a logic error to do so. Committing edits made to a state which is not the head is like committing edits in git while in detached HEAD mode: the resultant state is orphaned and unreachable.

One may be tempted to manually dig in and issue noms merge commands to make that state reachable. Don't do that. Doing so will break an invariant which this function depends on.

## Technical Background

noms is a git-like database. This gives it many properties that we desire, but it also means that it has some complications that we don't. As in git, though the common case is for a single commit to have a single parent, there exists the notion of a merge commit which has more than one parent.

Unlike git, our use of noms can maintain the invariant that any given noms database will have at most a single client, and any commit will have at most a single parent. We can ensure this because we're using tendermint to establish consensus, instead of noms' native merge system. That invariant makes iterators like this possible.

func StopIteration

func StopIteration() error

StopIteration can be raised inside the IterHistory callback to stop iteration in a way distinguishable from an actual error.

Iterators, python-style.

func ValUpdateToVal

func ValUpdateToVal(t *testing.T, vu abci.ValidatorUpdate) abci.Validator

ValUpdateToVal is a test helper which converts between these equivalent types

func ValUpdatesToVals

func ValUpdatesToVals(t *testing.T, vus []abci.ValidatorUpdate) []abci.Validator

ValUpdatesToVals is a test helper which converts slices between these equivalent types

func ValidatorsAreEquivalent

func ValidatorsAreEquivalent(t *testing.T, a, b []abci.Validator)

ValidatorsAreEquivalent is a test helper which ensures that two lists of validators are in fact equivalent.

Types

type Metastate

type Metastate struct {
	Validators map[string]int64
	Height     uint64
	Stats      VoteStats
	ChildState State
}

Metastate wraps the client app state and keeps track of bookkeeping data such as the validator set and height offset. nomsify Metastate

func (*Metastate) AppendRoundStats

func (m *Metastate) AppendRoundStats(logger log.FieldLogger, req abci.RequestBeginBlock)

AppendRoundStats appends round statistics of the current round to the metastate

func (*Metastate) Commit

func (state *Metastate) Commit(db datas.Database, ds datas.Dataset) (datas.Dataset, error)

Commit the current state and return an updated dataset

func (*Metastate) GetValidators

func (state *Metastate) GetValidators() (validators []abci.Validator, err error)

GetValidators returns a list of validators this app knows of

func (*Metastate) Load

func (state *Metastate) Load(db datas.Database, ds datas.Dataset, child State) (datas.Dataset, error)

Load the metastate from a DB and DS

Initialize the DB if it hasn't already been done. We need an example of the child state so we can properly initialize everything

func (Metastate) MarshalNoms

func (x Metastate) MarshalNoms(vrw nt.ValueReadWriter) (metastateValue nt.Value, err error)

MarshalNoms implements noms/go/marshal.Marshaler

func (*Metastate) UnmarshalNoms

func (x *Metastate) UnmarshalNoms(value nt.Value) (err error)

UnmarshalNoms implements noms/go/marshal.Unmarshaler

This method makes no attempt to zeroize the provided struct; it simply overwrites fields as they are found.

func (*Metastate) UpdateValidator

func (state *Metastate) UpdateValidator(db datas.Database, v abci.ValidatorUpdate) error

UpdateValidator updates the app's internal state with the given validator

type NodeRoundStats

type NodeRoundStats struct {
	Power            int64 `chain:"120,Stats_Power"`
	Voted            bool  `chain:"121,Stats_Voted"`
	AgainstConsensus bool  `chain:"122,Stats_AgainstConsensus"`
}

NodeRoundStats contains information about the votes of a particular node in a particular round

func (NodeRoundStats) MarshalNoms

func (x NodeRoundStats) MarshalNoms(vrw nt.ValueReadWriter) (nodeRoundStatsValue nt.Value, err error)

MarshalNoms implements noms/go/marshal.Marshaler

func (*NodeRoundStats) UnmarshalNoms

func (x *NodeRoundStats) UnmarshalNoms(value nt.Value) (err error)

UnmarshalNoms implements noms/go/marshal.Unmarshaler

This method makes no attempt to zeroize the provided struct; it simply overwrites fields as they are found.

type RoundStats

type RoundStats struct {
	Height     uint64
	Validators map[string]NodeRoundStats
}

RoundStats contains information about the validator set votes in a particular round

func MakeRoundStats

func MakeRoundStats(logger log.FieldLogger, req abci.RequestBeginBlock) RoundStats

MakeRoundStats collects data from a RequestBeginBlock and converts it to a RoundStats, logging as it goes.

func (RoundStats) MarshalNoms

func (x RoundStats) MarshalNoms(vrw nt.ValueReadWriter) (roundStatsValue nt.Value, err error)

MarshalNoms implements noms/go/marshal.Marshaler

func (*RoundStats) UnmarshalNoms

func (x *RoundStats) UnmarshalNoms(value nt.Value) (err error)

UnmarshalNoms implements noms/go/marshal.Unmarshaler

This method makes no attempt to zeroize the provided struct; it simply overwrites fields as they are found.

type State

type State interface {
	marshal.Marshaler
	marshal.Unmarshaler

	// Init initializes the state.
	//
	// It is expected to be implemented on a pointer receiver, and
	// initialize maps etc as required.
	Init(vrw nt.ValueReadWriter)
}

State is a generic application state, backed by noms.

For the most part, actual application implementations will use type assertions to their particular state implementation to gain access to the full range of state functions for that application.

type VoteStats

type VoteStats struct {
	History []RoundStats
}

VoteStats is a rolling window of the N most recent rounds of statistics

It's a struct mainly due to nomsify limitations, but this also lets us internalize certain functions into methods.

func (*VoteStats) Append

func (vs *VoteStats) Append(rs RoundStats)

Append the provided RoundStats to the history

Retain no more than HistorySize items.

func (VoteStats) MarshalNoms

func (x VoteStats) MarshalNoms(vrw nt.ValueReadWriter) (voteStatsValue nt.Value, err error)

MarshalNoms implements noms/go/marshal.Marshaler

func (*VoteStats) UnmarshalNoms

func (x *VoteStats) UnmarshalNoms(value nt.Value) (err error)

UnmarshalNoms implements noms/go/marshal.Unmarshaler

This method makes no attempt to zeroize the provided struct; it simply overwrites fields as they are found.