commitment

package
v0.2202.7 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2023 License: Apache-2.0 Imports: 14 Imported by: 1

Documentation

Overview

Package commitment defines a roothash commitment.

Index

Constants

View Source 
const (
	// TimeoutNever is the timeout value that never expires.
	TimeoutNever = 0

	// LogEventDiscrepancyMajorityFailure is a log event value that dependency resoluton with majority failure.
	LogEventDiscrepancyMajorityFailure = "pool/discrepancy_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")
	ErrNodeIsScheduler        = errors.New(moduleName, 16, "roothash/commitment: node is scheduler")
	ErrMajorityFailure        = errors.New(moduleName, 17, "roothash/commitment: majority commitments indicated failure")
	ErrInvalidRound           = errors.New(moduleName, 18, "roothash/commitment: invalid round")
	ErrNoProposerCommitment   = errors.New(moduleName, 19, "roothash/commitment: no proposer commitment")
	ErrBadProposerCommitment  = errors.New(moduleName, 20, "roothash/commitment: bad proposer 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 GetTransactionScheduler added in v0.2010.0 

func GetTransactionScheduler(committee *scheduler.Committee, round uint64) (*scheduler.CommitteeNode, error)

GetTransactionScheduler returns the transaction scheduler of the provided committee based on the provided round.

Types

type ComputeResultsHeader 

type ComputeResultsHeader struct {
	Round        uint64    `json:"round"`
	PreviousHash hash.Hash `json:"previous_hash"`

	IORoot       *hash.Hash `json:"io_root,omitempty"`
	StateRoot    *hash.Hash `json:"state_root,omitempty"`
	MessagesHash *hash.Hash `json:"messages_hash,omitempty"`

	// InMessagesHash is the 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 {
	ComputeResultsHeader

	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 {
	// Runtime is the runtime descriptor this pool is collecting the
	// commitments for.
	Runtime *registry.Runtime `json:"runtime"`
	// Committee is the committee this pool is collecting the commitments for.
	Committee *scheduler.Committee `json:"committee"`
	// Round is the current protocol round.
	Round uint64 `json:"round"`
	// ExecuteCommitments are the commitments in the pool iff Committee.Kind
	// is scheduler.KindComputeExecutor.
	ExecuteCommitments map[signature.PublicKey]*ExecutorCommitment `json:"execute_commitments,omitempty"`
	// Discrepancy is a flag signalling that a discrepancy has been detected.
	Discrepancy bool `json:"discrepancy"`
	// NextTimeout is the time when the next call to TryFinalize(true) should
	// be scheduled to be executed. Zero means that no timeout is to be scheduled.
	NextTimeout int64 `json:"next_timeout"`
	// contains filtered or unexported fields
}

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

The pool is not safe for concurrent use.

func (*Pool) AddExecutorCommitment 

func (p *Pool) AddExecutorCommitment(
	ctx context.Context,
	blk *block.Block,
	nl NodeLookup,
	commit *ExecutorCommitment,
	msgValidator MessageValidator,
) error

AddExecutorCommitment verifies and adds a new executor commitment to the pool.

func (*Pool) CheckProposerTimeout added in v0.2010.0 

func (p *Pool) CheckProposerTimeout(
	ctx context.Context,
	block *block.Block,
	nl NodeLookup,
	id signature.PublicKey,
	round uint64,
) error

CheckProposerTimeout verifies executor timeout request conditions.

func (*Pool) IsTimeout 

func (p *Pool) IsTimeout(height int64) bool

IsTimeout returns true if the time is up for pool's TryFinalize to be called.

func (*Pool) ProcessCommitments added in v0.2100.0 

func (p *Pool) ProcessCommitments(didTimeout bool) (OpenCommitment, error)

ProcessCommitments performs a single round of commitment checks. If there are enough commitments in the pool, it performs discrepancy detection or resolution.

func (*Pool) ResetCommitments 

func (p *Pool) ResetCommitments(round uint64)

ResetCommitments resets the commitments in the pool, clears the discrepancy flag and the next timeout height.

func (*Pool) TryFinalize 

func (p *Pool) TryFinalize(
	height int64,
	roundTimeout int64,
	didTimeout bool,
	isTimeoutAuthoritative bool,
) (OpenCommitment, error)

TryFinalize attempts to finalize the commitments by performing discrepancy detection and discrepancy resolution, based on the state of the pool. It may request the caller to schedule timeouts by setting NextTimeout appropriately.

If a timeout occurs and isTimeoutAuthoritative is false, the internal discrepancy flag will not be changed but the method will still return the ErrDiscrepancyDetected error.

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.

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.