commitment

package
v0.20.9 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2020 License: Apache-2.0 Imports: 16 Imported by: 1

Documentation

Overview

Package commitment defines a roothash commitment.

Package commitment defines a roothash commitment.

Index

Constants

This section is empty.

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")
	ErrInvalidCommitteeID     = errors.New(moduleName, 12, "roothash/commitment: invalid committee ID")
	ErrTxnSchedSigInvalid     = p2pError.Permanent(errors.New(moduleName, 13, "roothash/commitment: txn scheduler signature invalid"))
	ErrInvalidMessages        = p2pError.Permanent(errors.New(moduleName, 14, "roothash/commitment: invalid messages"))
	ErrBadStorageReceipts     = errors.New(moduleName, 15, "roothash/commitment: bad storage receipts")
)
View Source 
var MergeSignatureContext = signature.NewContext("oasis-core/roothash: merge commitment", signature.WithChainSeparation())

MergeSignatureContext is the signature context used to sign merge worker commitments.

View Source 
var TxnSchedulerBatchSigCtx = signature.NewContext("oasis-core/roothash: tx batch", signature.WithChainSeparation())

TxnSchedulerBatchSigCtx is the context used for signing transaction scheduler batch dispatch messages.

Functions

This section is empty.

Types

type ComputeBody 

type ComputeBody struct {
	CommitteeID       hash.Hash              `json:"cid"`
	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, round uint64, receipt *storage.ReceiptBody) error

VerifyStorageReceipt validates that the provided storage receipt matches the header.

func (*ComputeBody) VerifyStorageReceiptSignatures 

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

VerifyStorageReceiptSignature 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 {
	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 MergeBody 

type MergeBody struct {
	ExecutorCommits []ExecutorCommitment `json:"commits"`
	Header          block.Header         `json:"header"`
}

type MergeCommitment 

type MergeCommitment struct {
	signature.Signed
}

MergeCommitment is a roothash commitment from a merge worker.

The signed content is MergeBody.

func SignMergeCommitment 

func SignMergeCommitment(signer signature.Signer, body *MergeBody) (*MergeCommitment, error)

SignMergeCommitment serializes the message and signs the commitment.

func (*MergeCommitment) Equal 

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

Equal compares vs another MergeCommitment for equality.

func (*MergeCommitment) Open 

func (c *MergeCommitment) Open() (*OpenMergeCommitment, error)

Open validates the merge commitment signature, and de-serializes the body.

type MultiPool 

type MultiPool struct {
	Committees map[hash.Hash]*Pool `json:"committees"`
}

MultiPool contains pools for multiple committees and routes operations to multiple committees based on commitments' committee IDs.

func (*MultiPool) AddExecutorCommitment 

func (m *MultiPool) AddExecutorCommitment(
	ctx context.Context,
	blk *block.Block,
	sv SignatureVerifier,
	nl NodeLookup,
	commitment *ExecutorCommitment,
) (*Pool, error)

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

func (*MultiPool) CheckEnoughCommitments 

func (m *MultiPool) CheckEnoughCommitments() error

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

Note that this checks all committees in the multi-pool and returns an error if any doesn't have enoguh commitments.

func (*MultiPool) GetExecutorCommitments 

func (m *MultiPool) GetExecutorCommitments() (result []ExecutorCommitment)

GetExecutorCommitments returns a list of executor commitments in the pool.

func (*MultiPool) GetNextTimeout 

func (m *MultiPool) GetNextTimeout() (timeout time.Time)

GetNextTimeout returns the minimum next timeout of all committee pools.

func (*MultiPool) GetTimeoutCommittees 

func (m *MultiPool) GetTimeoutCommittees(now time.Time) (result []*Pool)

GetTimeoutCommittees returns a list of committee pools that are up for their TryFinalize to be called.

func (*MultiPool) ResetCommitments 

func (m *MultiPool) ResetCommitments()

ResetCommitments resets the commitments in the pool and clears their discrepancy flags.

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 OpenMergeCommitment 

type OpenMergeCommitment struct {
	MergeCommitment

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

OpenMergeCommitment is a merge commitment that has been verified and deserialized.

The open commitment still contains the original signed commitment.

func (OpenMergeCommitment) MostlyEqual 

func (c OpenMergeCommitment) MostlyEqual(other OpenCommitment) bool

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

func (OpenMergeCommitment) ToDDResult 

func (c OpenMergeCommitment) ToDDResult() interface{}

ToDDResult returns a commitment-specific result after discrepancy detection.

func (OpenMergeCommitment) ToVote 

func (c OpenMergeCommitment) ToVote() hash.Hash

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

func (*OpenMergeCommitment) UnmarshalCBOR 

func (c *OpenMergeCommitment) 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"`
	// MergeCommitments are the commitments in the pool iff Committee.Kind
	// is scheduler.KindComputeMerge.
	MergeCommitments map[signature.PublicKey]OpenMergeCommitment `json:"merge_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 timestamp means that no timeout is
	// to be scheduled.
	NextTimeout time.Time `json:"next_timeout"`

	// MemberSet is a cached committee member set. If not provided it will be automatically
	// constructed based on the passed Committee.
	MemberSet map[signature.PublicKey]bool `json:"member_set,omitempty"`
}

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

func (p *Pool) AddMergeCommitment(
	ctx context.Context,
	blk *block.Block,
	sv SignatureVerifier,
	nl NodeLookup,
	commitment *MergeCommitment,
	ccPool *MultiPool,
) error

AddMergeCommitment verifies and adds a new merge commitment to the pool.

Any executor commitments are added to the provided 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) 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) GetCommitteeID 

func (p *Pool) GetCommitteeID() hash.Hash

GetCommitteeID returns the identifier of the committee this pool is collecting commitments for.

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(now time.Time) 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 and clears the discrepancy flag.

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(
	now time.Time,
	roundTimeout time.Duration,
	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 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
}

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

type SignedTxnSchedulerBatch 

type SignedTxnSchedulerBatch struct {
	signature.Signed
}

SignedTxnSchedulerBatch is a TxnSchedulerBatch, signed by the transaction scheduler.

func SignTxnSchedulerBatch 

func SignTxnSchedulerBatch(signer signature.Signer, tsbd *TxnSchedulerBatch) (*SignedTxnSchedulerBatch, error)

SignTxnSchedulerBatch signs a TxnSchedulerBatch struct using the given signer.

func (*SignedTxnSchedulerBatch) Open 

func (s *SignedTxnSchedulerBatch) Open(tsbd *TxnSchedulerBatch) error

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

type TxnSchedulerBatch 

type TxnSchedulerBatch struct {
	// CommitteeID is the committee ID of the target executor committee.
	CommitteeID hash.Hash `json:"cid"`

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

TxnSchedulerBatch 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.

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.