commitment

package
v0.2403.1 Latest Latest
Warning

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

 Go to latest Published: Nov 29, 2024 License: Apache-2.0 Imports: 16 Imported by: 1

Documentation

Overview

Package commitment defines a roothash commitment.

Index

Constants

View Source 
const LogEventDiscrepancyMajorityFailure = "pool/discrepancy_majority_failure"

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

Variables

View Source 
var (
	// ExecutorSignatureContext is the signature context used to sign executor
	// worker commitments.
	ExecutorSignatureContext = signature.NewContext(
		"oasis-core/roothash: executor commitment",
		signature.WithChainSeparation(),
		signature.WithDynamicSuffix(" for runtime ", common.NamespaceHexSize),
	)

	// ComputeResultsHeaderSignatureContext is the signature context used to
	// sign compute results headers with RAK.
	ComputeResultsHeaderSignatureContext = signature.NewContext("oasis-core/roothash: compute results header")
)
View Source 
var (
	ErrNoRuntime              = errors.New(moduleName, 1, "roothash/commitment: no runtime configured")
	ErrNoCommittee            = errors.New(moduleName, 2, "roothash/commitment: no committee configured")
	ErrInvalidCommitteeKind   = errors.New(moduleName, 3, "roothash/commitment: invalid committee kind")
	ErrRakSigInvalid          = errors.New(moduleName, 4, "roothash/commitment: batch RAK signature invalid")
	ErrNotInCommittee         = errors.New(moduleName, 5, "roothash/commitment: node not part of committee")
	ErrAlreadyCommitted       = errors.New(moduleName, 6, "roothash/commitment: node already sent commitment")
	ErrNotBasedOnCorrectBlock = errors.New(moduleName, 7, "roothash/commitment: submitted commitment is not based on correct block")
	ErrDiscrepancyDetected    = errors.New(moduleName, 8, "roothash/commitment: discrepancy detected")
	ErrStillWaiting           = errors.New(moduleName, 9, "roothash/commitment: still waiting for commits")
	ErrInsufficientVotes      = errors.New(moduleName, 10, "roothash/commitment: insufficient votes to finalize discrepancy resolution round")
	ErrBadExecutorCommitment  = errors.New(moduleName, 11, "roothash/commitment: bad executor commitment")
	// Error code 12 is reserved for future use.
	ErrInvalidMessages = p2pError.Permanent(errors.New(moduleName, 13, "roothash/commitment: invalid messages"))
	// Error code 14 is reserved for future use.
	ErrTimeoutNotCorrectRound = errors.New(moduleName, 15, "roothash/commitment: timeout not for correct round")
	ErrInvalidRound           = errors.New(moduleName, 16, "roothash/commitment: invalid round")
	ErrNoSchedulerCommitment  = errors.New(moduleName, 17, "roothash/commitment: no scheduler commitment")
	ErrBadSchedulerCommitment = errors.New(moduleName, 18, "roothash/commitment: bad scheduler commitment")
)

nolint: revive

View Source 
var ProposalSignatureContext = signature.NewContext(
	"oasis-core/roothash: proposal",
	signature.WithChainSeparation(),
	signature.WithDynamicSuffix(" for runtime ", common.NamespaceHexSize),
)

ProposalSignatureContext is the context used for signing propose batch dispatch messages.

Functions

func VerifyExecutorCommitment added in v0.2300.0 

func VerifyExecutorCommitment(
	ctx context.Context,
	blk *block.Block,
	rt *registry.Runtime,
	epoch beacon.EpochTime,
	commit *ExecutorCommitment,
	msgValidator MessageValidator,
	nl NodeLookup,
) error

VerifyExecutorCommitment verifies the given executor commitment.

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.

func (*ComputeResultsHeader) EncodedHash 

func (h *ComputeResultsHeader) EncodedHash() hash.Hash

EncodedHash returns the encoded cryptographic hash of the header.

func (*ComputeResultsHeader) IsParentOf 

func (h *ComputeResultsHeader) IsParentOf(child *block.Header) bool

IsParentOf returns true iff the header is the parent of a child header.

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.

func (*ExecutorCommitment) IsIndicatingFailure added in v0.2200.0 

func (c *ExecutorCommitment) IsIndicatingFailure() bool

IsIndicatingFailure returns true if this commitment indicates a failure.

func (*ExecutorCommitment) MostlyEqual added in v0.2200.0 

func (c *ExecutorCommitment) MostlyEqual(other OpenCommitment) bool

MostlyEqual returns true if the commitment is mostly equal to another specified commitment as per discrepancy detection criteria.

func (*ExecutorCommitment) Sign added in v0.2200.0 

func (c *ExecutorCommitment) Sign(signer signature.Signer, runtimeID common.Namespace) error

Sign signs the executor commitment header and sets the signature on the commitment.

func (*ExecutorCommitment) ToDDResult added in v0.2200.0 

func (c *ExecutorCommitment) ToDDResult() interface{}

ToDDResult returns a commitment-specific result after discrepancy detection.

func (*ExecutorCommitment) ToVote added in v0.2200.0 

func (c *ExecutorCommitment) ToVote() hash.Hash

ToVote returns a hash that represents a vote for this commitment as per discrepancy resolution criteria.

func (*ExecutorCommitment) ValidateBasic added in v0.2200.0 

func (c *ExecutorCommitment) ValidateBasic() error

ValidateBasic performs basic executor commitment validity checks.

func (*ExecutorCommitment) Verify added in v0.2200.0 

func (c *ExecutorCommitment) Verify(runtimeID common.Namespace) error

Verify verifies that the header signature is valid.

type ExecutorCommitmentFailure added in v0.2100.0 

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 added in v0.2200.0 

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.

func (*ExecutorCommitmentHeader) MostlyEqual added in v0.2200.0 

func (eh *ExecutorCommitmentHeader) MostlyEqual(other *ExecutorCommitmentHeader) bool

MostlyEqual compares against another executor commitment header for equality.

The RAKSignature field is not compared.

func (*ExecutorCommitmentHeader) SetFailure added in v0.2200.0 

func (eh *ExecutorCommitmentHeader) SetFailure(failure ExecutorCommitmentFailure)

SetFailure sets failure reason and clears any fields that should be clear in a failure indicating commitment.

func (*ExecutorCommitmentHeader) Sign added in v0.2200.0 

func (eh *ExecutorCommitmentHeader) Sign(signer signature.Signer, runtimeID common.Namespace) (*signature.RawSignature, error)

Sign signs the executor commitment header.

func (*ExecutorCommitmentHeader) VerifyRAK added in v0.2200.0 

func (eh *ExecutorCommitmentHeader) VerifyRAK(rak signature.PublicKey) error

VerifyRAK verifies the RAK signature.

type MessageValidator added in v0.2100.0 

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 NodeLookup 

type NodeLookup interface {
	// Node looks up a node descriptor.
	Node(ctx context.Context, id signature.PublicKey) (*node.Node, error)
}

NodeLookup is an interface for looking up registry node descriptors.

type OpenCommitment 

type OpenCommitment interface {
	// MostlyEqual returns true if the commitment is mostly equal to another
	// specified commitment as per discrepancy detection criteria.
	//
	// The caller MUST guarantee that the passed commitment is of the same
	// type.
	MostlyEqual(OpenCommitment) bool

	// IsIndicatingFailure returns true if this commitment indicates a failure.
	IsIndicatingFailure() bool

	// ToVote returns a hash that represents a vote for this commitment as
	// per discrepancy resolution criteria.
	ToVote() hash.Hash

	// ToDDResult returns a commitment-specific result after discrepancy
	// detection.
	ToDDResult() interface{}
}

OpenCommitment is a verified roothash commitment.

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.

func NewPool added in v0.2300.0 

func NewPool() *Pool

NewPool creates a new pool without any commitments and with .

func (*Pool) AddVerifiedExecutorCommitment added in v0.2300.0 

func (p *Pool) AddVerifiedExecutorCommitment(c *scheduler.Committee, ec *ExecutorCommitment) error

AddVerifiedExecutorCommitment adds a verified executor commitment to the pool.

func (*Pool) ProcessCommitments added in v0.2100.0 

func (p *Pool) ProcessCommitments(c *scheduler.Committee, allowedStragglers uint16, timeout bool) (*SchedulerCommitment, error)

ProcessCommitments performs discrepancy detection or resolution.

type Proposal added in v0.2200.0 

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.

func (*Proposal) Sign added in v0.2200.0 

func (p *Proposal) Sign(signer signature.Signer, runtimeID common.Namespace) error

Sign signs the proposal header and sets the signature on the proposal.

func (*Proposal) Verify added in v0.2200.0 

func (p *Proposal) Verify(runtimeID common.Namespace) error

Verify verifies that the header signature is valid.

type ProposalHeader added in v0.2200.0 

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.

func (*ProposalHeader) Equal added in v0.2200.0 

func (ph *ProposalHeader) Equal(other *ProposalHeader) bool

Equal compares against another proposal header for equality.

func (*ProposalHeader) Sign added in v0.2200.0 

func (ph *ProposalHeader) Sign(signer signature.Signer, runtimeID common.Namespace) (*signature.RawSignature, error)

Sign signs the proposal header.

type SchedulerCommitment added in v0.2300.0 

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.

func (*SchedulerCommitment) Add added in v0.2300.0 

func (sc *SchedulerCommitment) Add(ec *ExecutorCommitment) error

Add converts the provided executor commitment into a vote and adds it to the votes map.

It returns an error if the node has already submitted a vote.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.