commitment

package
v0.2010.0 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2020 License: Apache-2.0 Imports: 16 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
)

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())

	// 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")
	ErrBadExecutorCommits     = errors.New(moduleName, 11, "roothash/commitment: bad executor commitments")
	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")
)
View Source 
var ProposedBatchSignatureContext = signature.NewContext("oasis-core/roothash: proposed batch", signature.WithChainSeparation())

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"`
	StorageSignatures []signature.Signature  `json:"storage_signatures"`
	RakSig            signature.RawSignature `json:"rak_sig"`

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

ComputeBody holds the data signed in a compute worker commitment.

func (*ComputeBody) RootsForStorageReceipt 

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

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

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(header block.Header) bool

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"`
	StateRoot    hash.Hash        `json:"state_root"`
	Messages     []*block.Message `json:"messages"`
}

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, 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() (*OpenExecutorCommitment, error)

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

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

	// 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) 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"`
	// 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,
) error

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

func (*Pool) CheckEnoughCommitments 

func (p *Pool) CheckEnoughCommitments(didTimeout bool) error

CheckEnoughCommitments checks if there are enough commitments in the pool to be able to perform discrepancy detection.

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) DetectDiscrepancy 

func (p *Pool) DetectDiscrepancy() (OpenCommitment, error)

DetectDiscrepancy performs discrepancy detection on the current commitments in the pool.

The caller must verify that there are enough commitments in the pool.

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) ResetCommitments 

func (p *Pool) ResetCommitments()

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

func (*Pool) ResolveDiscrepancy 

func (p *Pool) ResolveDiscrepancy() (OpenCommitment, error)

ResolveDiscrepancy performs discrepancy resolution on the current commitments in the pool.

The caller must verify that there are enough commitments in the pool.

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

	// VerifyTxnSchedulerSignature verifies that the given signatures come from
	// the transaction scheduler at provided round.
	VerifyTxnSchedulerSignature(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, tsbd *ProposedBatch) (*SignedProposedBatch, error)

SignProposedBatch signs a ProposedBatch struct using the given signer.

func (*SignedProposedBatch) Open added in v0.2010.0 

func (s *SignedProposedBatch) Open(tsbd *ProposedBatch) 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.