api

Documentation

Overview

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

Index

• Constants
• type AnnotatedBlock
• type ConsensusParameterChanges
• type ConsensusParameters
• type EquivocationExecutorEvidence
• type EquivocationProposalEvidence
• type Event
• type Evidence
• type EvidenceKind
• type ExecutionDiscrepancyDetectedEvent
• type ExecutorCommit
• type ExecutorCommittedEvent
• type FinalizedEvent
• type Genesis
• type GenesisRuntimeState
• type InMessageQueueRequest
• type InMsgProcessedEvent
• type LivenessStatistics
• type MessageEvent
• type RoundResults
• type RoundRoots
• type RuntimeIDAttribute
• type RuntimeRequest
• type RuntimeState
• type SubmitMsg

Constants

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

	// RoundInvalid is a special round number that refers to an invalid round.
	RoundInvalid uint64 = math.MaxUint64
	// TimeoutNever is the timeout value that never expires.
	TimeoutNever int64 = 0

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

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"

	// GasOpEvidence is the gas operation identifier for evidence submission transaction cost.
	GasOpEvidence transaction.Op = "evidence"

	// GasOpSubmitMsg is the gas operation identifier for message submission transaction cost.
	GasOpSubmitMsg transaction.Op = "submit_msg"
)

const (
	// EvidenceKindEquivocation is the evidence kind for equivocation.
	EvidenceKindEquivocation = 1
)

const RoundLatest = RoundInvalid

RoundLatest is a special round number always referring to the latest round.

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 ConsensusParameterChanges

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

	// MaxRuntimeMessages is the new maximum number of emitted runtime messages.
	MaxRuntimeMessages *uint32 `json:"max_runtime_messages"`

	// MaxInRuntimeMessages is the new maximum number of incoming queued runtime messages.
	MaxInRuntimeMessages *uint32 `json:"max_in_runtime_messages"`

	// MaxEvidenceAge is the new maximum evidence age.
	MaxEvidenceAge *uint64 `json:"max_evidence_age"`

	// MaxPastRootsStored is the new maximum number of past runtime state and I/O
	// roots that are stored in the consensus state.
	MaxPastRootsStored *uint64 `json:"max_past_roots_stored,omitempty"`
}

ConsensusParameterChanges are allowed roothash consensus parameter changes.

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

	// MaxRuntimeMessages is the maximum number of allowed messages that can be emitted by a runtime
	// in a single round.
	MaxRuntimeMessages uint32 `json:"max_runtime_messages"`

	// MaxInRuntimeMessages is the maximum number of allowed incoming messages that can be queued.
	MaxInRuntimeMessages uint32 `json:"max_in_runtime_messages"`

	// MaxEvidenceAge is the maximum age of submitted evidence in the number of rounds.
	MaxEvidenceAge uint64 `json:"max_evidence_age"`

	// MaxPastRootsStored is the maximum number of past runtime state and I/O
	// roots that are stored in the consensus state.
	MaxPastRootsStored uint64 `json:"max_past_roots_stored,omitempty"`
}

ConsensusParameters are the roothash consensus parameters.

type EquivocationExecutorEvidence

type EquivocationExecutorEvidence struct {
	CommitA commitment.ExecutorCommitment `json:"commit_a"`
	CommitB commitment.ExecutorCommitment `json:"commit_b"`
}

EquivocationExecutorEvidence is evidence of executor commitment equivocation.

type EquivocationProposalEvidence

type EquivocationProposalEvidence struct {
	ProposalA commitment.Proposal `json:"prop_a"`
	ProposalB commitment.Proposal `json:"prop_b"`
}

EquivocationProposalEvidence is evidence of executor proposed batch equivocation.

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"`
	Finalized                    *FinalizedEvent                    `json:"finalized,omitempty"`
	InMsgProcessed               *InMsgProcessedEvent               `json:"in_msg_processed,omitempty"`
}

Event is a roothash event.

type Evidence

type Evidence struct {
	ID common.Namespace `json:"id"`

	EquivocationExecutor *EquivocationExecutorEvidence `json:"equivocation_executor,omitempty"`
	EquivocationProposal *EquivocationProposalEvidence `json:"equivocation_prop,omitempty"`
}

Evidence is an evidence of node misbehaviour.

type EvidenceKind

type EvidenceKind uint8

EvidenceKind is the evidence kind.

type ExecutionDiscrepancyDetectedEvent

type ExecutionDiscrepancyDetectedEvent struct {
	// Rank is the rank of the transaction scheduler.
	Rank uint64 `json:"rank"`
	// 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 is the round that was finalized.
	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 are the runtime states at genesis.
	RuntimeStates map[common.Namespace]*GenesisRuntimeState `json:"runtime_states,omitempty"`
}

Genesis is the roothash genesis state.

type GenesisRuntimeState

type GenesisRuntimeState struct {
	registry.RuntimeGenesis

	// MessageResults are the message results emitted at the last processed round.
	MessageResults []*MessageEvent `json:"message_results,omitempty"`
}

GenesisRuntimeState contains state for runtimes that are restored in a genesis block.

type InMessageQueueRequest

type InMessageQueueRequest struct {
	RuntimeID common.Namespace `json:"runtime_id"`
	Height    int64            `json:"height"`

	Offset uint64 `json:"offset,omitempty"`
	Limit  uint32 `json:"limit,omitempty"`
}

InMessageQueueRequest is a request for queued incoming messages.

type InMsgProcessedEvent

