tmstore

Documentation

Overview

Package tmstore contains the store interfaces for the gordian/tm tree.

Index

• Variables
• type ActionStore
• type CommittedHeaderStore
• type DoubleActionError
  • func (e DoubleActionError) Error() string
• type FinalizationOverwriteError
  • func (e FinalizationOverwriteError) Error() string
• type FinalizationStore
• type MirrorStore
• type NoPubKeyHashError
  • func (e NoPubKeyHashError) Error() string
• type NoVotePowerHashError
  • func (e NoVotePowerHashError) Error() string
• type OverwriteError
  • func (e OverwriteError) Error() string
• type PubKeyChangedError
  • func (e PubKeyChangedError) Error() string
• type PubKeyPowerCountMismatchError
  • func (e PubKeyPowerCountMismatchError) Error() string
• type PubKeysAlreadyExistError
  • func (e PubKeysAlreadyExistError) Error() string
• type RoundActions
• type RoundStore
• type StateMachineStore
• type ValidatorStore
• type VotePowersAlreadyExistError
  • func (e VotePowersAlreadyExistError) Error() string

Variables

var ErrStoreUninitialized = errors.New("uninitialized")

ErrStoreUninitialized is returned by certain store methods that need a corresponding Save call before a call to Load is valid.

Types

type ActionStore

type ActionStore interface {
	SaveProposedHeaderAction(context.Context, tmconsensus.ProposedHeader) error

	SavePrevoteAction(ctx context.Context, pubKey gcrypto.PubKey, vt tmconsensus.VoteTarget, sig []byte) error
	SavePrecommitAction(ctx context.Context, pubKey gcrypto.PubKey, vt tmconsensus.VoteTarget, sig []byte) error

	// LoadActions returns all actions recorded for this round.
	LoadActions(ctx context.Context, height uint64, round uint32) (RoundActions, error)
}

ActionStore stores the active actions the current state machine and application take; specifically, proposed blocks, prevotes, and precommits.

type CommittedHeaderStore

type CommittedHeaderStore interface {
	SaveCommittedHeader(ctx context.Context, ch tmconsensus.CommittedHeader) error

	LoadCommittedHeader(ctx context.Context, height uint64) (tmconsensus.CommittedHeader, error)
}

CommittedHeaderStore is the store that the Engine's Mirror uses for committed block headers. The committed headers always lag the voting round by one height. The subsequent header's PrevCommitProof field is the canonical proof. But while the engine is still voting on that height, the RoundStore contains the most up to date previous commit proof for the committing header.

The proofs associated with the committed headers must be considered subjective. That is, while the proof is expected to represent >2/3 voting power for the header, it is not necessarily the same set of signatures as in the subsequent block's PrevCommitProof field.

type DoubleActionError

type DoubleActionError struct {
	Type string
}

DoubleActionError is returned by ActionStore if a proposed block, prevote, or precommit is attempted to be stored in the same height-round more than once.

func (DoubleActionError) Error

func (e DoubleActionError) Error() string

type FinalizationOverwriteError

type FinalizationOverwriteError struct {
	Height uint64
}

FinalizationOverwriteError is returned from [FinalizationStore.SaveFinalization] if a finalization already exists at the given height. This error indicates a serious programming bug.

func (FinalizationOverwriteError) Error

func (e FinalizationOverwriteError) Error() string

type FinalizationStore

type FinalizationStore interface {
	SaveFinalization(
		ctx context.Context,
		height uint64, round uint32,
		blockHash string,
		valSet tmconsensus.ValidatorSet,
		appStateHash string,
	) error

	LoadFinalizationByHeight(ctx context.Context, height uint64) (
		round uint32,
		blockHash string,
		valSet tmconsensus.ValidatorSet,
		appStateHash string,
		err error,
	)
}

type MirrorStore

type MirrorStore interface {
	// Set and get the "network height and round", which is what the Mirror
	// believes to be the current round for voting and the current round
	// for a block being committed.
	//
	// While an ephemeral copy of this value lives in the Mirror,
	// it needs to be persisted to disk in order to resume upon process restart.
	SetNetworkHeightRound(
		ctx context.Context,
		votingHeight uint64, votingRound uint32,
		committingHeight uint64, committingRound uint32,
	) error

	NetworkHeightRound(context.Context) (
		votingHeight uint64, votingRound uint32,
		committingHeight uint64, committingRound uint32,
		err error,
	)
}

MirrorStore contains values that an engine's Mirror needs to read and write.

type NoPubKeyHashError

type NoPubKeyHashError struct {
	Want string
}

NoPubKeyHashError is returned when loading pub keys from the ValidatorStore using a hash that does not exist in the store.

func (NoPubKeyHashError) Error

func (e NoPubKeyHashError) Error() string

type NoVotePowerHashError

type NoVotePowerHashError struct {
	Want string
}

NoPubKeyHashError is returned when loading vote powers from the ValidatorStore using a hash that does not exist in the store.

func (NoVotePowerHashError) Error

func (e NoVotePowerHashError) Error() string

type OverwriteError

type OverwriteError struct {
	Field, Value string
}

OverwriteError is returned from store methods that are not intended to overwrite existing values. The [tmengine] components that manage the store instances, are typically intended to only use the store as durable backup. The presence of an OverwriteError therefore usually indicates a programming bug.

func (OverwriteError) Error

func (e OverwriteError) Error() string

