commitment

package
v0.2103.6 Latest Latest
Warning

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

 Go to latest Published: Nov 15, 2021 License: Apache-2.0 Imports: 17 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")
	ErrTxnSchedSigInvalid     = p2pError.Permanent(errors.New(moduleName, 12, "roothash/commitment: txn scheduler signature invalid"))
	ErrInvalidMessages        = p2pError.Permanent(errors.New(moduleName, 13, "roothash/commitment: invalid messages"))
	ErrBadStorageReceipts     = errors.New(moduleName, 14, "roothash/commitment: bad storage receipts")
	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")
)
View Source 
var ProposedBatchSignatureContext = signature.NewContext(
	"oasis-core/roothash: proposed batch",
	signature.WithChainSeparation(),
	signature.WithDynamicSuffix(" for runtime ", common.NamespaceHexSize),
)

ProposedBatchSignatureContext 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 ComputeBody 

type ComputeBody struct {
	Header  ComputeResultsHeader      `json:"header"`
	Failure ExecutorCommitmentFailure `json:"failure,omitempty"`

	TxnSchedSig      signature.Signature   `json:"txn_sched_sig"`
	InputRoot        hash.Hash             `json:"input_root"`
	InputStorageSigs []signature.Signature `json:"input_storage_sigs"`

	StorageSignatures []signature.Signature   `json:"storage_signatures,omitempty"`
	RakSig            *signature.RawSignature `json:"rak_sig,omitempty"`
	Messages          []message.Message       `json:"messages,omitempty"`
}

ComputeBody holds the data signed in a compute worker commitment.

func (*ComputeBody) RootTypesForStorageReceipt added in v0.2100.0 

func (m *ComputeBody) RootTypesForStorageReceipt() []storage.RootType

RootTypesForStorageReceipt gets the storage root types that must be part of a storage receipt.

func (*ComputeBody) RootsForStorageReceipt 

func (m *ComputeBody) RootsForStorageReceipt() []hash.Hash

RootsForStorageReceipt gets the merkle roots that must be part of a storage receipt.

func (*ComputeBody) SetFailure added in v0.2100.0 

func (m *ComputeBody) SetFailure(failure ExecutorCommitmentFailure)

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

func (*ComputeBody) ValidateBasic added in v0.2100.0 

func (m *ComputeBody) ValidateBasic() error

ValidateBasic performs basic executor commitment validity checks.

func (*ComputeBody) VerifyStorageReceipt 

func (m *ComputeBody) VerifyStorageReceipt(ns common.Namespace, receipt *storage.ReceiptBody) error

VerifyStorageReceipt validates that the provided storage receipt matches the header.

func (*ComputeBody) VerifyStorageReceiptSignatures 

func (m *ComputeBody) VerifyStorageReceiptSignatures(ns common.Namespace) error

VerifyStorageReceiptSignatures validates that the storage receipt signatures match the signatures for the current merkle roots.

Note: Ensuring that the signature is signed by the keypair(s) that are expected is the responsibility of the caller.

func (*ComputeBody) VerifyTxnSchedSignature 

func (m *ComputeBody) VerifyTxnSchedSignature(runtimeID common.Namespace, header block.Header) (bool, error)

VerifyTxnSchedSignature rebuilds the batch dispatch message from the data in the ComputeBody struct and verifies if the txn scheduler signature matches what we're seeing.

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

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 {
	signature.Signed
}

ExecutorCommitment is a roothash commitment from an executor worker.

The signed content is ComputeBody.

func SignExecutorCommitment 

func SignExecutorCommitment(
	signer signature.Signer,
	runtimeID common.Namespace,
	body *ComputeBody,
) (*ExecutorCommitment, error)

SignExecutorCommitment serializes the message and signs the commitment.

func (*ExecutorCommitment) Equal 

func (c *ExecutorCommitment) Equal(cmp *ExecutorCommitment) bool

Equal compares vs another ExecutorCommitment for equality.

func (*ExecutorCommitment) Open 

func (c *ExecutorCommitment) Open(runtimeID common.Namespace) (*OpenExecutorCommitment, error)

