protocol

package
v0.2200.2 Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2022 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package protocol implements the Runtime Host Protocol.

Index

Constants

View Source 
const (
	// ExecutionModeExecute is the execution mode where the batch of transactions is executed as-is
	// without the ability to perform any modifications to the batch.
	ExecutionModeExecute = 0
	// ExecutionModeSchedule is the execution mode where the runtime is in control of scheduling and
	// may arbitrarily modify the batch during execution.
	//
	// This execution mode will only be used in case the runtime advertises to support the schedule
	// control feature. In this case the call will only contain up to InitialBatchSize transactions
	// and the runtime will need to request more if it needs more.
	ExecutionModeSchedule = 1
)
View Source 
const MethodQueryBatchWeightLimits = "internal.BatchWeightLimits"

MethodQueryBatchWeightLimits is the name of the runtime batch weight limits query method.

Variables

View Source 
var (
	// ErrNotReady is the error reported when the Runtime Host Protocol is not initialized.
	ErrNotReady = errors.New(moduleName, 1, "rhp: not ready")
)

Functions

This section is empty.

Types

type Body 

type Body struct {
	Empty *Empty `json:",omitempty"`
	Error *Error `json:",omitempty"`

	// Runtime interface.
	RuntimeInfoRequest                    *RuntimeInfoRequest                    `json:",omitempty"`
	RuntimeInfoResponse                   *RuntimeInfoResponse                   `json:",omitempty"`
	RuntimePingRequest                    *Empty                                 `json:",omitempty"`
	RuntimeShutdownRequest                *Empty                                 `json:",omitempty"`
	RuntimeCapabilityTEERakInitRequest    *RuntimeCapabilityTEERakInitRequest    `json:",omitempty"`
	RuntimeCapabilityTEERakInitResponse   *Empty                                 `json:",omitempty"`
	RuntimeCapabilityTEERakReportRequest  *Empty                                 `json:",omitempty"`
	RuntimeCapabilityTEERakReportResponse *RuntimeCapabilityTEERakReportResponse `json:",omitempty"`
	RuntimeCapabilityTEERakAvrRequest     *RuntimeCapabilityTEERakAvrRequest     `json:",omitempty"`
	RuntimeCapabilityTEERakAvrResponse    *Empty                                 `json:",omitempty"`
	RuntimeRPCCallRequest                 *RuntimeRPCCallRequest                 `json:",omitempty"`
	RuntimeRPCCallResponse                *RuntimeRPCCallResponse                `json:",omitempty"`
	RuntimeLocalRPCCallRequest            *RuntimeLocalRPCCallRequest            `json:",omitempty"`
	RuntimeLocalRPCCallResponse           *RuntimeLocalRPCCallResponse           `json:",omitempty"`
	RuntimeCheckTxBatchRequest            *RuntimeCheckTxBatchRequest            `json:",omitempty"`
	RuntimeCheckTxBatchResponse           *RuntimeCheckTxBatchResponse           `json:",omitempty"`
	RuntimeExecuteTxBatchRequest          *RuntimeExecuteTxBatchRequest          `json:",omitempty"`
	RuntimeExecuteTxBatchResponse         *RuntimeExecuteTxBatchResponse         `json:",omitempty"`
	RuntimeAbortRequest                   *Empty                                 `json:",omitempty"`
	RuntimeAbortResponse                  *Empty                                 `json:",omitempty"`
	RuntimeKeyManagerPolicyUpdateRequest  *RuntimeKeyManagerPolicyUpdateRequest  `json:",omitempty"`
	RuntimeKeyManagerPolicyUpdateResponse *Empty                                 `json:",omitempty"`
	RuntimeQueryRequest                   *RuntimeQueryRequest                   `json:",omitempty"`
	RuntimeQueryResponse                  *RuntimeQueryResponse                  `json:",omitempty"`
	RuntimeConsensusSyncRequest           *RuntimeConsensusSyncRequest           `json:",omitempty"`
	RuntimeConsensusSyncResponse          *Empty                                 `json:",omitempty"`

	// Host interface.
	HostRPCCallRequest              *HostRPCCallRequest              `json:",omitempty"`
	HostRPCCallResponse             *HostRPCCallResponse             `json:",omitempty"`
	HostStorageSyncRequest          *HostStorageSyncRequest          `json:",omitempty"`
	HostStorageSyncResponse         *HostStorageSyncResponse         `json:",omitempty"`
	HostLocalStorageGetRequest      *HostLocalStorageGetRequest      `json:",omitempty"`
	HostLocalStorageGetResponse     *HostLocalStorageGetResponse     `json:",omitempty"`
	HostLocalStorageSetRequest      *HostLocalStorageSetRequest      `json:",omitempty"`
	HostLocalStorageSetResponse     *Empty                           `json:",omitempty"`
	HostFetchConsensusBlockRequest  *HostFetchConsensusBlockRequest  `json:",omitempty"`
	HostFetchConsensusBlockResponse *HostFetchConsensusBlockResponse `json:",omitempty"`
	HostFetchTxBatchRequest         *HostFetchTxBatchRequest         `json:",omitempty"`
	HostFetchTxBatchResponse        *HostFetchTxBatchResponse        `json:",omitempty"`
}

