protocol

package
v0.0.0-...-3f0f60f Latest Latest
Warning

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

Go to latest
Published: Jun 22, 2023 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const ContractTransmitterTimeoutWarningGracePeriod = 50 * time.Millisecond
View Source
const ReportingPluginTimeoutWarningGracePeriod = 100 * time.Millisecond

Variables

This section is empty.

Functions

func ByzQuorumSize

func ByzQuorumSize(n, f int) int

func Leader

func Leader(epoch uint64, n int, key [16]byte) (leader commontypes.OracleID)

Leader will produce an oracle id for the given epoch.

func RunOracle

func RunOracle[RI any](
	ctx context.Context,

	config ocr3config.SharedConfig,
	contractTransmitter ocr3types.ContractTransmitter[RI],
	database Database,
	id commontypes.OracleID,
	localConfig types.LocalConfig,
	logger loghelper.LoggerWithContext,
	netEndpoint NetworkEndpoint[RI],
	offchainKeyring types.OffchainKeyring,
	onchainKeyring ocr3types.OnchainKeyring[RI],
	reportingPlugin ocr3types.OCR3Plugin[RI],
	telemetrySender TelemetrySender,
)

RunOracle runs one oracle instance of the offchain reporting protocol and manages the lifecycle of all underlying goroutines.

RunOracle runs forever until ctx is cancelled. It will only shut down after all its sub-goroutines have exited.

func RunPacemaker

func RunPacemaker[RI any](
	ctx context.Context,

	chNetToPacemaker <-chan MessageToPacemakerWithSender[RI],
	chPacemakerToReportGeneration chan<- EventToReportGeneration[RI],
	chReportGenerationToPacemaker <-chan EventToPacemaker[RI],
	config ocr3config.SharedConfig,
	database Database,
	id commontypes.OracleID,
	localConfig types.LocalConfig,
	logger loghelper.LoggerWithContext,
	netSender NetworkSender[RI],
	offchainKeyring types.OffchainKeyring,
	telemetrySender TelemetrySender,

	restoredEpoch uint64,
)

Pacemaker keeps track of the state and message handling for an oracle participating in the off-chain reporting protocol

func RunReportFinalization

func RunReportFinalization[RI any](
	ctx context.Context,

	chNetToReportFinalization <-chan MessageToReportFinalizationWithSender[RI],
	chReportFinalizationToTransmission chan<- EventToTransmission[RI],
	chReportGenerationToReportFinalization <-chan EventToReportFinalization[RI],
	config ocr3config.SharedConfig,
	contractSigner ocr3types.OnchainKeyring[RI],
	contractTransmitter ocr3types.ContractTransmitter[RI],
	logger loghelper.LoggerWithContext,
	netSender NetworkSender[RI],
	reportingPlugin ocr3types.OCR3Plugin[RI],
)

func RunReportGeneration

func RunReportGeneration[RI any](
	ctx context.Context,
	subprocesses *subprocesses.Subprocesses,

	chNetToReportGeneration <-chan MessageToReportGenerationWithSender[RI],
	chPacemakerToReportGeneration <-chan EventToReportGeneration[RI],
	chReportGenerationToPacemaker chan<- EventToPacemaker[RI],
	chReportGenerationToReportFinalization chan<- EventToReportFinalization[RI],
	config ocr3config.SharedConfig,
	database Database,
	id commontypes.OracleID,
	localConfig types.LocalConfig,
	logger loghelper.LoggerWithContext,
	netSender NetworkSender[RI],
	offchainKeyring types.OffchainKeyring,
	reportingPlugin ocr3types.OCR3Plugin[RI],
	telemetrySender TelemetrySender,

	restoredCert CertifiedPrepareOrCommit,
)

func RunTransmission