Open validates the executor commitment signature, and de-serializes the message. This does not validate the RAK signature.

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
	// FailureStorageUnavailable indicates that batch processing failed due to
	// storage being unavailable.
	FailureStorageUnavailable ExecutorCommitmentFailure = 2
)

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 OpenExecutorCommitment 

type OpenExecutorCommitment struct {
	ExecutorCommitment

	Body *ComputeBody `json:"-"` // No need to serialize as it can be reconstructed.
}

OpenExecutorCommitment is an executor commitment that has been verified and deserialized.

The open commitment still contains the original signed commitment.

func (OpenExecutorCommitment) IsIndicatingFailure added in v0.2100.0 

func (c OpenExecutorCommitment) IsIndicatingFailure() bool

IsIndicatingFailure returns true if this commitment indicates a failure.

func (OpenExecutorCommitment) MostlyEqual 

func (c OpenExecutorCommitment) MostlyEqual(other OpenCommitment) bool

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

func (OpenExecutorCommitment) ToDDResult 

func (c OpenExecutorCommitment) ToDDResult() interface{}

ToDDResult returns a commitment-specific result after discrepancy detection.

func (OpenExecutorCommitment) ToVote 

func (c OpenExecutorCommitment) ToVote() hash.Hash

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

func (*OpenExecutorCommitment) UnmarshalCBOR 

func (c *OpenExecutorCommitment) UnmarshalCBOR(data []byte) error

UnmarshalCBOR handles CBOR unmarshalling from passed data.

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]OpenExecutorCommitment `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,
	sv SignatureVerifier,
	nl NodeLookup,
	commitment *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,
	sv SignatureVerifier,
	nl NodeLookup,
	id signature.PublicKey,
	round uint64,
) error

CheckProposerTimeout verifies executor timeout request conditions.

func (*Pool) GetExecutorCommitments 

func (p *Pool) GetExecutorCommitments() (result []ExecutorCommitment)

GetExecutorCommitments returns a list of executor commitments in the pool.

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

type ProposedBatch struct {
	// IORoot is the I/O root containing the inputs (transactions) that
	// the executor node should use.
	IORoot hash.Hash `json:"io_root"`

	// StorageSignatures are the storage receipt signatures for the I/O root.
	StorageSignatures []signature.Signature `json:"storage_signatures"`

	// Header is the block header on which the batch should be based.
	Header block.Header `json:"header"`
}

ProposedBatch is the message sent from the transaction scheduler to executor workers after a batch is ready to be executed.

Don't forget to bump CommitteeProtocol version in go/common/version if you change anything in this struct.

type SignatureVerifier 

type SignatureVerifier interface {
	// VerifyCommitteeSignatures verifies that the given signatures come from
	// the current committee members of the given kind.
	VerifyCommitteeSignatures(kind scheduler.CommitteeKind, sigs []signature.Signature) error

	// VerifyTxnSchedulerSigner verifies that the given signature comes from
	// the transaction scheduler at provided round.
	VerifyTxnSchedulerSigner(sig signature.Signature, round uint64) error
}

SignatureVerifier is an interface for verifying storage and transaction scheduler signatures against the active committees.

type SignedProposedBatch added in v0.2010.0 

type SignedProposedBatch struct {
	signature.Signed
}

SignedProposedBatch is a ProposedBatch, signed by the transaction scheduler.

func SignProposedBatch added in v0.2010.0 

func SignProposedBatch(signer signature.Signer, runtimeID common.Namespace, tsbd *ProposedBatch) (*SignedProposedBatch, error)

SignProposedBatch signs a ProposedBatch struct using the given signer.

func (*SignedProposedBatch) Equal added in v0.2100.0 

func (s *SignedProposedBatch) Equal(cmp *SignedProposedBatch) bool

Equal compares vs another SignedProposedBatch for equality.

func (*SignedProposedBatch) Open added in v0.2010.0 

func (s *SignedProposedBatch) Open(tsbd *ProposedBatch, runtimeID common.Namespace) error

Open first verifies the blob signature and then unmarshals the blob.

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.