Body is a protocol message body.

func (Body) Type 

func (body Body) Type() string

Type returns the message type by determining the name of the first non-nil member.

type CheckTxMetadata added in v0.2102.0 

type CheckTxMetadata struct {
	// Priority is the transaction's priority.
	Priority uint64 `json:"priority,omitempty"`

	// Weight are runtime specific transaction weights.
	Weights map[transaction.Weight]uint64 `json:"weights,omitempty"`
}

CheckTxMetadata is the transaction check-tx metadata.

type CheckTxResult added in v0.2100.0 

type CheckTxResult struct {
	// Error is the error (if any) that resulted from the operation.
	Error Error `json:"error"`

	// Meta contains metadata that can be used for scheduling transactions by the scheduler.
	Meta *CheckTxMetadata `json:"meta,omitempty"`
}

CheckTxResult contains the result of a CheckTx operation.

func (*CheckTxResult) IsSuccess added in v0.2100.0 

func (r *CheckTxResult) IsSuccess() bool

IsSuccess returns true if transaction execution was successful.

func (*CheckTxResult) ToCheckedTransaction added in v0.2102.0 

func (r *CheckTxResult) ToCheckedTransaction(rawTx []byte) *transaction.CheckedTransaction

ToCheckedTransaction creates CheckedTransaction from CheckTx result.

Assumes a successful result.

type ComputedBatch 

type ComputedBatch struct {
	// Header is the compute results header.
	Header commitment.ComputeResultsHeader `json:"header"`
	// Log that generates the I/O tree.
	IOWriteLog storage.WriteLog `json:"io_write_log"`
	// Batch of storage write operations.
	StateWriteLog storage.WriteLog `json:"state_write_log"`
	// If this runtime uses a TEE, then this is the signature of Header with
	// node's RAK for this runtime.
	RakSig signature.RawSignature `json:"rak_sig"`
	// Messages are the emitted runtime messages.
	Messages []message.Message `json:"messages"`
}

ComputedBatch is a computed batch.

func (*ComputedBatch) String 

func (b *ComputedBatch) String() string

String returns a string representation of a computed batch.

type Connection 

type Connection interface {
	// Close closes the connection.
	Close()

	// GetInfo retrieves the runtime information.
	GetInfo(ctx context.Context) (*RuntimeInfoResponse, error)

	// Call sends a request to the other side and returns the response or error.
	Call(ctx context.Context, body *Body) (*Body, error)

	// InitHost performs initialization in host mode and transitions the connection to Ready state.
	//
	// This method must be called before the host will answer requests.
	//
	// Only one of InitHost/InitGuest can be called otherwise the method may panic.
	//
	// Returns the self-reported runtime version.
	InitHost(ctx context.Context, conn net.Conn, hi *HostInfo) (*version.Version, error)

	// InitGuest performs initialization in guest mode and transitions the connection to Ready
	// state.
	//
	// Only one of InitHost/InitGuest can be called otherwise the method may panic.
	InitGuest(ctx context.Context, conn net.Conn) error
}