func RunTransmission[RI any](
	ctx context.Context,
	subprocesses *subprocesses.Subprocesses,

	chReportFinalizationToTransmission <-chan EventToTransmission[RI],
	config ocr3config.SharedConfig,
	contractTransmitter ocr3types.ContractTransmitter[RI],
	database ocr3types.Database,
	id commontypes.OracleID,
	localConfig types.LocalConfig,
	logger loghelper.LoggerWithContext,
	reportingPlugin ocr3types.OCR3Plugin[RI],
)

TransmissionProtocol tracks the local oracle process's role in the transmission of a report to the on-chain oracle contract.

Note: The transmission protocol doesn't clean up pending transmissions when it is terminated. This is by design, but means that old pending transmissions may accumulate in the database. They should be garbage collected once in a while.

Types

type AttestedReportMany

type AttestedReportMany[RI any] struct {
	ReportWithInfo       ocr3types.ReportWithInfo[RI]
	AttributedSignatures []types.AttributedOnchainSignature
}

type AttributedCommitSignature

type AttributedCommitSignature struct {
	Signature CommitSignature
	Signer    commontypes.OracleID
}

type AttributedPrepareSignature

type AttributedPrepareSignature struct {
	Signature PrepareSignature
	Signer    commontypes.OracleID
}

type AttributedSignedHighestCertifiedTimestamp

type AttributedSignedHighestCertifiedTimestamp struct {
	SignedHighestCertifiedTimestamp SignedHighestCertifiedTimestamp
	Signer                          commontypes.OracleID
}

type AttributedSignedObservation

type AttributedSignedObservation struct {
	SignedObservation SignedObservation
	Observer          commontypes.OracleID
}

type CertifiedPrepareOrCommit

type CertifiedPrepareOrCommit interface {
	Epoch() uint64
	Timestamp() HighestCertifiedTimestamp
	IsGenesis() bool
	Verify(
		_ types.ConfigDigest,
		_ []config.OracleIdentity,
		n int,
		f int,
	) error
	// contains filtered or unexported methods
}

type CertifiedPrepareOrCommitCommit

type CertifiedPrepareOrCommitCommit struct {
	CommitEpoch             uint64
	SeqNr                   uint64
	Outcome                 ocr3types.Outcome
	CommitQuorumCertificate []AttributedCommitSignature
}

func (*CertifiedPrepareOrCommitCommit) Epoch

func (*CertifiedPrepareOrCommitCommit) IsGenesis

func (hc *CertifiedPrepareOrCommitCommit) IsGenesis() bool

func (*CertifiedPrepareOrCommitCommit) Timestamp

func (*CertifiedPrepareOrCommitCommit) Verify

func (hc *CertifiedPrepareOrCommitCommit) Verify(
	configDigest types.ConfigDigest,
	oracleIdentities []config.OracleIdentity,
	n int,
	f int,
) error

type CertifiedPrepareOrCommitPrepare

type CertifiedPrepareOrCommitPrepare struct {
	PrepareEpoch             uint64
	SeqNr                    uint64
	OutcomeInputsDigest      OutcomeInputsDigest
	Outcome                  ocr3types.Outcome
	PrepareQuorumCertificate []AttributedPrepareSignature
}

func (*CertifiedPrepareOrCommitPrepare) Epoch

func (*CertifiedPrepareOrCommitPrepare) IsGenesis

func (hc *CertifiedPrepareOrCommitPrepare) IsGenesis() bool

func (*CertifiedPrepareOrCommitPrepare) Timestamp

func (*CertifiedPrepareOrCommitPrepare) Verify

func (hc *CertifiedPrepareOrCommitPrepare) Verify(
	configDigest types.ConfigDigest,
	oracleIdentities []config.OracleIdentity,
	n int,
	f int,
) error

type CommitSignature

type CommitSignature []byte

func MakeCommitSignature

func MakeCommitSignature(
	ocr3ts Timestamp,
	seqNr uint64,
	outcomeDigest OutcomeDigest,
	signer func(msg []byte) ([]byte, error),
) (CommitSignature, error)

func (CommitSignature) Verify

