Version: v0.2010.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2020 License: Apache-2.0 Imports: 12 Imported by: 7



Package api implements the root hash backend API and common datastructures.



View Source
const (
	// ModuleName is a unique module name for the roothash module.
	ModuleName = "roothash"

	// LogEventExecutionDiscrepancyDetected is a log event value that signals
	// an execution discrepancy has been detected.
	LogEventExecutionDiscrepancyDetected = "roothash/execution_discrepancy_detected"
	// LogEventTimerFired is a log event value that signals a timer has fired.
	LogEventTimerFired = "roothash/timer_fired"
	// LogEventRoundFailed is a log event value that signals a round has failed.
	LogEventRoundFailed = "roothash/round_failed"
	// LogEventMessageUnsat is a log event value that signals a roothash message was not satisfactory.
	LogEventMessageUnsat = "roothash/message_unsat"
	// LogEventHistoryReindexing is a log event value that signals a roothash runtime reindexing
	// was run.
	LogEventHistoryReindexing = "roothash/history_reindexing"
View Source
const (
	// GasOpComputeCommit is the gas operation identifier for compute commits.
	GasOpComputeCommit transaction.Op = "compute_commit"

	// GasOpProposerTimeout is the gas operation identifier for executor propose timeout cost.
	GasOpProposerTimeout transaction.Op = "proposer_timeout"


View Source
var (
	// ErrInvalidArgument is the error returned on malformed argument(s).
	ErrInvalidArgument = errors.New(ModuleName, 1, "roothash: invalid argument")

	// ErrNotFound is the error returned when a block is not found.
	ErrNotFound = errors.New(ModuleName, 2, "roothash: block not found")

	// ErrInvalidRuntime is the error returned when the passed runtime is invalid.
	ErrInvalidRuntime = errors.New(ModuleName, 3, "roothash: invalid runtime")

	// ErrNoExecutorPool is the error returned when there is no executor pool.
	ErrNoExecutorPool = errors.New(ModuleName, 4, "roothash: no executor pool")

	// ErrRuntimeSuspended is the error returned when the passed runtime is suspended.
	ErrRuntimeSuspended = errors.New(ModuleName, 5, "roothash: runtime is suspended")

	// ErrProposerTimeoutNotAllowed is the error returned when proposer timeout is not allowed.
	ErrProposerTimeoutNotAllowed = errors.New(ModuleName, 6, "roothash: proposer timeout not allowed")

	// MethodExecutorCommit is the method name for executor commit submission.
	MethodExecutorCommit = transaction.NewMethodName(ModuleName, "ExecutorCommit", ExecutorCommit{})

	// MethodExecutorProposerTimeout is the method name for executor.
	MethodExecutorProposerTimeout = transaction.NewMethodName(ModuleName, "ExecutorProposerTimeout", ExecutorProposerTimeoutRequest{})

	// Methods is a list of all methods supported by the roothash backend.
	Methods = []transaction.MethodName{
View Source
var DefaultGasCosts = transaction.Costs{
	GasOpComputeCommit:   1000,
	GasOpProposerTimeout: 1000,

DefaultGasCosts are the "default" gas costs for operations.


func NewExecutorCommitTx

func NewExecutorCommitTx(nonce uint64, fee *transaction.Fee, runtimeID common.Namespace, commits []commitment.ExecutorCommitment) *transaction.Transaction

NewExecutorCommitTx creates a new executor commit transaction.

func NewRequestProposerTimeoutTx added in v0.2010.0

func NewRequestProposerTimeoutTx(nonce uint64, fee *transaction.Fee, runtimeID common.Namespace, round uint64) *transaction.Transaction

NewRequestProposerTimeoutTx creates a new request proposer timeout transaction.

func SanityCheckBlocks

func SanityCheckBlocks(blocks map[common.Namespace]*block.Block) error

SanityCheckBlocks examines the blocks table.


type AnnotatedBlock

type AnnotatedBlock struct {
	// Height is the underlying roothash backend's block height that
	// generated this block.
	Height int64 `json:"consensus_height"`

	// Block is the roothash block.
	Block *block.Block `json:"block"`

AnnotatedBlock is an annotated roothash block.

type Backend

type Backend interface {
	// GetGenesisBlock returns the genesis block.
	GetGenesisBlock(ctx context.Context, runtimeID common.Namespace, height int64) (*block.Block, error)

	// GetLatestBlock returns the latest block.
	// The metadata contained in this block can be further used to get
	// the latest state from the storage backend.
	GetLatestBlock(ctx context.Context, runtimeID common.Namespace, height int64) (*block.Block, error)

	// WatchBlocks returns a channel that produces a stream of
	// annotated blocks.
	// The latest block if any will get pushed to the stream immediately.
	// Subsequent blocks will be pushed into the stream as they are
	// confirmed.
	WatchBlocks(runtimeID common.Namespace) (<-chan *AnnotatedBlock, *pubsub.Subscription, error)

	// WatchEvents returns a stream of protocol events.
	WatchEvents(runtimeID common.Namespace) (<-chan *Event, *pubsub.Subscription, error)

	// TrackRuntime adds a runtime the history of which should be tracked.
	TrackRuntime(ctx context.Context, history BlockHistory) error

	// StateToGenesis returns the genesis state at specified block height.
	StateToGenesis(ctx context.Context, height int64) (*Genesis, error)

	// GetEvents returns the events at specified block height.
	GetEvents(ctx context.Context, height int64) ([]*Event, error)

	// Cleanup cleans up the roothash backend.

Backend is a root hash implementation.

type BlockHistory

type BlockHistory interface {
	// RuntimeID returns the runtime ID of the runtime this block history is for.
	RuntimeID() common.Namespace

	// Commit commits an annotated block into history.
	// Must be called in order, sorted by round.
	Commit(blk *AnnotatedBlock) error

	// ConsensusCheckpoint records the last consensus height which was processed
	// by the roothash backend.
	// This method can only be called once all roothash blocks for consensus
	// heights <= height have been committed using Commit.
	ConsensusCheckpoint(height int64) error

	// LastConsensusHeight returns the last consensus height which was seen
	// by block history.
	LastConsensusHeight() (int64, error)

	// GetBlock returns the block at a specific round.
	GetBlock(ctx context.Context, round uint64) (*block.Block, error)

	// GetLatestBlock returns the block at latest round.
	GetLatestBlock(ctx context.Context) (*block.Block, error)

BlockHistory is the root hash block history keeper interface.

All methods operate on a specific runtime.

type ConsensusParameters

type ConsensusParameters struct {
	// GasCosts are the roothash transaction gas costs.
	GasCosts transaction.Costs `json:"gas_costs,omitempty"`

	// DebugDoNotSuspendRuntimes is true iff runtimes should not be suspended
	// for lack of paying maintenance fees.
	DebugDoNotSuspendRuntimes bool `json:"debug_do_not_suspend_runtimes,omitempty"`

	// DebugBypassStake is true iff the roothash should bypass all of the staking
	// related checks and operations.
	DebugBypassStake bool `json:"debug_bypass_stake,omitempty"`

ConsensusParameters are the roothash consensus parameters.

type Event

type Event struct {
	Height int64     `json:"height,omitempty"`
	TxHash hash.Hash `json:"tx_hash,omitempty"`

	RuntimeID common.Namespace `json:"runtime_id"`

	ExecutorCommitted            *ExecutorCommittedEvent            `json:"executor_committed,omitempty"`
	ExecutionDiscrepancyDetected *ExecutionDiscrepancyDetectedEvent `json:"execution_discrepancy,omitempty"`
	FinalizedEvent               *FinalizedEvent                    `json:"finalized,omitempty"`

Event is a roothash event.

type ExecutionDiscrepancyDetectedEvent

type ExecutionDiscrepancyDetectedEvent struct {
	// Timeout signals whether the discrepancy was due to a timeout.
	Timeout bool `json:"timeout"`

ExecutionDiscrepancyDetectedEvent is an execute discrepancy detected event.

type ExecutorCommit

type ExecutorCommit struct {
	ID      common.Namespace                `json:"id"`
	Commits []commitment.ExecutorCommitment `json:"commits"`

ExecutorCommit is the argument set for the ExecutorCommit method.

type ExecutorCommittedEvent

type ExecutorCommittedEvent struct {
	// Commit is the executor commitment.
	Commit commitment.ExecutorCommitment `json:"commit"`

ExecutorCommittedEvent is an event emitted each time an executor node commits.

type ExecutorProposerTimeoutRequest added in v0.2010.0

type ExecutorProposerTimeoutRequest struct {
	ID    common.Namespace `json:"id"`
	Round uint64           `json:"round"`

ExecutorProposerTimeoutRequest is an executor proposer timeout request.

type FinalizedEvent

type FinalizedEvent struct {
	Round uint64 `json:"round"`

FinalizedEvent is a finalized event.

type Genesis

type Genesis struct {
	// Parameters are the roothash consensus parameters.
	Parameters ConsensusParameters `json:"params"`

	// RuntimeStates is the per-runtime map of genesis blocks.
	RuntimeStates map[common.Namespace]*api.RuntimeGenesis `json:"runtime_states,omitempty"`

Genesis is the roothash genesis state.

func (*Genesis) SanityCheck

func (g *Genesis) SanityCheck() error

SanityCheck does basic sanity checking on the genesis state.

type MetricsMonitorable

type MetricsMonitorable interface {
	// WatchAllBlocks returns a channel that produces a stream of blocks.
	// All blocks from all tracked runtimes will be pushed into the stream
	// immediately as they are finalized.
	WatchAllBlocks() (<-chan *block.Block, *pubsub.Subscription)

MetricsMonitorable is the interface exposed by backends capable of providing metrics data.

Source Files


Path Synopsis
Package block implements the roothash block and header.
Package block implements the roothash block and header.
Package commitment defines a roothash commitment.
Package commitment defines a roothash commitment.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL