api

Documentation

Overview

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

Index

• Constants
• Variables
• func NewExecutorCommitTx(nonce uint64, fee *transaction.Fee, runtimeID common.Namespace, ...) *transaction.Transaction
• func NewMergeCommitTx(nonce uint64, fee *transaction.Fee, runtimeID common.Namespace, ...) *transaction.Transaction
• func SanityCheckBlocks(blocks map[common.Namespace]*block.Block) error
• type AnnotatedBlock
• type Backend
• type BlockHistory
• type ConsensusParameters
• type Event
• type ExecutionDiscrepancyDetectedEvent
• type ExecutorCommit
• type ExecutorCommittedEvent
• type FinalizedEvent
• type Genesis
  • func (g *Genesis) SanityCheck() error
• type MergeCommit
• type MergeCommittedEvent
• type MergeDiscrepancyDetectedEvent
• type MetricsMonitorable

Constants

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"
	// LogEventMergeDiscrepancyDetected is a log event value that signals
	// a merge discrepancy has been detected.
	LogEventMergeDiscrepancyDetected = "roothash/merge_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 singals a roothash runtime reindexing
	// was run.
	LogEventHistoryReindexing = "roothash/history_reindexing"
)

const (
	// GasOpComputeCommit is the gas operation identifier for compute commits.
	GasOpComputeCommit transaction.Op = "compute_commit"
	// GasOpMergeCommit is the gas operation identifier for merge commits.
	GasOpMergeCommit transaction.Op = "merge_commit"
)

Variables

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")

	// ErrNoRound is the error returned when no round is in progress.
	ErrNoRound = errors.New(ModuleName, 4, "roothash: no round is in progress")

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

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

	// Methods is a list of all methods supported by the roothash backend.
	Methods = []transaction.MethodName{
		MethodExecutorCommit,
		MethodMergeCommit,
	}
)

var DefaultGasCosts = transaction.Costs{
	GasOpComputeCommit: 1000,
	GasOpMergeCommit:   1000,
}

DefaultGasCosts are the "default" gas costs for operations.

Functions

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 NewMergeCommitTx

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

NewMergeCommitTx creates a new executor commit transaction.

func SanityCheckBlocks

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

SanityCheckBlocks examines the blocks table.

Types

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.
	Cleanup()
}

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"`
	MergeCommitted               *MergeCommittedEvent               `json:"merge_committed,omitempty"`
	ExecutionDiscrepancyDetected *ExecutionDiscrepancyDetectedEvent `json:"execution_discrepancy,omitempty"`
	MergeDiscrepancyDetected     *MergeDiscrepancyDetectedEvent     `json:"merge_discrepancy,omitempty"`
	FinalizedEvent               *FinalizedEvent                    `json:"finalized,omitempty"`
}

Event is a roothash event.

type ExecutionDiscrepancyDetectedEvent

type ExecutionDiscrepancyDetectedEvent struct {
	// CommitteeID is the identifier of the executor committee where a
	// discrepancy has been detected.
	CommitteeID hash.Hash `json:"cid"`

	// 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 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 MergeCommit

type MergeCommit struct {
	ID      common.Namespace             `json:"id"`
	Commits []commitment.MergeCommitment `json:"commits"`
}

MergeCommit is the argument set for the MergeCommit method.

type MergeCommittedEvent

type MergeCommittedEvent struct {
	// Commit is the merge commitment.
	Commit commitment.MergeCommitment `json:"commit"`
}

MergeCommittedEvent is an event emitted each time a merge node commits.

type MergeDiscrepancyDetectedEvent

type MergeDiscrepancyDetectedEvent struct {
}

MergeDiscrepancyDetectedEvent is a merge discrepancy detected event.

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.