func (sig CommitSignature) Verify(
	ocr3ts Timestamp,
	seqNr uint64,
	outcomeDigest OutcomeDigest,
	publicKey types.OffchainPublicKey,
) error

type Database

type Database interface {
	types.ConfigDatabase

	ReadCert(ctx context.Context, configDigest types.ConfigDigest) (CertifiedPrepareOrCommit, error)
	WriteCert(ctx context.Context, configDigest types.ConfigDigest, cert CertifiedPrepareOrCommit) error
}

type EventChangeLeader

type EventChangeLeader[RI any] struct{}

EventChangeLeader is used to process the "change-leader" event passed by the local oracle from its the reporting protocol to the leader-election protocol

type EventDeliver

type EventDeliver[RI any] struct {
	CertifiedCommit CertifiedPrepareOrCommitCommit
}

type EventMissingOutcome

type EventMissingOutcome[RI any] struct {
	SeqNr uint64
}

type EventProgress

type EventProgress[RI any] struct{}

EventProgress is used to process the "progress" event passed by the local oracle from its the reporting protocol to the leader-election protocol. It is sent by the reporting protocol when the leader has produced a valid new report.

type EventStartNewEpoch

type EventStartNewEpoch[RI any] struct {
	Epoch uint64
}

type EventToPacemaker

type EventToPacemaker[RI any] interface {
	// contains filtered or unexported methods
}

EventToPacemaker is the interface used to pass in-process events to the leader-election protocol.

type EventToReportFinalization

type EventToReportFinalization[RI any] interface {
	// contains filtered or unexported methods
}

type EventToReportGeneration

type EventToReportGeneration[RI any] interface {
	// contains filtered or unexported methods
}

type EventToTransmission

type EventToTransmission[RI any] interface {
	// contains filtered or unexported methods
}

EventToTransmission is the interface used to pass a completed report to the protocol which will transmit it to the on-chain smart contract.

type EventTransmit

type EventTransmit[RI any] struct {
	SeqNr          uint64
	Index          int
	AttestedReport AttestedReportMany[RI]
}

EventTransmit is used to process the "transmit" event passed by the local reporting protocol to to the local transmit-to-the-onchain-smart-contract protocol.

type HighestCertifiedTimestamp

type HighestCertifiedTimestamp struct {
	SeqNr                 uint64
	CommittedElsePrepared bool
}

func (HighestCertifiedTimestamp) Less

type Message

type Message[RI any] interface {
	// CheckSize checks whether the given message conforms to the limits imposed by
	// reportingPluginLimits
	CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool
	// contains filtered or unexported methods
}

Message is the interface used to pass an inter-oracle message to the local oracle process.

type MessageBuffer

type MessageBuffer[RI any] struct {
	// contains filtered or unexported fields
}

MessageBuffer implements a fixed capacity ringbuffer for items of type MessageToReportGeneration

func NewMessageBuffer

func NewMessageBuffer[RI any](cap int) *MessageBuffer[RI]

func (*MessageBuffer[RI]) Peek

func (rb *MessageBuffer[RI]) Peek() *MessageToReportGeneration[RI]

Peek at the front item

func (*MessageBuffer[RI]) Pop

func (rb *MessageBuffer[RI]) Pop() *MessageToReportGeneration[RI]

Pop front item

func (*MessageBuffer[RI]) Push

func (rb *MessageBuffer[RI]) Push(msg MessageToReportGeneration[RI])

Push new item to back. If the additional item would lead to the capacity being exceeded, remove the front item first

type MessageCommit

type MessageCommit[RI any] struct {
	Epoch     uint64
	SeqNr     uint64
	Signature CommitSignature
}

func (MessageCommit[RI]) CheckSize