type PubKeyChangedError

type PubKeyChangedError struct {
	ActionType string
	Want, Got  string
}

PubKeyChangedError is returned by ActionStore when attempting to record a prevote and a precommit with two different public keys.

func (PubKeyChangedError) Error

func (e PubKeyChangedError) Error() string

type PubKeyPowerCountMismatchError

type PubKeyPowerCountMismatchError struct {
	NPubKeys, NVotePower int
}

PubKeyPowerCountMismatchError is returned by [ValidatorStore.LoadValidators] when both hashes are valid but they correspond to public keys and vote powers of differing lengths.

func (PubKeyPowerCountMismatchError) Error

func (e PubKeyPowerCountMismatchError) Error() string

type PubKeysAlreadyExistError

type PubKeysAlreadyExistError struct {
	ExistingHash string
}

PubKeysAlreadyExistError is returned when saving an existing set of validators to the ValidatorStore. It can be safely ignored, but it is better to avoid the error if possible.

func (PubKeysAlreadyExistError) Error

func (e PubKeysAlreadyExistError) Error() string

type RoundActions

type RoundActions struct {
	Height uint64
	Round  uint32

	ProposedHeader tmconsensus.ProposedHeader

	PubKey gcrypto.PubKey

	PrevoteTarget    string // Block hash or empty string for nil.
	PrevoteSignature string // Immutable signature.

	PrecommitTarget    string // Block hash or empty string for nil.
	PrecommitSignature string // Immutable signature.
}

RoundActions contains all three possible actions the current validator may have taken for a single round.

type RoundStore

type RoundStore interface {
	// SaveRoundProposedHeader saves the given proposed block header
	// as a candidate proposed header in the given height and round.
	SaveRoundProposedHeader(ctx context.Context, ph tmconsensus.ProposedHeader) error

	// SaveRoundReplayedHeader saves the header as one
	// that is about to be committed in the given height,
	// due to mirror catchup.
	//
	// In the normal mirror flow, the replayed header is saved,
	// and then OverwriteRoundPrecommitProofs is called.
	SaveRoundReplayedHeader(ctx context.Context, h tmconsensus.Header) error

	// The overwrite proofs methods overwrite existing entries
	// for the corresponding proof at the given height and round.
	// TODO: these methods should both accept sparse proofs,
	// as sparse proofs are more suited to storage.
	OverwriteRoundPrevoteProofs(
		ctx context.Context,
		height uint64,
		round uint32,
		proofs tmconsensus.SparseSignatureCollection,
	) error
	OverwriteRoundPrecommitProofs(
		ctx context.Context,
		height uint64,
		round uint32,
		proofs tmconsensus.SparseSignatureCollection,
	) error

	// LoadRoundState returns the saved proposed blocks and votes
	// for the given height and round.
	// The order of the proposed blocks in the pbs slice is undefined
	// and may differ from one call to another.
	//
	// Note that in the event of replayed blocks during a mirror catchup,
	// there may be ProposedHeader values without its PubKey, Signature, or Annotations fields set.
	//
	// If there are no proposed blocks or votes at the given height and round,
	// [tmconsensus.RoundUnknownError] is returned.
	// If at least one proposed block, prevote, or precommit exists at the height and round,
	// a nil error is returned.
	LoadRoundState(ctx context.Context, height uint64, round uint32) (
		phs []tmconsensus.ProposedHeader,
		prevotes, precommits tmconsensus.SparseSignatureCollection,
		err error,
	)
}

RoundStore stores and retrieves the proposed headers, prevotes, and precommits observed during each round.

type StateMachineStore

type StateMachineStore interface {
	// Track the state machine's current height and round,
	// so that it can pick up where it left off, after a process restart.
	SetStateMachineHeightRound(
		ctx context.Context,
		height uint64, round uint32,
	) error

	StateMachineHeightRound(context.Context) (
		height uint64, round uint32,
		err error,
	)
}

StateMachineStore contains values that an engine's state machine needs to read and write.

type ValidatorStore

type ValidatorStore interface {
	// SavePubKeys saves the ordered collection of public keys,
	// and returns the calculated hash to retrieve the same set of keys later.
	SavePubKeys(context.Context, []gcrypto.PubKey) (string, error)

	// SavePubKeys saves the ordered collection of vote powers,
	// and returns the calculated hash to retrieve the same set of powers later.
	SaveVotePowers(context.Context, []uint64) (string, error)

	// LoadPubKeys loads the set of public keys belonging to the given hash.
	LoadPubKeys(context.Context, string) ([]gcrypto.PubKey, error)

	// LoadVotePowers loads the set of vote powers belonging to the given hash.
	LoadVotePowers(context.Context, string) ([]uint64, error)

	// LoadValidators loads a set of validators constituted of the public keys and vote powers
	// corresponding to the given hashes.
	LoadValidators(ctx context.Context, keyHash, powHash string) ([]tmconsensus.Validator, error)
}

ValidatorStore manages storage and retrieval of sets of validators, split into sets of public keys and sets of voting powers.

type VotePowersAlreadyExistError

type VotePowersAlreadyExistError struct {
	ExistingHash string
}

VotePowersAlreadyExistError is returned when saving an existing set of vote powers to the ValidatorStore. It can be safely ignored, but it is better to avoid the error if possible.

func (VotePowersAlreadyExistError) Error

func (e VotePowersAlreadyExistError) Error() string