protocol

package
v0.1.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Leader 

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

Leader will produce an oracle id for the given epoch.

func RunOracle 

func RunOracle(
	ctx context.Context,

	config config.SharedConfig,
	configOverrider types.ConfigOverrider,
	contractTransmitter types.ContractTransmitter,
	database types.Database,
	datasource types.DataSource,
	id commontypes.OracleID,
	keys types.PrivateKeys,
	localConfig types.LocalConfig,
	logger loghelper.LoggerWithContext,
	netEndpoint NetworkEndpoint,
	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(
	ctx context.Context,
	subprocesses *subprocesses.Subprocesses,

	chNetToPacemaker <-chan MessageToPacemakerWithSender,
	chNetToReportGeneration <-chan MessageToReportGenerationWithSender,
	chPacemakerToOracle chan<- uint32,
	chReportGenerationToTransmission chan<- EventToTransmission,
	config config.SharedConfig,
	configOverrider types.ConfigOverrider,
	contractTransmitter types.ContractTransmitter,
	database types.Database,
	datasource types.DataSource,
	id commontypes.OracleID,
	localConfig types.LocalConfig,
	logger loghelper.LoggerWithContext,
	netSender NetworkSender,
	privateKeys types.PrivateKeys,
	telemetrySender TelemetrySender,
)

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

func RunReportGeneration 

func RunReportGeneration(
	ctx context.Context,
	subprocesses *subprocesses.Subprocesses,

	chNetToReportGeneration <-chan MessageToReportGenerationWithSender,
	chReportGenerationToPacemaker chan<- EventToPacemaker,
	chReportGenerationToTransmission chan<- EventToTransmission,
	config config.SharedConfig,
	configOverrider types.ConfigOverrider,
	contractTransmitter types.ContractTransmitter,
	datasource types.DataSource,
	e uint32,
	id commontypes.OracleID,
	l commontypes.OracleID,
	localConfig types.LocalConfig,
	logger loghelper.LoggerWithContext,
	netSender NetworkSender,
	privateKeys types.PrivateKeys,
	telemetrySender TelemetrySender,
)

Report Generation protocol corresponding to alg. 2 & 3.

func RunTransmission 

func RunTransmission(
	ctx context.Context,
	subprocesses *subprocesses.Subprocesses,

	config config.SharedConfig,
	configOverrider types.ConfigOverrider,
	chReportGenerationToTransmission <-chan EventToTransmission,
	database types.Database,
	id commontypes.OracleID,
	localConfig types.LocalConfig,
	logger loghelper.LoggerWithContext,
	transmitter types.ContractTransmitter,
)

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 struct {
	AttributedObservations AttributedObservations
	Signatures             [][]byte
}

AttestedReportMany consists of attributed observations with aggregated signatures from the oracles which have sent this report to the current epoch leader.

func (AttestedReportMany) Equal 

func (rep AttestedReportMany) Equal(c2 AttestedReportMany) bool

func (*AttestedReportMany) TransmissionArgs 

func (rep *AttestedReportMany) TransmissionArgs(repctx ReportContext) (report []byte, rs,
	ss [][32]byte, vs [32]byte, err error)

func (*AttestedReportMany) VerifySignatures 

func (rep *AttestedReportMany) VerifySignatures(
	repctx ReportContext,
	as signature.EthAddresses,
) error

VerifySignatures checks that all the signatures (c.Signatures) come from the addresses in the map "as", and returns a list of which oracles they came from.

type AttestedReportOne 

type AttestedReportOne struct {
	AttributedObservations AttributedObservations
	Signature              []byte
}

AttestedReportOne is the collated report oracles sign off on, after they've verified the individual signatures in a report-req sent by the current leader

func MakeAttestedReportOne 

func MakeAttestedReportOne(
	aos AttributedObservations,
	repctx ReportContext,
	signer func([]byte) ([]byte, error),
) (AttestedReportOne, error)

func (AttestedReportOne) Equal 

func (rep AttestedReportOne) Equal(rep2 AttestedReportOne) bool

func (*AttestedReportOne) Verify 

func (c *AttestedReportOne) Verify(repctx ReportContext, a types.OnChainSigningAddress) (err error)

Verify is used by the leader to check the signature a process attaches to its report message (the c.Sig value.)

type AttributedObservation 

type AttributedObservation struct {
	Observation observation.Observation
	Observer    commontypes.OracleID
}

AttributedObservation succinctly attributes a value reported to an oracle

func (AttributedObservation) Equal 

func (o AttributedObservation) Equal(o2 AttributedObservation) bool

type AttributedObservations 

type AttributedObservations []AttributedObservation

func (AttributedObservations) Equal 

func (aos AttributedObservations) Equal(aos2 AttributedObservations) bool

func (AttributedObservations) Median 

func (aos AttributedObservations) Median() (observation.Observation, error)

func (AttributedObservations) OnChainReport 

func (aos AttributedObservations) OnChainReport(repctx ReportContext) ([]byte, error)

OnChainReport returns the serialized report which is transmitted to the onchain contract, and signed by participating oracles using their onchain identities

type AttributedSignedObservation 

type AttributedSignedObservation struct {
	SignedObservation SignedObservation
	Observer          commontypes.OracleID
}

func (AttributedSignedObservation) Equal 

func (aso AttributedSignedObservation) Equal(aso2 AttributedSignedObservation) bool

type DomainSeparationTag 

type DomainSeparationTag [32]byte

DomainSeparationTag consists of: 11-byte zero padding 16-byte configDigest 4-byte epoch 1-byte round It uniquely identifies a message to a particular group-epoch-round tuple. It is used in signature verification

type EpochRound 

type EpochRound struct {
	Epoch uint32
	Round uint8
}

func (EpochRound) Less 

func (x EpochRound) Less(y EpochRound) bool

type EventChangeLeader 

type EventChangeLeader 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 EventProgress 

type EventProgress 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 EventToPacemaker 

type EventToPacemaker interface {
	// contains filtered or unexported methods
}

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

type EventToTransmission 

type EventToTransmission 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 struct {
	Epoch  uint32
	Round  uint8
	Report AttestedReportMany
}

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 Message 

type Message interface {
	// 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 struct {
	// contains filtered or unexported fields
}

MessageBuffer implements a fixed capacity ringbuffer for items of type MessageToReportGeneration

func NewMessageBuffer 

func NewMessageBuffer(cap int) *MessageBuffer

func (*MessageBuffer) Peek 

func (rb *MessageBuffer) Peek() *MessageToReportGeneration

Peek at the front item

func (*MessageBuffer) Pop 

func (rb *MessageBuffer) Pop() *MessageToReportGeneration

Pop front item

func (*MessageBuffer) Push 

func (rb *MessageBuffer) Push(msg MessageToReportGeneration)

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

type MessageFinal 

type MessageFinal struct {
	Epoch  uint32
	Round  uint8
	Report AttestedReportMany
}

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

func (msg MessageFinal) Equal(m2 MessageFinal) bool

type MessageFinalEcho 

type MessageFinalEcho struct {
	MessageFinal
}

MessageFinalEcho corresponds to the "final-echo" message in alg. 2. It is broadcast by all oracles to all other oracles, to ensure that all can play their role in transmitting the report to the on-chain contract.

func (MessageFinalEcho) Equal 

func (msg MessageFinalEcho) Equal(m2 MessageFinalEcho) bool

type MessageNewEpoch 

type MessageNewEpoch struct {
	Epoch uint32
}

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.

type MessageObserve 

type MessageObserve struct {
	Epoch             uint32
	Round             uint8
	SignedObservation SignedObservation
}

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

func (MessageObserve) Equal 

func (msg MessageObserve) Equal(msg2 MessageObserve) bool

type MessageObserveReq 

type MessageObserveReq struct {
	Epoch uint32
	Round uint8
}

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

type MessageReport 

type MessageReport struct {
	Epoch  uint32
	Round  uint8
	Report AttestedReportOne
}

MessageReport corresponds to the "report" message from alg. 2. It is sent by participating oracles in response to a MessageReportReq, and contains the final form of the report, based on the collated observations, and the sending oracle's signature.

func (MessageReport) Equal 

func (msg MessageReport) Equal(m2 MessageReport) bool

type MessageReportReq 

type MessageReportReq struct {
	Epoch                        uint32
	Round                        uint8
	AttributedSignedObservations []AttributedSignedObservation
}

MessageReportReq corresponds to the "report-req" message from alg. 2. It is sent by the epoch leader with collated observations for the participating oracles to sign.

type MessageToPacemaker 

type MessageToPacemaker interface {
	Message
	// contains filtered or unexported methods
}

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

type MessageToPacemakerWithSender 

type MessageToPacemakerWithSender struct {
	// contains filtered or unexported fields
}

MessageToPacemakerWithSender records a msg with the idx of the sender oracle

type MessageToReportGeneration 

type MessageToReportGeneration interface {
	Message
	// 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 struct {
	// contains filtered or unexported fields
}

MessageToReportGenerationWithSender records a message destined for the oracle reporting

type MessageWithSender 

type MessageWithSender struct {
	Msg    Message
	Sender commontypes.OracleID
}

MessageWithSender records a msg with the index of the sender oracle

type MinHeapTimeToPendingTransmission 

type MinHeapTimeToPendingTransmission struct {
	// contains filtered or unexported fields
}

Type safe wrapper around MinHeapTimeToContractReportInternal

func (*MinHeapTimeToPendingTransmission) Len 

func (h *MinHeapTimeToPendingTransmission) Len() int

func (*MinHeapTimeToPendingTransmission) Peek 

func (h *MinHeapTimeToPendingTransmission) Peek() MinHeapTimeToPendingTransmissionItem

func (*MinHeapTimeToPendingTransmission) Pop 

func (h *MinHeapTimeToPendingTransmission) Pop() MinHeapTimeToPendingTransmissionItem

func (*MinHeapTimeToPendingTransmission) Push 

func (h *MinHeapTimeToPendingTransmission) Push(item MinHeapTimeToPendingTransmissionItem)

type MinHeapTimeToPendingTransmissionInternal 

type MinHeapTimeToPendingTransmissionInternal []MinHeapTimeToPendingTransmissionItem

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

func (MinHeapTimeToPendingTransmissionInternal) Len 

func (pq MinHeapTimeToPendingTransmissionInternal) Len() int

func (MinHeapTimeToPendingTransmissionInternal) Less 

func (pq MinHeapTimeToPendingTransmissionInternal) Less(i, j int) bool

func (*MinHeapTimeToPendingTransmissionInternal) Pop 

func (pq *MinHeapTimeToPendingTransmissionInternal) Pop() interface{}

func (*MinHeapTimeToPendingTransmissionInternal) Push 

func (pq *MinHeapTimeToPendingTransmissionInternal) Push(x interface{})

func (MinHeapTimeToPendingTransmissionInternal) Swap 

func (pq MinHeapTimeToPendingTransmissionInternal) Swap(i, j int)

type MinHeapTimeToPendingTransmissionItem 

type MinHeapTimeToPendingTransmissionItem struct {
	types.ReportTimestamp
	types.PendingTransmission
}

type NetworkEndpoint 

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

	// 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 interface {
	// SendTo(msg, to) sends msg to "to"
	SendTo(msg Message, to commontypes.OracleID)
	// Broadcast(msg) sends msg to all oracles
	Broadcast(msg Message)
}