Connection is a Runtime Host Protocol connection interface.

func NewConnection 

func NewConnection(logger *logging.Logger, runtimeID common.Namespace, handler Handler) (Connection, error)

NewConnection creates a new uninitialized RHP connection.

type Empty 

type Empty struct{}

Empty is an empty message body.

type Error 

type Error struct {
	Module  string `json:"module,omitempty"`
	Code    uint32 `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}

Error is a message body representing an error.

func (Error) String added in v0.2100.0 

func (e Error) String() string

String returns a string representation of this runtime error.

type ExecutionMode added in v0.2103.9 

type ExecutionMode uint8

ExecutionMode is the batch execution mode.

type FeatureScheduleControl added in v0.2103.9 

type FeatureScheduleControl struct {
	// InitialBatchSize is the size of the initial batch of transactions.
	InitialBatchSize uint32 `json:"initial_batch_size"`
}

FeatureScheduleControl is a feature specifying that the runtime supports controlling the scheduling of batches. This means that the scheduler should only take priority into account and ignore weights, leaving it up to the runtime to decide which transactions to include.

type Features added in v0.2103.9 

type Features struct {
	// ScheduleControl is the schedule control feature.
	ScheduleControl *FeatureScheduleControl `json:"schedule_control,omitempty"`
}

Features is a set of supported runtime features.

func (*Features) HasScheduleControl added in v0.2103.9 

func (f *Features) HasScheduleControl() bool

HasScheduleControl returns true when the runtime supports the schedule control feature.

type Handler 

type Handler interface {
	// Handle given request and return a response.
	Handle(ctx context.Context, body *Body) (*Body, error)
}

Handler is a protocol message handler interface.

type HostFetchConsensusBlockRequest added in v0.2103.0 

type HostFetchConsensusBlockRequest struct {
	Height uint64 `json:"height"`
}

HostFetchConsensusBlockRequest is a request to host to fetch the given consensus light block.

type HostFetchConsensusBlockResponse added in v0.2103.0 

type HostFetchConsensusBlockResponse struct {
	Block consensus.LightBlock `json:"block"`
}

HostFetchConsensusBlockResponse is a response from host fetching the given consensus light block.

type HostFetchTxBatchRequest added in v0.2103.9 

type HostFetchTxBatchRequest struct {
	// Offset specifies the transaction hash that should serve as an offset when returning
	// transactions from the pool. Transactions will be skipped until the given hash is encountered
	// and only following transactions will be returned.
	Offset *hash.Hash `json:"offset,omitempty"`
	// Limit specifies the maximum size of the batch to request.
	Limit uint32 `json:"limit"`
}

HostFetchTxBatchRequest is a request to host to fetch a further batch of transactions.

type HostFetchTxBatchResponse added in v0.2103.9 

type HostFetchTxBatchResponse struct {
	// Batch is a batch of transactions.
	Batch [][]byte `json:"batch,omitempty"`
}

HostFetchTxBatchResponse is a response from host fetching the given transaction batch.

type HostInfo added in v0.2100.0 

type HostInfo struct {
	// ConsensusBackend is the name of the consensus backend that is in use for the consensus layer.
	ConsensusBackend string
	// ConsensusProtocolVersion is the consensus protocol version that is in use for the consensus
	// layer.
	ConsensusProtocolVersion version.Version
	// ConsensusChainContext is the consensus layer chain domain separation context.
	ConsensusChainContext string

	// LocalConfig is the node-local runtime configuration.
	//
	// This configuration must not be used in any context which requires determinism across
	// replicated runtime instances.
	LocalConfig map[string]interface{}
}

HostInfo contains the information about the host environment that is sent to the runtime during connection initialization.

func (*HostInfo) Clone added in v0.2102.0 

func (hi *HostInfo) Clone() *HostInfo

Clone returns a copy of the HostInfo structure.

type HostLocalStorageGetRequest 

type HostLocalStorageGetRequest struct {
	Key []byte `json:"key"`
}

HostLocalStorageGetRequest is a host local storage get request message body.

type HostLocalStorageGetResponse 

type HostLocalStorageGetResponse struct {
	Value []byte `json:"value"`
}

HostLocalStorageGetResponse is a host local storage get response message body.

type HostLocalStorageSetRequest 

type HostLocalStorageSetRequest struct {
	Key   []byte `json:"key"`
	Value []byte `json:"value"`
}

HostLocalStorageSetRequest is a host local storage set request message body.

type HostRPCCallRequest 

type HostRPCCallRequest struct {
	Endpoint string `json:"endpoint"`
	Request  []byte `json:"request"`
}

HostRPCCallRequest is a host RPC call request message body.

type HostRPCCallResponse 

type HostRPCCallResponse struct {
	Response []byte `json:"response"`
}

HostRPCCallResponse is a host RPC call response message body.

type HostStorageEndpoint added in v0.2100.0 

type HostStorageEndpoint uint8

HostStorageEndpoint is the host storage endpoint. 

const (
	// HostStorageEndpointRuntime is the runtime state storage endpoint.
	HostStorageEndpointRuntime HostStorageEndpoint = 0
	// HostStorageEndpointConsensus is the consensus layer state storage endpoint.
	HostStorageEndpointConsensus HostStorageEndpoint = 1
)

type HostStorageSyncRequest 

type HostStorageSyncRequest struct {
	// Endpoint is the storage endpoint to which this request should be routed.
	Endpoint HostStorageEndpoint `json:"endpoint,omitempty"`

	SyncGet         *storage.GetRequest         `json:",omitempty"`
	SyncGetPrefixes *storage.GetPrefixesRequest `json:",omitempty"`
	SyncIterate     *storage.IterateRequest     `json:",omitempty"`
}

HostStorageSyncRequest is a host storage read syncer request message body.

type HostStorageSyncResponse 

type HostStorageSyncResponse struct {
	ProofResponse *storage.ProofResponse `json:",omitempty"`
}

HostStorageSyncResponse is a host storage read syncer response body.

type Message 

type Message struct {
	ID          uint64      `json:"id"`
	MessageType MessageType `json:"message_type"`
	Body        Body        `json:"body"`
}

Message is a protocol message.

type MessageType 

type MessageType uint8

MessageType is a message type. 

const (
	// Invalid message (should never be seen on the wire).
	MessageInvalid MessageType = 0

	// Request message.
	MessageRequest MessageType = 1

	// Response message.
	MessageResponse MessageType = 2
)

func (MessageType) String 

func (m MessageType) String() string

String returns a string representation of a message type.

type NoOpNotifier 

type NoOpNotifier struct{}

NoOpNotifier is the default no-op runtime notifier implementation.

func (*NoOpNotifier) Start 

func (n *NoOpNotifier) Start() error

Start the no-op notifier.

func (*NoOpNotifier) Stop 

func (n *NoOpNotifier) Stop()

Stop the no-op notifier.

type Notifier 

type Notifier interface {
	// Start the notifier.
	Start() error

	// Stop the notifier.
	Stop()
}

Notifier is a protocol runtime notifier interface.

type RuntimeCapabilityTEERakAvrRequest 

type RuntimeCapabilityTEERakAvrRequest struct {
	AVR ias.AVRBundle `json:"avr"`
}

RuntimeCapabilityTEERakAvrRequest is a worker RFC 0009 CapabilityTEE RAK AVR setup request message body.

type RuntimeCapabilityTEERakInitRequest 

type RuntimeCapabilityTEERakInitRequest struct {
	TargetInfo []byte `json:"target_info"`
}

RuntimeCapabilityTEERakInitRequest is a worker RFC 0009 CapabilityTEE initialization request message body.

type RuntimeCapabilityTEERakReportResponse 

type RuntimeCapabilityTEERakReportResponse struct {
	RakPub signature.PublicKey `json:"rak_pub"`
	Report []byte              `json:"report"`
	Nonce  string              `json:"nonce"`
}

RuntimeCapabilityTEERakReportResponse is a worker RFC 0009 CapabilityTEE RAK response message body.

type RuntimeCheckTxBatchRequest 

type RuntimeCheckTxBatchRequest struct {
	// ConsensusBlock is the consensus light block at the last finalized round
	// height (e.g., corresponding to .Block.Header.Round).
	ConsensusBlock consensus.LightBlock `json:"consensus_block"`

	// Batch of runtime inputs to check.
	Inputs transaction.RawBatch `json:"inputs"`
	// Block on which the batch check should be based.
	Block block.Block `json:"block"`
	// Epoch is the current epoch number.
	Epoch beacon.EpochTime `json:"epoch"`

	// MaxMessages is the maximum number of messages that can be emitted in this
	// round. Any more messages will be rejected by the consensus layer.
	MaxMessages uint32 `json:"max_messages"`
}

RuntimeCheckTxBatchRequest is a worker check tx batch request message body.

type RuntimeCheckTxBatchResponse 

type RuntimeCheckTxBatchResponse struct {
	// Batch of CheckTx results corresponding to transactions passed on input.
	Results []CheckTxResult `json:"results"`
}

RuntimeCheckTxBatchResponse is a worker check tx batch response message body.

type RuntimeConsensusSyncRequest added in v0.2103.0 

type RuntimeConsensusSyncRequest struct {
	Height uint64 `json:"height"`
}

RuntimeConsensusSyncRequest is a runtime consensus block synchronization request message body.

type RuntimeExecuteTxBatchRequest 

type RuntimeExecuteTxBatchRequest struct {
	// Mode is the execution mode.
	Mode ExecutionMode `json:"mode,omitempty"`

	// ConsensusBlock is the consensus light block at the last finalized round
	// height (e.g., corresponding to .Block.Header.Round).
	ConsensusBlock consensus.LightBlock `json:"consensus_block"`

	// RoundResults are the results of executing the previous successful round.
	RoundResults *roothash.RoundResults `json:"round_results"`

	// IORoot is the I/O root containing the inputs (transactions) that
	// the compute node should use. It must match what is passed in "inputs".
	IORoot hash.Hash `json:"io_root"`
	// Batch of inputs (transactions).
	Inputs transaction.RawBatch `json:"inputs"`
	// InMessages are the incoming messages emitted by the consensus layer.
	InMessages []*message.IncomingMessage `json:"in_msgs,omitempty"`
	// Block on which the batch computation should be based.
	Block block.Block `json:"block"`
	// Epoch is the current epoch number.
	Epoch beacon.EpochTime `json:"epoch"`

	// MaxMessages is the maximum number of messages that can be emitted in this
	// round. Any more messages will be rejected by the consensus layer.
	MaxMessages uint32 `json:"max_messages"`
}

RuntimeExecuteTxBatchRequest is a worker execute tx batch request message body.

type RuntimeExecuteTxBatchResponse 

type RuntimeExecuteTxBatchResponse struct {
	Batch             ComputedBatch                 `json:"batch"`
	BatchWeightLimits map[transaction.Weight]uint64 `json:"batch_weight_limits"`

	// TxHashes are the transaction hashes of the included batch.
	TxHashes []hash.Hash `json:"tx_hashes,omitempty"`
	// TxRejectHashes are the transaction hashes of transactions that should be immediately removed
	// from the scheduling queue as they are invalid.
	TxRejectHashes []hash.Hash `json:"tx_reject_hashes,omitempty"`
	// TxInputRoot is the root hash of all transaction inputs.
	TxInputRoot hash.Hash `json:"tx_input_root,omitempty"`
	// TxInputWriteLog is the write log for generating transaction inputs.
	TxInputWriteLog storage.WriteLog `json:"tx_input_write_log,omitempty"`
}

RuntimeExecuteTxBatchResponse is a worker execute tx batch response message body.

type RuntimeInfoRequest 

type RuntimeInfoRequest struct {
	// RuntimeID is the assigned runtime ID of the loaded runtime.
	RuntimeID common.Namespace `json:"runtime_id"`

	// ConsensusBackend is the name of the consensus backend that is in use for the consensus layer.
	ConsensusBackend string `json:"consensus_backend"`
	// ConsensusProtocolVersion is the consensus protocol version that is in use for the consensus
	// layer.
	ConsensusProtocolVersion version.Version `json:"consensus_protocol_version"`
	// ConsensusChainContext is the consensus layer chain domain separation context.
	ConsensusChainContext string `json:"consensus_chain_context"`

	// LocalConfig is the node-local runtime configuration.
	//
	// This configuration must not be used in any context which requires determinism across
	// replicated runtime instances.
	LocalConfig map[string]interface{} `json:"local_config,omitempty"`
}

RuntimeInfoRequest is a worker info request message body.

type RuntimeInfoResponse 

type RuntimeInfoResponse struct {
	// ProtocolVersion is the runtime protocol version supported by the runtime.
	ProtocolVersion version.Version `json:"protocol_version"`

	// RuntimeVersion is the version of the runtime.
	RuntimeVersion version.Version `json:"runtime_version"`

	// Features describe the features supported by the runtime.
	Features *Features `json:"features,omitempty"`
}

RuntimeInfoResponse is a runtime info response message body.

type RuntimeKeyManagerPolicyUpdateRequest 

type RuntimeKeyManagerPolicyUpdateRequest struct {
	SignedPolicyRaw []byte `json:"signed_policy_raw"`
}

RuntimeKeyManagerPolicyUpdateRequest is a runtime key manager policy request message body.

type RuntimeLocalRPCCallRequest 

type RuntimeLocalRPCCallRequest struct {
	// Request.
	Request []byte `json:"request"`
}

RuntimeLocalRPCCallRequest is a worker local RPC call request message body.

type RuntimeLocalRPCCallResponse 

type RuntimeLocalRPCCallResponse struct {
	// Response.
	Response []byte `json:"response"`
}

RuntimeLocalRPCCallResponse is a worker local RPC call response message body.

type RuntimeQueryRequest added in v0.2100.0 

type RuntimeQueryRequest struct {
	// ConsensusBlock is the consensus light block at the last finalized round
	// height (e.g., corresponding to .Header.Round).
	ConsensusBlock consensus.LightBlock `json:"consensus_block"`

	// Header is the current block header.
	Header block.Header `json:"header"`
	// Epoch is the current epoch number.
	Epoch beacon.EpochTime `json:"epoch"`

	// MaxMessages is the maximum number of messages that can be emitted in this
	// round. Any more messages will be rejected by the consensus layer.
	MaxMessages uint32 `json:"max_messages"`

	Method string `json:"method"`
	Args   []byte `json:"args,omitempty"`
}

RuntimeQueryRequest is a runtime query request message body.

type RuntimeQueryResponse added in v0.2100.0 

type RuntimeQueryResponse struct {
	Data []byte `json:"data,omitempty"`
}

RuntimeQueryRequest is a runtime query response message body.

type RuntimeRPCCallRequest 

type RuntimeRPCCallRequest struct {
	// Request.
	Request []byte `json:"request"`
}

RuntimeRPCCallRequest is a worker RPC call request message body.

type RuntimeRPCCallResponse 

type RuntimeRPCCallResponse struct {
	// Response.
	Response []byte `json:"response"`
}

RuntimeRPCCallResponse is a worker RPC call response message body.

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.