type InMsgProcessedEvent struct {
	// ID is the unique incoming message identifier.
	ID uint64 `json:"id"`
	// Round is the round where the incoming message was processed.
	Round uint64 `json:"round"`
	// Caller is the incoming message submitter address.
	Caller staking.Address `json:"caller"`
	// Tag is an optional tag provided by the caller.
	Tag uint64 `json:"tag,omitempty"`
}

InMsgProcessedEvent is an event of a specific incoming message being processed.

In order to see details one needs to query the runtime at the specified round.

type LivenessStatistics

type LivenessStatistics struct {
	// TotalRounds is the total number of rounds in the last epoch, excluding any rounds generated
	// by the roothash service itself.
	TotalRounds uint64 `json:"total_rounds"`

	// LiveRounds is a list of counters, specified in committee order (e.g. counter at index i has
	// the value for node i in the committee).
	LiveRounds []uint64 `json:"good_rounds"`

	// FinalizedProposals is a list that records the number of finalized rounds when a node
	// acted as a proposer.
	//
	// The list is ordered according to the committee arrangement (i.e., the counter at index i
	// holds the value for the node at index i in the committee).
	FinalizedProposals []uint64 `json:"finalized_proposals"`

	// MissedProposals is a list that records the number of failed rounds when a node
	// acted as a proposer.
	//
	// The list is ordered according to the committee arrangement (i.e., the counter at index i
	// holds the value for the node at index i in the committee).
	MissedProposals []uint64 `json:"missed_proposals"`
}

LivenessStatistics has the per-epoch liveness statistics for nodes.

type MessageEvent

type MessageEvent struct {
	Module string `json:"module,omitempty"`
	Code   uint32 `json:"code,omitempty"`
	Index  uint32 `json:"index,omitempty"`

	// Result contains CBOR-encoded message execution result for successfully executed messages.
	Result cbor.RawMessage `json:"result,omitempty"`
}

MessageEvent is a runtime message processed event.

type RoundResults

type RoundResults struct {
	// Messages are the results of executing emitted runtime messages.
	Messages []*MessageEvent `json:"messages,omitempty"`

	// GoodComputeEntities are the public keys of compute nodes' controlling entities that
	// positively contributed to the round by replicating the computation correctly.
	GoodComputeEntities []signature.PublicKey `json:"good_compute_entities,omitempty"`
	// BadComputeEntities are the public keys of compute nodes' controlling entities that
	// negatively contributed to the round by causing discrepancies.
	BadComputeEntities []signature.PublicKey `json:"bad_compute_entities,omitempty"`
}

RoundResults contains information about how a particular round was executed by the consensus layer.

type RoundRoots

type RoundRoots struct {
	StateRoot hash.Hash
	IORoot    hash.Hash
	// contains filtered or unexported fields
}

RoundRoots holds the per-round state and I/O roots that are stored in consensus state.

type RuntimeIDAttribute

type RuntimeIDAttribute struct {
	ID common.Namespace
}

RuntimeIDAttribute is the event attribute for specifying runtime ID. ID is base64 encoded runtime ID.

type RuntimeRequest

type RuntimeRequest struct {
	RuntimeID common.Namespace `json:"runtime_id"`
	Height    int64            `json:"height"`
}

RuntimeRequest is a generic roothash get request for a specific runtime.

type RuntimeState

type RuntimeState struct {
	// Runtime is the latest per-epoch runtime descriptor.
	Runtime *registry.Runtime `json:"runtime"`
	// Suspended is a flag indicating whether the runtime is currently suspended.
	Suspended bool `json:"suspended,omitempty"`

	// GenesisBlock is the runtime's first block.
	GenesisBlock *block.Block `json:"genesis_block"`

	// LastBlock is the runtime's most recently generated block.
	LastBlock *block.Block `json:"last_block"`
	// LastBlockHeight is the height at which the runtime's most recent block was generated.
	LastBlockHeight int64 `json:"last_block_height"`

	// LastNormalRound is the runtime round which was normally processed by the runtime. This is
	// also the round that contains the message results for the last processed runtime messages.
	LastNormalRound uint64 `json:"last_normal_round"`
	// LastNormalHeight is the consensus block height corresponding to LastNormalRound.
	LastNormalHeight int64 `json:"last_normal_height"`

	// Committee is the committee the executor pool is collecting commitments for.
	Committee *scheduler.Committee `json:"committee,omitempty"`
	// CommitmentPool collects the executor commitments.
	CommitmentPool *commitment.Pool `json:"commitment_pool,omitempty"`
	// NextTimeout is the time at which the round is scheduled for forced finalization.
	NextTimeout int64 `json:"timeout,omitempty"`

	// LivenessStatistics contains the liveness statistics for the current epoch.
	LivenessStatistics *LivenessStatistics `json:"liveness_stats,omitempty"`
}

RuntimeState is the per-runtime state.

type SubmitMsg

type SubmitMsg struct {
	// ID is the destination runtime ID.
	ID common.Namespace `json:"id"`
	// Tag is an optional tag provided by the caller which is ignored and can be used to match
	// processed incoming message events later.
	Tag uint64 `json:"tag,omitempty"`
	// Fee is the fee sent into the runtime as part of the message being sent. The fee is
	// transferred before the message is processed by the runtime.
	Fee quantity.Quantity `json:"fee,omitempty"`
	// Tokens are any tokens sent into the runtime as part of the message being sent. The tokens are
	// transferred before the message is processed by the runtime.
	Tokens quantity.Quantity `json:"tokens,omitempty"`
	// Data is arbitrary runtime-dependent data.
	Data []byte `json:"data,omitempty"`
}

SubmitMsg is the argument set for the SubmitMsg method.