commitment

Documentation

Overview

Package commitment defines a roothash commitment.

Index

• Constants
• type ComputeResultsHeader
• type ExecutorCommitment
• type ExecutorCommitmentFailure
• type ExecutorCommitmentHeader
• type MessageValidator
• type Pool
• type Proposal
• type ProposalHeader
• type SchedulerCommitment

Constants

const LogEventDiscrepancyMajorityFailure = "pool/discrepancy_majority_failure"

LogEventDiscrepancyMajorityFailure is a log event value that dependency resolution with majority failure.

Types

type ComputeResultsHeader

type ComputeResultsHeader struct {
	// Round is the round number.
	Round uint64 `json:"round"`

	// PreviousHash is the hash of the previous block header this batch was computed against.
	PreviousHash hash.Hash `json:"previous_hash"`

	// IORoot is the I/O merkle root.
	IORoot *hash.Hash `json:"io_root,omitempty"`
	// StateRoot is the root hash of the state after computing this batch.
	StateRoot *hash.Hash `json:"state_root,omitempty"`
	// MessagesHash is the hash of messages sent from this batch.
	MessagesHash *hash.Hash `json:"messages_hash,omitempty"`

	// InMessagesHash is hash of processed incoming messages.
	InMessagesHash *hash.Hash `json:"in_msgs_hash,omitempty"`
	// InMessagesCount is the number of processed incoming messages.
	InMessagesCount uint32 `json:"in_msgs_count,omitempty"`
}

ComputeResultsHeader is the header of a computed batch output by a runtime. This header is a compressed representation (e.g., hashes instead of full content) of the actual results.

These headers are signed by RAK inside the runtime and included in executor commitments.

Keep the roothash RAK validation in sync with changes to this structure.

type ExecutorCommitment

type ExecutorCommitment struct {
	// NodeID is the public key of the node that generated this commitment.
	NodeID signature.PublicKey `json:"node_id"`

	// Header is the commitment header.
	Header ExecutorCommitmentHeader `json:"header"`

	// Signature is the commitment header signature.
	Signature signature.RawSignature `json:"sig"`

	// Messages are the messages emitted by the runtime.
	//
	// This field is only present in case this commitment belongs to the proposer. In case of
	// the commitment being submitted as equivocation evidence, this field should be omitted.
	Messages []message.Message `json:"messages,omitempty"`
}

ExecutorCommitment is a commitment to results of processing a proposed runtime block.

type ExecutorCommitmentFailure

type ExecutorCommitmentFailure uint8

ExecutorCommitmentFailure is the executor commitment failure reason.

const (
	// FailureNone indicates that no failure has occurred.
	FailureNone ExecutorCommitmentFailure = 0
	// FailureUnknown indicates a generic failure.
	FailureUnknown ExecutorCommitmentFailure = 1
	// FailureStateUnavailable indicates that batch processing failed due to the state being
	// unavailable.
	FailureStateUnavailable ExecutorCommitmentFailure = 2
)

type ExecutorCommitmentHeader

type ExecutorCommitmentHeader struct {
	// SchedulerID is the public key of the node that scheduled transactions
	// and prepared the proposal.
	SchedulerID signature.PublicKey `json:"scheduler_id"`

	// Header is the compute results header.
	Header ComputeResultsHeader `json:"header"`

	// Failure is the executor commitment failure reason.
	Failure ExecutorCommitmentFailure `json:"failure,omitempty"`

	RAKSignature *signature.RawSignature `json:"rak_sig,omitempty"`
}

ExecutorCommitmentHeader is the header of an executor commitment.

type MessageValidator

type MessageValidator func(msgs []message.Message) error

MessageValidator is an arbitrary function that validates messages for validity. It can be used for gas accounting.

type Pool

type Pool struct {
	// HighestRank is the rank of the highest-ranked scheduler among those who have submitted
	// a commitment for their own proposal. The maximum value indicates that no scheduler
	// has submitted a commitment.
	HighestRank uint64 `json:"highest_rank,omitempty"`
	// SchedulerCommitments is a map that groups scheduler commitments and worker votes
	// by the scheduler's rank.
	SchedulerCommitments map[uint64]*SchedulerCommitment `json:"scheduler_commitments,omitempty"`
	// Discrepancy is a flag signalling that a discrepancy has been detected.
	Discrepancy bool `json:"discrepancy,omitempty"`
}

Pool is a serializable pool of scheduler commitments that can be used to perform discrepancy detection and resolution.

The pool is not safe for concurrent use.

type Proposal

type Proposal struct {
	// NodeID is the public key of the node that generated this proposal.
	NodeID signature.PublicKey `json:"node_id"`

	// Header is the proposal header.
	Header ProposalHeader `json:"header"`

	// Signature is the proposal header signature.
	Signature signature.RawSignature `json:"sig"`

	// Batch is an ordered list of all transaction hashes that should be in a batch. In case of
	// the proposal being submitted as equivocation evidence, this field should be omitted.
	Batch []hash.Hash `json:"batch,omitempty"`
}

Proposal is a batch proposal.

type ProposalHeader

type ProposalHeader struct {
	// Round is the proposed round number.
	Round uint64 `json:"round"`

	// PreviousHash is the hash of the block header on which the batch should be based.
	PreviousHash hash.Hash `json:"previous_hash"`

	// BatchHash is the hash of the content of the batch.
	BatchHash hash.Hash `json:"batch_hash"`
}

ProposalHeader is the header of the batch proposal.

type SchedulerCommitment

type SchedulerCommitment struct {
	// Commitment is a verified scheduler's Commitment for which votes are being collected.
	Commitment *ExecutorCommitment `json:"commitment,omitempty"`

	// Votes is a map that collects Votes from nodes in the form of commitment hashes.
	//
	// A nil vote indicates a failure.
	Votes map[signature.PublicKey]*hash.Hash `json:"votes,omitempty"`
}

SchedulerCommitment is a structure for storing scheduler commitment and its votes.