NetworkSender sends messages to other oracles

type ReportContext 

type ReportContext struct {
	ConfigDigest types.ConfigDigest
	Epoch        uint32
	Round        uint8
}

func (ReportContext) DomainSeparationTag 

func (r ReportContext) DomainSeparationTag() (d DomainSeparationTag)

func (ReportContext) Equal 

func (r ReportContext) Equal(r2 ReportContext) bool

type SignedObservation 

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

func MakeSignedObservation 

func MakeSignedObservation(
	observation observation.Observation,
	repctx ReportContext,
	signer func(msg []byte) (sig []byte, err error),
) (
	SignedObservation,
	error,
)

func (SignedObservation) Equal 

func (so SignedObservation) Equal(so2 SignedObservation) bool

func (SignedObservation) Verify 

func (so SignedObservation) Verify(repctx ReportContext, publicKey types.OffchainPublicKey) error

type SimpleNetwork 

type SimpleNetwork 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(n int) *SimpleNetwork

NewSimpleNetwork returns a SimpleNetwork for n oracles

func (*SimpleNetwork) Endpoint 

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

Endpoint returns the interface for oracle id's networking facilities

type SimpleNetworkEndpoint 

type SimpleNetworkEndpoint struct {
	// contains filtered or unexported fields
}

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

func (SimpleNetworkEndpoint) Broadcast 

func (end SimpleNetworkEndpoint) Broadcast(msg Message)

Broadcast sends msg to all participating oracles

func (SimpleNetworkEndpoint) Close 

func (SimpleNetworkEndpoint) Close() error

Close satisfies the interface

func (SimpleNetworkEndpoint) Receive 

func (end SimpleNetworkEndpoint) Receive() <-chan MessageWithSender

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

func (SimpleNetworkEndpoint) SendTo 

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

SendTo sends msg to oracle "to"

func (SimpleNetworkEndpoint) Start 

func (SimpleNetworkEndpoint) Start() error

Start satisfies the interface

type TelemetrySender 

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

type XXXUnknownMessageType 

type XXXUnknownMessageType struct{}

Used only for testing

Source Files

View all Source files

Directories

Path Synopsis
Package observation contains the data structures and logic for handling observations provided by the client DataSource.
 Package observation contains the data structures and logic for handling observations provided by the client DataSource.

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.