func (msg MessageCommit[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessageFinal

type MessageFinal[RI any] struct {
	SeqNr            uint64
	ReportSignatures [][]byte
}

MessageFinal corresponds to the "final" message in alg. 2. It is sent by the current leader with the aggregated signature(s) to all participating oracles, for them to participate in the subsequent transmission of the report to the on-chain contract.

func (MessageFinal[RI]) CheckSize

func (msg MessageFinal[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessageNewEpoch

type MessageNewEpoch[RI any] struct {
	Epoch uint64
}

MessageNewEpoch corresponds to the "newepoch(epoch_number)" message from alg. 1. It indicates that the node believes the protocol should move to the specified epoch.

func (MessageNewEpoch[RI]) CheckSize

func (msg MessageNewEpoch[RI]) CheckSize(types.ReportingPluginLimits) bool

type MessageObserve

type MessageObserve[RI any] struct {
	Epoch             uint64
	SeqNr             uint64
	SignedObservation SignedObservation
}

MessageObserve corresponds to the "observe" message from alg. 2. Participating oracles send this back to the leader in response to MessageStartRound's.

func (MessageObserve[RI]) CheckSize

func (msg MessageObserve[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessagePrepare

type MessagePrepare[RI any] struct {
	Epoch     uint64
	SeqNr     uint64
	Signature PrepareSignature
}

func (MessagePrepare[RI]) CheckSize

func (msg MessagePrepare[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessagePropose

type MessagePropose[RI any] struct {
	Epoch                        uint64
	SeqNr                        uint64
	AttributedSignedObservations []AttributedSignedObservation
}

func (MessagePropose[RI]) CheckSize

func (msg MessagePropose[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessageReconcile

type MessageReconcile[RI any] struct {
	Epoch                           uint64
	HighestCertified                CertifiedPrepareOrCommit
	SignedHighestCertifiedTimestamp SignedHighestCertifiedTimestamp
}

func (MessageReconcile[RI]) CheckSize

func (msg MessageReconcile[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessageRequestCertifiedCommit

type MessageRequestCertifiedCommit[RI any] struct {
	SeqNr uint64
}

func (MessageRequestCertifiedCommit[RI]) CheckSize

func (msg MessageRequestCertifiedCommit[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessageStartEpoch

type MessageStartEpoch[RI any] struct {
	Epoch           uint64
	StartEpochProof StartEpochProof
}

func (MessageStartEpoch[RI]) CheckSize

func (msg MessageStartEpoch[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessageStartRound

type MessageStartRound[RI any] struct {
	Epoch uint64
	SeqNr uint64
	Query types.Query
}

MessageStartRound corresponds to the "observe-req" message from alg. 2. The leader transmits this to request observations from participating oracles, so that it can collate them into a report.

func (MessageStartRound[RI]) CheckSize

func (msg MessageStartRound[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessageSupplyCertifiedCommit

type MessageSupplyCertifiedCommit[RI any] struct {
	CertifiedCommit CertifiedPrepareOrCommitCommit
}

func (MessageSupplyCertifiedCommit[RI]) CheckSize

func (msg MessageSupplyCertifiedCommit[RI]) CheckSize(reportingPluginLimits types.ReportingPluginLimits) bool

type MessageToPacemaker

type MessageToPacemaker[RI any] interface {
	Message[RI]
	// contains filtered or unexported methods
}

MessageToPacemaker is the interface used to pass a message to the local leader-election protocol

type MessageToPacemakerWithSender

type MessageToPacemakerWithSender[RI any] struct {
	// contains filtered or unexported fields
}

MessageToPacemakerWithSender records a msg with the idx of the sender oracle

type MessageToReportFinalization

type MessageToReportFinalization[RI any] interface {
	Message[RI]
	// contains filtered or unexported methods
}

type MessageToReportFinalizationWithSender

type MessageToReportFinalizationWithSender[RI any] struct {
	// contains filtered or unexported fields
}

type MessageToReportGeneration

type MessageToReportGeneration[RI any] interface {
	Message[RI]
	// contains filtered or unexported methods
}

MessageToReportGeneration is the interface used to pass an inter-oracle message to the local oracle reporting process.

type MessageToReportGenerationWithSender

type MessageToReportGenerationWithSender[RI any] struct {
	// contains filtered or unexported fields
}

MessageToReportGenerationWithSender records a message destined for the oracle reporting

type MessageWithSender

type MessageWithSender[RI any] struct {
	Msg    Message[RI]
	Sender commontypes.OracleID
}

MessageWithSender records a msg with the index of the sender oracle

type MinHeapTimeToPendingTransmission

type MinHeapTimeToPendingTransmission[RI any] struct {
	// contains filtered or unexported fields
}

Type safe wrapper around MinHeapTimeToContractReportInternal

func (*MinHeapTimeToPendingTransmission[RI]) Len

func (*MinHeapTimeToPendingTransmission[RI]) Peek

func (*MinHeapTimeToPendingTransmission[RI]) Pop

func (*MinHeapTimeToPendingTransmission[RI]) Push

type MinHeapTimeToPendingTransmissionInternal

type MinHeapTimeToPendingTransmissionInternal[RI any] []MinHeapTimeToPendingTransmissionItem[RI]

Implements heap.Interface and uses interface{} all over the place.

func (MinHeapTimeToPendingTransmissionInternal[RI]) Len

func (MinHeapTimeToPendingTransmissionInternal[RI]) Less

func (*MinHeapTimeToPendingTransmissionInternal[RI]) Pop

func (pq *MinHeapTimeToPendingTransmissionInternal[RI]) Pop() interface{}

func (*MinHeapTimeToPendingTransmissionInternal[RI]) Push

func (pq *MinHeapTimeToPendingTransmissionInternal[RI]) Push(x interface{})

func (MinHeapTimeToPendingTransmissionInternal[RI]) Swap

type MinHeapTimeToPendingTransmissionItem

type MinHeapTimeToPendingTransmissionItem[RI any] struct {
	Time           time.Time
	SeqNr          uint64
	Index          int
	AttestedReport AttestedReportMany[RI]
}

type NetworkEndpoint

type NetworkEndpoint[RI any] interface {
	NetworkSender[RI]
	// Receive returns channel which carries all messages sent to this oracle
	Receive() <-chan MessageWithSender[RI]

	// Start must be called before Receive. Calling Start more than once causes
	// panic.
	Start() error

	// Close must be called before receive. Close can be called multiple times.
	// Close can be called even on an unstarted NetworkEndpoint.
	Close() error
}

NetworkEndpoint sends & receives messages to/from other oracles

type NetworkSender

type NetworkSender[RI any] interface {
	// SendTo(msg, to) sends msg to "to"
	SendTo(msg Message[RI], to commontypes.OracleID)
	// Broadcast(msg) sends msg to all oracles
	Broadcast(msg Message[RI])
}

NetworkSender sends messages to other oracles

type OutcomeDigest

type OutcomeDigest [32]byte

func MakeOutcomeDigest

func MakeOutcomeDigest(outcome ocr3types.Outcome) OutcomeDigest

type OutcomeInputsDigest

type OutcomeInputsDigest [32]byte

func MakeOutcomeInputsDigest

func MakeOutcomeInputsDigest(
	ocr3ts Timestamp,
	previousOutcome ocr3types.Outcome,
	seqNr uint64,
	query types.Query,
	attributedObservations []types.AttributedObservation,
) OutcomeInputsDigest

type PrepareSignature

type PrepareSignature []byte

func MakePrepareSignature

func MakePrepareSignature(
	ocr3ts Timestamp,
	seqNr uint64,
	outcomeInputsDigest OutcomeInputsDigest,
	outcomeDigest OutcomeDigest,
	signer func(msg []byte) ([]byte, error),
) (PrepareSignature, error)

func (PrepareSignature) Verify

func (sig PrepareSignature) Verify(
	ocr3ts Timestamp,
	seqNr uint64,
	outcomeInputsDigest OutcomeInputsDigest,
	outcomeDigest OutcomeDigest,
	publicKey types.OffchainPublicKey,
) error

type SignedHighestCertifiedTimestamp

type SignedHighestCertifiedTimestamp struct {
	HighestCertifiedTimestamp HighestCertifiedTimestamp
	Signature                 []byte
}

func MakeSignedHighestCertifiedTimestamp

func MakeSignedHighestCertifiedTimestamp(
	ocr3ts Timestamp,
	highestCertifiedTimestamp HighestCertifiedTimestamp,
	signer func(msg []byte) ([]byte, error),
) (SignedHighestCertifiedTimestamp, error)

func (*SignedHighestCertifiedTimestamp) Verify

func (shct *SignedHighestCertifiedTimestamp) Verify(ocr3ts Timestamp, publicKey types.OffchainPublicKey) error

type SignedObservation

type SignedObservation struct {
	Observation types.Observation
	Signature   []byte
}

func MakeSignedObservation

func MakeSignedObservation(
	ocr3ts Timestamp,
	query types.Query,
	observation types.Observation,
	signer func(msg []byte) (sig []byte, err error),
) (
	SignedObservation,
	error,
)

func (SignedObservation) Verify

func (so SignedObservation) Verify(ocr3ts Timestamp, query types.Query, publicKey types.OffchainPublicKey) error

type SimpleNetwork

type SimpleNetwork[RI any] struct {
	// contains filtered or unexported fields
}

SimpleNetwork is a strawman (in-memory) implementation of the Network interface. Network channels are buffered and can queue up to 100 messages before blocking.

func NewSimpleNetwork

func NewSimpleNetwork[RI any](n int) *SimpleNetwork[RI]

NewSimpleNetwork returns a SimpleNetwork for n oracles

func (*SimpleNetwork[RI]) Endpoint

func (net *SimpleNetwork[RI]) Endpoint(id commontypes.OracleID) (NetworkEndpoint[RI], error)

Endpoint returns the interface for oracle id's networking facilities

type SimpleNetworkEndpoint

type SimpleNetworkEndpoint[RI any] struct {
	// contains filtered or unexported fields
}

SimpleNetworkEndpoint is a strawman (in-memory) implementation of NetworkEndpoint, used by SimpleNetwork

func (SimpleNetworkEndpoint[RI]) Broadcast

func (end SimpleNetworkEndpoint[RI]) Broadcast(msg Message[RI])

Broadcast sends msg to all participating oracles

func (SimpleNetworkEndpoint[RI]) Close

func (SimpleNetworkEndpoint[RI]) Close() error

Close satisfies the interface

func (SimpleNetworkEndpoint[RI]) Receive

func (end SimpleNetworkEndpoint[RI]) Receive() <-chan MessageWithSender[RI]

Receive returns a channel which carries all messages sent to the oracle

func (SimpleNetworkEndpoint[RI]) SendTo

func (end SimpleNetworkEndpoint[RI]) SendTo(msg Message[RI], to commontypes.OracleID)

SendTo sends msg to oracle "to"

func (SimpleNetworkEndpoint[RI]) Start

func (SimpleNetworkEndpoint[RI]) Start() error

Start satisfies the interface

type StartEpochProof

type StartEpochProof struct {
	HighestCertified      CertifiedPrepareOrCommit
	HighestCertifiedProof []AttributedSignedHighestCertifiedTimestamp
}

func (*StartEpochProof) Verify

func (qc *StartEpochProof) Verify(
	ocr3ts Timestamp,
	oracleIdentities []config.OracleIdentity,
	n int,
	f int,
) error

type TelemetrySender

type TelemetrySender interface {
	RoundStarted(
		configDigest types.ConfigDigest,
		epoch uint64,
		round uint8,
		leader commontypes.OracleID,
	)
}

type Timestamp

type Timestamp struct {
	ConfigDigest types.ConfigDigest
	Epoch        uint64
}

type XXXUnknownMessageType

type XXXUnknownMessageType[RI any] struct{}

Used only for testing

func (XXXUnknownMessageType[RI]) CheckSize

Conform to protocol.Message interface

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL