llo

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2024 License: MIT Imports: 25 Imported by: 5

Documentation

Index

Constants

View Source 
const (
	// OCR protocol limits
	// NOTE: CAREFUL! If we ever accidentally exceed these e.g.
	// through too many channels/streams, the protocol will halt.
	//
	// TODO: How many channels/streams can we support given these constraints?
	// https://smartcontract-it.atlassian.net/browse/MERC-6468
	MaxReportCount       = ocr3types.MaxMaxReportCount
	MaxObservationLength = ocr3types.MaxMaxObservationLength
	MaxOutcomeLength     = ocr3types.MaxMaxOutcomeLength
	MaxReportLength      = ocr3types.MaxMaxReportLength

	// LLO-specific limits
	// Maximum amount of channels that can be added per round (if more than
	// this needs to be added, it will be added in batches until everything is
	// up-to-date)
	MaxObservationRemoveChannelIDsLength = 5
	// Maximum amount of channels that can be removed per round (if more than
	// this needs to be removed, it will be removed in batches until everything
	// is up-to-date)
	MaxObservationUpdateChannelDefinitionsLength = 5
	// Maximum number of streams that can be observed per round
	MaxObservationStreamValuesLength = 10_000
	// MaxOutcomeChannelDefinitionsLength is the maximum number of channels that
	// can be supported
	MaxOutcomeChannelDefinitionsLength = MaxReportCount
)

Additional limits so we can more effectively bound the size of observations NOTE: These are hardcoded because these exact values are relied upon as a property of coming to consensus, it's too dangerous to make these configurable on a per-node basis. It may be possible to add them to the OffchainConfig if they need to be changed dynamically and in a backwards-compatible way.

View Source 
const (
	LifeCycleStageStaging    llotypes.LifeCycleStage = "staging"
	LifeCycleStageProduction llotypes.LifeCycleStage = "production"
	LifeCycleStageRetired    llotypes.LifeCycleStage = "retired"
)

Protocol instances start in either the staging or production stage. They may later be retired and "hand over" their work to another protocol instance that will move from the staging to the production stage.

Variables

View Source 
var (
	LLOStreamValue_Type_name = map[int32]string{
		0: "Decimal",
		1: "Quote",
	}
	LLOStreamValue_Type_value = map[string]int32{
		"Decimal": 0,
		"Quote":   1,
	}
)

Enum value maps for LLOStreamValue_Type.

View Source 
var (
	ErrNilStreamValue = errors.New("nil stream value")
)
View Source 
var File_llo_offchain_config_proto protoreflect.FileDescriptor
View Source 
var File_plugin_codecs_proto protoreflect.FileDescriptor

Functions

func Decode added in v0.1.1 

func Decode(value StreamValue, data []byte) error

func VerifyChannelDefinitions added in v0.1.1 

func VerifyChannelDefinitions(channelDefs llotypes.ChannelDefinitions) error

Types

type AggregatorFunc added in v0.1.1 

type AggregatorFunc func(values []StreamValue, f int) (StreamValue, error)

func GetAggregatorFunc added in v0.1.1 

func GetAggregatorFunc(a llotypes.Aggregator) AggregatorFunc

type ChannelDefinitionCache 

type ChannelDefinitionCache interface {
	Definitions() llotypes.ChannelDefinitions
}

type ChannelDefinitionWithID 

type ChannelDefinitionWithID struct {
	llotypes.ChannelDefinition
	ChannelID llotypes.ChannelID
}

type ChannelHash 

type ChannelHash [32]byte

func MakeChannelHash 

func MakeChannelHash(cd ChannelDefinitionWithID) ChannelHash

MakeChannelHash is used for mapping ChannelDefinitionWithIDs

type Config 

type Config struct {
	// Enables additional logging that might be expensive, e.g. logging entire
	// channel definitions on every round or other very large structs
	VerboseLogging bool
}

type DSOpts 

type DSOpts interface {
	VerboseLogging() bool
	SeqNr() uint64
	OutCtx() ocr3types.OutcomeContext
	ConfigDigest() ocr2types.ConfigDigest
}

type DataSource 

type DataSource interface {
	// For each known streamID, Observe should set the observed value in the
	// passed streamValues.
	// If an observation fails, or the stream is unknown, no value should be
	// set.
	Observe(ctx context.Context, streamValues StreamValues, opts DSOpts) error
}

type Decimal added in v0.1.1 

type Decimal decimal.Decimal

func ToDecimal added in v0.1.1 

func ToDecimal(d decimal.Decimal) *Decimal

func (*Decimal) Decimal added in v0.1.1 

func (v *Decimal) Decimal() decimal.Decimal

func (*Decimal) MarshalBinary added in v0.1.1 

func (v *Decimal) MarshalBinary() ([]byte, error)

func (*Decimal) MarshalText added in v0.1.1 

func (v *Decimal) MarshalText() ([]byte, error)

func (*Decimal) String added in v0.1.1 

func (v *Decimal) String() string

func (*Decimal) Type added in v0.1.1 

func (v *Decimal) Type() LLOStreamValue_Type

func (*Decimal) UnmarshalBinary added in v0.1.1 

func (v *Decimal) UnmarshalBinary(data []byte) error

func (*Decimal) UnmarshalText added in v0.1.1 

func (v *Decimal) UnmarshalText(data []byte) error

type EVMOnchainConfigCodec added in v0.1.1 

type EVMOnchainConfigCodec struct{}

EVMOnchainConfigCodec provides a llo-specific implementation of OnchainConfigCodec.

An encoded onchain config is expected to be in the format <version><predecessorConfigDigest> where version is a uint8 and min and max are in the format returned by EncodeValueInt192.

func (EVMOnchainConfigCodec) Decode added in v0.1.1 

func (EVMOnchainConfigCodec) Decode(b []byte) (OnchainConfig, error)

TODO: Needs fuzz testing - MERC-3524

func (EVMOnchainConfigCodec) Encode added in v0.1.1 

func (EVMOnchainConfigCodec) Encode(c OnchainConfig) ([]byte, error)

TODO: Needs fuzz testing - MERC-3524

type ErrUnreportableChannel 

type ErrUnreportableChannel struct {
	Inner     error `json:",omitempty"`
	Reason    string
	ChannelID llotypes.ChannelID
}

func (*ErrUnreportableChannel) Error 

func (e *ErrUnreportableChannel) Error() string

func (*ErrUnreportableChannel) String 

func (e *ErrUnreportableChannel) String() string

func (*ErrUnreportableChannel) Unwrap 

func (e *ErrUnreportableChannel) Unwrap() error

type JSONReportCodec 

type JSONReportCodec struct{}

func (JSONReportCodec) Decode 

func (cdc JSONReportCodec) Decode(b []byte) (r Report, err error)

func (JSONReportCodec) Encode 

func (cdc JSONReportCodec) Encode(ctx context.Context, r Report, _ llotypes.ChannelDefinition) ([]byte, error)

func (JSONReportCodec) Pack added in v0.1.1 

func (cdc JSONReportCodec) Pack(digest types.ConfigDigest, seqNr uint64, report ocr2types.Report, sigs []types.AttributedOnchainSignature) ([]byte, error)

TODO: Needs tests, MERC-3524

func (JSONReportCodec) Unpack added in v0.1.1 

func (cdc JSONReportCodec) Unpack(b []byte) (digest types.ConfigDigest, seqNr uint64, report ocr2types.Report, sigs []types.AttributedOnchainSignature, err error)

TODO: Needs tests, MERC-3524

func (JSONReportCodec) UnpackDecode added in v0.1.1 

func (cdc JSONReportCodec) UnpackDecode(b []byte) (digest types.ConfigDigest, seqNr uint64, report Report, sigs []types.AttributedOnchainSignature, err error)

TODO: Needs tests, MERC-3524

type JSONStreamValue added in v0.1.1 

type JSONStreamValue struct {
	Type  LLOStreamValue_Type
	Value string
}

type LLOChannelDefinitionProto 

type LLOChannelDefinitionProto struct {
	ReportFormat uint32                 `protobuf:"varint,1,opt,name=reportFormat,proto3" json:"reportFormat,omitempty"`
	Streams      []*LLOStreamDefinition `protobuf:"bytes,2,rep,name=streams,proto3" json:"streams,omitempty"`
	Opts         []byte                 `protobuf:"bytes,3,opt,name=opts,proto3" json:"opts,omitempty"`
	// contains filtered or unexported fields
}

func (*LLOChannelDefinitionProto) Descriptor deprecated 

func (*LLOChannelDefinitionProto) Descriptor() ([]byte, []int)

Deprecated: Use LLOChannelDefinitionProto.ProtoReflect.Descriptor instead.

func (*LLOChannelDefinitionProto) GetOpts added in v0.1.1 

func (x *LLOChannelDefinitionProto) GetOpts() []byte

func (*LLOChannelDefinitionProto) GetReportFormat 

func (x *LLOChannelDefinitionProto) GetReportFormat() uint32

func (*LLOChannelDefinitionProto) GetStreams added in v0.1.1 

func (x *LLOChannelDefinitionProto) GetStreams() []*LLOStreamDefinition

func (*LLOChannelDefinitionProto) ProtoMessage 

func (*LLOChannelDefinitionProto) ProtoMessage()

func (*LLOChannelDefinitionProto) ProtoReflect 

func (x *LLOChannelDefinitionProto) ProtoReflect() protoreflect.Message

func (*LLOChannelDefinitionProto) Reset 

func (x *LLOChannelDefinitionProto) Reset()

func (*LLOChannelDefinitionProto) String 

func (x *LLOChannelDefinitionProto) String() string

type LLOChannelIDAndDefinitionProto 

type LLOChannelIDAndDefinitionProto struct {
	ChannelID         uint32                     `protobuf:"varint,1,opt,name=channelID,proto3" json:"channelID,omitempty"`
	ChannelDefinition *LLOChannelDefinitionProto `protobuf:"bytes,2,opt,name=channelDefinition,proto3" json:"channelDefinition,omitempty"`
	// contains filtered or unexported fields
}

func (*LLOChannelIDAndDefinitionProto) Descriptor deprecated 

func (*LLOChannelIDAndDefinitionProto) Descriptor() ([]byte, []int)

Deprecated: Use LLOChannelIDAndDefinitionProto.ProtoReflect.Descriptor instead.

func (*LLOChannelIDAndDefinitionProto) GetChannelDefinition 

func (x *LLOChannelIDAndDefinitionProto) GetChannelDefinition() *LLOChannelDefinitionProto

func (*LLOChannelIDAndDefinitionProto) GetChannelID 

func (x *LLOChannelIDAndDefinitionProto) GetChannelID() uint32

func (*LLOChannelIDAndDefinitionProto) ProtoMessage 

func (*LLOChannelIDAndDefinitionProto) ProtoMessage()

func (*LLOChannelIDAndDefinitionProto) ProtoReflect 

func (x *LLOChannelIDAndDefinitionProto) ProtoReflect() protoreflect.Message

func (*LLOChannelIDAndDefinitionProto) Reset 

func (x *LLOChannelIDAndDefinitionProto) Reset()

func (*LLOChannelIDAndDefinitionProto) String 

func (x *LLOChannelIDAndDefinitionProto) String() string

type LLOChannelIDAndValidAfterSecondsProto 

type LLOChannelIDAndValidAfterSecondsProto struct {
	ChannelID         uint32 `protobuf:"varint,1,opt,name=channelID,proto3" json:"channelID,omitempty"`
	ValidAfterSeconds uint32 `protobuf:"varint,2,opt,name=validAfterSeconds,proto3" json:"validAfterSeconds,omitempty"`
	// contains filtered or unexported fields
}

func (*LLOChannelIDAndValidAfterSecondsProto) Descriptor deprecated 

func (*LLOChannelIDAndValidAfterSecondsProto) Descriptor() ([]byte, []int)

Deprecated: Use LLOChannelIDAndValidAfterSecondsProto.ProtoReflect.Descriptor instead.

func (*LLOChannelIDAndValidAfterSecondsProto) GetChannelID 

func (x *LLOChannelIDAndValidAfterSecondsProto) GetChannelID() uint32

func (*LLOChannelIDAndValidAfterSecondsProto) GetValidAfterSeconds 

func (x *LLOChannelIDAndValidAfterSecondsProto) GetValidAfterSeconds() uint32

func (*LLOChannelIDAndValidAfterSecondsProto) ProtoMessage 

func (*LLOChannelIDAndValidAfterSecondsProto) ProtoMessage()

func (*LLOChannelIDAndValidAfterSecondsProto) ProtoReflect 

func (x *LLOChannelIDAndValidAfterSecondsProto) ProtoReflect() protoreflect.Message

func (*LLOChannelIDAndValidAfterSecondsProto) Reset 

func (x *LLOChannelIDAndValidAfterSecondsProto) Reset()

func (*LLOChannelIDAndValidAfterSecondsProto) String 

func (x *LLOChannelIDAndValidAfterSecondsProto) String() string

type LLOObservationProto 

type LLOObservationProto struct {
	AttestedPredecessorRetirement []byte   `protobuf:"bytes,1,opt,name=attestedPredecessorRetirement,proto3" json:"attestedPredecessorRetirement,omitempty"`
	ShouldRetire                  bool     `protobuf:"varint,2,opt,name=shouldRetire,proto3" json:"shouldRetire,omitempty"`
	UnixTimestampNanoseconds      int64    `protobuf:"varint,3,opt,name=unixTimestampNanoseconds,proto3" json:"unixTimestampNanoseconds,omitempty"`
	RemoveChannelIDs              []uint32 `protobuf:"varint,4,rep,packed,name=removeChannelIDs,proto3" json:"removeChannelIDs,omitempty"`
	// Maps are safe to use here because Observation serialization does not
	// need to be deterministic. Non-deterministic map serialization is
	// marginally more efficient than converting to tuples and guarantees
	// uniqueness.
	UpdateChannelDefinitions map[uint32]*LLOChannelDefinitionProto `` /* 190-byte string literal not displayed */
	StreamValues             map[uint32]*LLOStreamValue            `` /* 166-byte string literal not displayed */
	// contains filtered or unexported fields
}

WARNING Use extreme caution making changes in this file All changes MUST be backwards compatible If the format changes in a backwards incompatible way, active DONs can become stuck permanently

func (*LLOObservationProto) Descriptor deprecated 

func (*LLOObservationProto) Descriptor() ([]byte, []int)

Deprecated: Use LLOObservationProto.ProtoReflect.Descriptor instead.

func (*LLOObservationProto) GetAttestedPredecessorRetirement 

func (x *LLOObservationProto) GetAttestedPredecessorRetirement() []byte

func (*LLOObservationProto) GetRemoveChannelIDs 

func (x *LLOObservationProto) GetRemoveChannelIDs() []uint32

func (*LLOObservationProto) GetShouldRetire 

func (x *LLOObservationProto) GetShouldRetire() bool

func (*LLOObservationProto) GetStreamValues 

func (x *LLOObservationProto) GetStreamValues() map[uint32]*LLOStreamValue

func (*LLOObservationProto) GetUnixTimestampNanoseconds 

func (x *LLOObservationProto) GetUnixTimestampNanoseconds() int64

func (*LLOObservationProto) GetUpdateChannelDefinitions 

func (x *LLOObservationProto) GetUpdateChannelDefinitions() map[uint32]*LLOChannelDefinitionProto

func (*LLOObservationProto) ProtoMessage 

func (*LLOObservationProto) ProtoMessage()

func (*LLOObservationProto) ProtoReflect 

func (x *LLOObservationProto) ProtoReflect() protoreflect.Message

func (*LLOObservationProto) Reset 

func (x *LLOObservationProto) Reset()

func (*LLOObservationProto) String 

func (x *LLOObservationProto) String() string

type LLOOffchainConfigProto 

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

func (*LLOOffchainConfigProto) Descriptor deprecated 

func (*LLOOffchainConfigProto) Descriptor() ([]byte, []int)

Deprecated: Use LLOOffchainConfigProto.ProtoReflect.Descriptor instead.

func (*LLOOffchainConfigProto) ProtoMessage 

func (*LLOOffchainConfigProto) ProtoMessage()

func (*LLOOffchainConfigProto) ProtoReflect 

func (x *LLOOffchainConfigProto) ProtoReflect() protoreflect.Message

func (*LLOOffchainConfigProto) Reset 

func (x *LLOOffchainConfigProto) Reset()

func (*LLOOffchainConfigProto) String 

func (x *LLOOffchainConfigProto) String() string

type LLOOutcomeProto 

type LLOOutcomeProto struct {
	LifeCycleStage                   string                                   `protobuf:"bytes,1,opt,name=lifeCycleStage,proto3" json:"lifeCycleStage,omitempty"`
	ObservationsTimestampNanoseconds int64                                    `protobuf:"varint,2,opt,name=observationsTimestampNanoseconds,proto3" json:"observationsTimestampNanoseconds,omitempty"`
	ChannelDefinitions               []*LLOChannelIDAndDefinitionProto        `protobuf:"bytes,3,rep,name=channelDefinitions,proto3" json:"channelDefinitions,omitempty"`
	ValidAfterSeconds                []*LLOChannelIDAndValidAfterSecondsProto `protobuf:"bytes,4,rep,name=validAfterSeconds,proto3" json:"validAfterSeconds,omitempty"`
	StreamAggregates                 []*LLOStreamAggregate                    `protobuf:"bytes,5,rep,name=streamAggregates,proto3" json:"streamAggregates,omitempty"`
	// contains filtered or unexported fields
}

NOTE: Outcome must serialize deterministically, hence use of repeated tuple instead of maps

func (*LLOOutcomeProto) Descriptor deprecated 

func (*LLOOutcomeProto) Descriptor() ([]byte, []int)

Deprecated: Use LLOOutcomeProto.ProtoReflect.Descriptor instead.

func (*LLOOutcomeProto) GetChannelDefinitions 

func (x *LLOOutcomeProto) GetChannelDefinitions() []*LLOChannelIDAndDefinitionProto

func (*LLOOutcomeProto) GetLifeCycleStage 

func (x *LLOOutcomeProto) GetLifeCycleStage() string

func (*LLOOutcomeProto) GetObservationsTimestampNanoseconds 

func (x *LLOOutcomeProto) GetObservationsTimestampNanoseconds() int64

func (*LLOOutcomeProto) GetStreamAggregates added in v0.1.1 

func (x *LLOOutcomeProto) GetStreamAggregates() []*LLOStreamAggregate

func (*LLOOutcomeProto) GetValidAfterSeconds 

func (x *LLOOutcomeProto) GetValidAfterSeconds() []*LLOChannelIDAndValidAfterSecondsProto

func (*LLOOutcomeProto) ProtoMessage 

func (*LLOOutcomeProto) ProtoMessage()

func (*LLOOutcomeProto) ProtoReflect 

func (x *LLOOutcomeProto) ProtoReflect() protoreflect.Message

func (*LLOOutcomeProto) Reset 

func (x *LLOOutcomeProto) Reset()

func (*LLOOutcomeProto) String 

func (x *LLOOutcomeProto) String() string

type LLOStreamAggregate added in v0.1.1 

type LLOStreamAggregate struct {
	StreamID    uint32          `protobuf:"varint,1,opt,name=streamID,proto3" json:"streamID,omitempty"`
	StreamValue *LLOStreamValue `protobuf:"bytes,2,opt,name=streamValue,proto3" json:"streamValue,omitempty"`
	Aggregator  uint32          `protobuf:"varint,3,opt,name=aggregator,proto3" json:"aggregator,omitempty"`
	// contains filtered or unexported fields
}

func StreamAggregatesToProtoOutcome added in v0.1.1 

func StreamAggregatesToProtoOutcome(in StreamAggregates) (out []*LLOStreamAggregate, err error)

TODO: Needs thorough unit testing of all paths including nil handling MERC-3524

func (*LLOStreamAggregate) Descriptor deprecated added in v0.1.1 

func (*LLOStreamAggregate) Descriptor() ([]byte, []int)

Deprecated: Use LLOStreamAggregate.ProtoReflect.Descriptor instead.

func (*LLOStreamAggregate) GetAggregator added in v0.1.1 

func (x *LLOStreamAggregate) GetAggregator() uint32

func (*LLOStreamAggregate) GetStreamID added in v0.1.1 

func (x *LLOStreamAggregate) GetStreamID() uint32

func (*LLOStreamAggregate) GetStreamValue added in v0.1.1 

func (x *LLOStreamAggregate) GetStreamValue() *LLOStreamValue

func (*LLOStreamAggregate) ProtoMessage added in v0.1.1 

func (*LLOStreamAggregate) ProtoMessage()

func (*LLOStreamAggregate) ProtoReflect added in v0.1.1 

func (x *LLOStreamAggregate) ProtoReflect() protoreflect.Message

func (*LLOStreamAggregate) Reset added in v0.1.1 

func (x *LLOStreamAggregate) Reset()

func (*LLOStreamAggregate) String added in v0.1.1 

func (x *LLOStreamAggregate) String() string

type LLOStreamDefinition added in v0.1.1 

type LLOStreamDefinition struct {
	StreamID   uint32 `protobuf:"varint,1,opt,name=streamID,proto3" json:"streamID,omitempty"`
	Aggregator uint32 `protobuf:"varint,2,opt,name=aggregator,proto3" json:"aggregator,omitempty"`
	// contains filtered or unexported fields
}

func (*LLOStreamDefinition) Descriptor deprecated added in v0.1.1 

func (*LLOStreamDefinition) Descriptor() ([]byte, []int)

Deprecated: Use LLOStreamDefinition.ProtoReflect.Descriptor instead.

func (*LLOStreamDefinition) GetAggregator added in v0.1.1 

func (x *LLOStreamDefinition) GetAggregator() uint32

func (*LLOStreamDefinition) GetStreamID added in v0.1.1 

func (x *LLOStreamDefinition) GetStreamID() uint32

func (*LLOStreamDefinition) ProtoMessage added in v0.1.1 

func (*LLOStreamDefinition) ProtoMessage()

func (*LLOStreamDefinition) ProtoReflect added in v0.1.1 

func (x *LLOStreamDefinition) ProtoReflect() protoreflect.Message

func (*LLOStreamDefinition) Reset added in v0.1.1 

func (x *LLOStreamDefinition) Reset()

func (*LLOStreamDefinition) String added in v0.1.1 

func (x *LLOStreamDefinition) String() string

type LLOStreamObservationProto 

type LLOStreamObservationProto struct {
	Valid bool   `protobuf:"varint,1,opt,name=valid,proto3" json:"valid,omitempty"`
	Value []byte `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
	// contains filtered or unexported fields
}

func (*LLOStreamObservationProto) Descriptor deprecated 

func (*LLOStreamObservationProto) Descriptor() ([]byte, []int)

Deprecated: Use LLOStreamObservationProto.ProtoReflect.Descriptor instead.

func (*LLOStreamObservationProto) GetValid 

func (x *LLOStreamObservationProto) GetValid() bool

func (*LLOStreamObservationProto) GetValue 

func (x *LLOStreamObservationProto) GetValue() []byte

func (*LLOStreamObservationProto) ProtoMessage 

func (*LLOStreamObservationProto) ProtoMessage()

func (*LLOStreamObservationProto) ProtoReflect 

func (x *LLOStreamObservationProto) ProtoReflect() protoreflect.Message

func (*LLOStreamObservationProto) Reset 

func (x *LLOStreamObservationProto) Reset()

func (*LLOStreamObservationProto) String 

func (x *LLOStreamObservationProto) String() string

type LLOStreamValue added in v0.1.1 

type LLOStreamValue struct {
	Type  LLOStreamValue_Type `protobuf:"varint,1,opt,name=type,proto3,enum=v1.LLOStreamValue_Type" json:"type,omitempty"`
	Value []byte              `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
	// contains filtered or unexported fields
}

func (*LLOStreamValue) Descriptor deprecated added in v0.1.1 

func (*LLOStreamValue) Descriptor() ([]byte, []int)

Deprecated: Use LLOStreamValue.ProtoReflect.Descriptor instead.

func (*LLOStreamValue) GetType added in v0.1.1 

func (x *LLOStreamValue) GetType() LLOStreamValue_Type

func (*LLOStreamValue) GetValue added in v0.1.1 

func (x *LLOStreamValue) GetValue() []byte

func (*LLOStreamValue) ProtoMessage added in v0.1.1 

func (*LLOStreamValue) ProtoMessage()

func (*LLOStreamValue) ProtoReflect added in v0.1.1 

func (x *LLOStreamValue) ProtoReflect() protoreflect.Message

func (*LLOStreamValue) Reset added in v0.1.1 

func (x *LLOStreamValue) Reset()

func (*LLOStreamValue) String added in v0.1.1 

func (x *LLOStreamValue) String() string

type LLOStreamValueQuote added in v0.1.1 

type LLOStreamValueQuote struct {
	Bid       []byte `protobuf:"bytes,1,opt,name=bid,proto3" json:"bid,omitempty"`
	Benchmark []byte `protobuf:"bytes,2,opt,name=benchmark,proto3" json:"benchmark,omitempty"`
	Ask       []byte `protobuf:"bytes,3,opt,name=ask,proto3" json:"ask,omitempty"`
	// contains filtered or unexported fields
}

func (*LLOStreamValueQuote) Descriptor deprecated added in v0.1.1 

func (*LLOStreamValueQuote) Descriptor() ([]byte, []int)

Deprecated: Use LLOStreamValueQuote.ProtoReflect.Descriptor instead.

func (*LLOStreamValueQuote) GetAsk added in v0.1.1 

func (x *LLOStreamValueQuote) GetAsk() []byte

func (*LLOStreamValueQuote) GetBenchmark added in v0.1.1 

func (x *LLOStreamValueQuote) GetBenchmark() []byte

func (*LLOStreamValueQuote) GetBid added in v0.1.1 

func (x *LLOStreamValueQuote) GetBid() []byte

func (*LLOStreamValueQuote) ProtoMessage added in v0.1.1 

func (*LLOStreamValueQuote) ProtoMessage()

func (*LLOStreamValueQuote) ProtoReflect added in v0.1.1 

func (x *LLOStreamValueQuote) ProtoReflect() protoreflect.Message

func (*LLOStreamValueQuote) Reset added in v0.1.1 

func (x *LLOStreamValueQuote) Reset()

func (*LLOStreamValueQuote) String added in v0.1.1 

func (x *LLOStreamValueQuote) String() string

type LLOStreamValue_Type added in v0.1.1 

type LLOStreamValue_Type int32
const (
	LLOStreamValue_Decimal LLOStreamValue_Type = 0
	LLOStreamValue_Quote   LLOStreamValue_Type = 1
)

func (LLOStreamValue_Type) Descriptor added in v0.1.1 

func (LLOStreamValue_Type) Descriptor() protoreflect.EnumDescriptor

func (LLOStreamValue_Type) Enum added in v0.1.1 

func (x LLOStreamValue_Type) Enum() *LLOStreamValue_Type

func (LLOStreamValue_Type) EnumDescriptor deprecated added in v0.1.1 

func (LLOStreamValue_Type) EnumDescriptor() ([]byte, []int)

Deprecated: Use LLOStreamValue_Type.Descriptor instead.

func (LLOStreamValue_Type) Number added in v0.1.1 

func (x LLOStreamValue_Type) Number() protoreflect.EnumNumber

func (LLOStreamValue_Type) String added in v0.1.1 

func (x LLOStreamValue_Type) String() string

func (LLOStreamValue_Type) Type added in v0.1.1 

func (LLOStreamValue_Type) Type() protoreflect.EnumType

type Observation 

type Observation struct {
	// Attested (i.e. signed by f+1 oracles) retirement report from predecessor
	// protocol instance
	AttestedPredecessorRetirement []byte
	// Should this protocol instance be retired?
	ShouldRetire bool
	// Timestamp from when observation is made
	// Note that this is the timestamp immediately before we initiate any
	// observations
	UnixTimestampNanoseconds int64
	// Votes to remove/add channels. Subject to MAX_OBSERVATION_*_LENGTH limits
	RemoveChannelIDs map[llotypes.ChannelID]struct{}
	// Votes to add or replace channel definitions
	UpdateChannelDefinitions llotypes.ChannelDefinitions
	// Observed (numeric) stream values. Subject to
	// MaxObservationStreamValuesLength limit
	StreamValues StreamValues
}

type ObservationCodec 

type ObservationCodec interface {
	Encode(obs Observation) (types.Observation, error)
	Decode(encoded types.Observation) (obs Observation, err error)
}

type OffchainConfig 

type OffchainConfig struct {
}

func DecodeOffchainConfig 

func DecodeOffchainConfig(b []byte) (o OffchainConfig, err error)

func (OffchainConfig) Encode 

func (c OffchainConfig) Encode() ([]byte, error)

type OnchainConfig 

type OnchainConfig struct {
	Version                 uint8
	PredecessorConfigDigest *types.ConfigDigest
}

type OnchainConfigCodec 

type OnchainConfigCodec interface {
	Decode(b []byte) (OnchainConfig, error)
	Encode(OnchainConfig) ([]byte, error)
}

type Outcome 

type Outcome struct {
	// LifeCycleStage the protocol is in
	LifeCycleStage llotypes.LifeCycleStage
	// ObservationsTimestampNanoseconds is the median timestamp from the
	// latest set of observations
	ObservationsTimestampNanoseconds int64
	// ChannelDefinitions defines the set & structure of channels for which we
	// generate reports
	ChannelDefinitions llotypes.ChannelDefinitions
	// Latest ValidAfterSeconds value for each channel, reports for each channel
	// span from ValidAfterSeconds to ObservationTimestampSeconds
	ValidAfterSeconds map[llotypes.ChannelID]uint32
	// StreamAggregates contains stream IDs mapped to various aggregations.
	// Usually you will only have one aggregation type per stream but since
	// channels can define different aggregation methods, sometimes we will
	// need multiple.
	StreamAggregates StreamAggregates
}

func (*Outcome) GenRetirementReport added in v0.1.1 

func (out *Outcome) GenRetirementReport() RetirementReport

func (*Outcome) IsReportable 

func (out *Outcome) IsReportable(channelID llotypes.ChannelID) *ErrUnreportableChannel

Indicates whether a report can be generated for the given channel. Returns nil if channel is reportable NOTE: A channel is still reportable even if missing some or all stream values. The report codec is expected to handle nils and act accordingly (e.g. some values may be optional).

func (*Outcome) ObservationsTimestampSeconds 

func (out *Outcome) ObservationsTimestampSeconds() (uint32, error)

The Outcome's ObservationsTimestamp rounded down to seconds precision

func (*Outcome) ReportableChannels 

func (out *Outcome) ReportableChannels() (reportable []llotypes.ChannelID, unreportable []*ErrUnreportableChannel)

List of reportable channels (according to IsReportable), sorted according to a canonical ordering

type OutcomeCodec 

type OutcomeCodec interface {
	Encode(outcome Outcome) (ocr3types.Outcome, error)
	Decode(encoded ocr3types.Outcome) (outcome Outcome, err error)
}

type Plugin 

type Plugin struct {
	Config                           Config
	PredecessorConfigDigest          *types.ConfigDigest
	ConfigDigest                     types.ConfigDigest
	PredecessorRetirementReportCache PredecessorRetirementReportCache
	ShouldRetireCache                ShouldRetireCache
	ChannelDefinitionCache           ChannelDefinitionCache
	DataSource                       DataSource
	Logger                           logger.Logger
	N                                int
	F                                int
	ObservationCodec                 ObservationCodec
	OutcomeCodec                     OutcomeCodec
	RetirementReportCodec            RetirementReportCodec
	ReportCodecs                     map[llotypes.ReportFormat]ReportCodec
}

func (*Plugin) Close 

func (p *Plugin) Close() error

func (*Plugin) Observation 

func (p *Plugin) Observation(ctx context.Context, outctx ocr3types.OutcomeContext, query types.Query) (types.Observation, error)

Observation gets an observation from the underlying data source. Returns a value or an error.

You may assume that the outctx.SeqNr is increasing monotonically (though *not* strictly) across the lifetime of a protocol instance and that outctx.previousOutcome contains the consensus outcome with sequence number (outctx.SeqNr-1).

Should return a serialized Observation struct.

func (*Plugin) ObservationQuorum 

func (p *Plugin) ObservationQuorum(ctx context.Context, outctx ocr3types.OutcomeContext, query types.Query, aos []types.AttributedObservation) (bool, error)

ObservationQuorum returns the minimum number of valid (according to ValidateObservation) observations needed to construct an outcome.

This function should be pure. Don't do anything slow in here.

This is an advanced feature. The "default" approach (what OCR1 & OCR2 did) is to have an empty ValidateObservation function and return QuorumTwoFPlusOne from this function.

func (*Plugin) Outcome 

func (p *Plugin) Outcome(ctx context.Context, outctx ocr3types.OutcomeContext, query types.Query, aos []types.AttributedObservation) (ocr3types.Outcome, error)

Generates an outcome for a seqNr, typically based on the previous outcome, the current query, and the current set of attributed observations.

This function should be pure. Don't do anything slow in here.

You may assume that the outctx.SeqNr is increasing monotonically (though *not* strictly) across the lifetime of a protocol instance and that outctx.previousOutcome contains the consensus outcome with sequence number (outctx.SeqNr-1).

libocr guarantees that this will always be called with at least 2f+1 AttributedObservations

func (*Plugin) Query 

func (p *Plugin) Query(ctx context.Context, outctx ocr3types.OutcomeContext) (types.Query, error)

Query creates a Query that is sent from the leader to all follower nodes as part of the request for an observation. Be careful! A malicious leader could equivocate (i.e. send different queries to different followers.) Many applications will likely be better off always using an empty query if the oracles don't need to coordinate on what to observe (e.g. in case of a price feed) or the underlying data source offers an (eventually) consistent view to different oracles (e.g. in case of observing a blockchain).

You may assume that the outctx.SeqNr is increasing monotonically (though *not* strictly) across the lifetime of a protocol instance and that outctx.previousOutcome contains the consensus outcome with sequence number (outctx.SeqNr-1).

func (*Plugin) Reports 

func (p *Plugin) Reports(ctx context.Context, seqNr uint64, rawOutcome ocr3types.Outcome) ([]ocr3types.ReportPlus[llotypes.ReportInfo], error)

Generates a (possibly empty) list of reports from an outcome. Each report will be signed and possibly be transmitted to the contract. (Depending on ShouldAcceptAttestedReport & ShouldTransmitAcceptedReport)

This function should be pure. Don't do anything slow in here.

This is likely to change in the future. It will likely be returning a list of report batches, where each batch goes into its own Merkle tree.

You may assume that the outctx.SeqNr is increasing monotonically (though *not* strictly) across the lifetime of a protocol instance and that outctx.previousOutcome contains the consensus outcome with sequence number (outctx.SeqNr-1).

func (*Plugin) ShouldAcceptAttestedReport 

func (p *Plugin) ShouldAcceptAttestedReport(context.Context, uint64, ocr3types.ReportWithInfo[llotypes.ReportInfo]) (bool, error)

func (*Plugin) ShouldTransmitAcceptedReport 

func (p *Plugin) ShouldTransmitAcceptedReport(context.Context, uint64, ocr3types.ReportWithInfo[llotypes.ReportInfo]) (bool, error)

func (*Plugin) ValidateObservation 

func (p *Plugin) ValidateObservation(ctx context.Context, outctx ocr3types.OutcomeContext, query types.Query, ao types.AttributedObservation) error

Should return an error if an observation isn't well-formed. Non-well-formed observations will be discarded by the protocol. This is called for each observation, don't do anything slow in here.

You may assume that the outctx.SeqNr is increasing monotonically (though *not* strictly) across the lifetime of a protocol instance and that outctx.previousOutcome contains the consensus outcome with sequence number (outctx.SeqNr-1).

type PluginFactory 

type PluginFactory struct {
	Config                           Config
	PredecessorRetirementReportCache PredecessorRetirementReportCache
	ShouldRetireCache                ShouldRetireCache
	RetirementReportCodec            RetirementReportCodec
	ChannelDefinitionCache           ChannelDefinitionCache
	DataSource                       DataSource
	Logger                           logger.Logger
	OnchainConfigCodec               OnchainConfigCodec
	ReportCodecs                     map[llotypes.ReportFormat]ReportCodec
}

func NewPluginFactory 

func NewPluginFactory(cfg Config, prrc PredecessorRetirementReportCache, src ShouldRetireCache, rcodec RetirementReportCodec, cdc ChannelDefinitionCache, ds DataSource, lggr logger.Logger, oncc OnchainConfigCodec, reportCodecs map[llotypes.ReportFormat]ReportCodec) *PluginFactory

func (*PluginFactory) NewReportingPlugin 

func (f *PluginFactory) NewReportingPlugin(ctx context.Context, cfg ocr3types.ReportingPluginConfig) (ocr3types.ReportingPlugin[llotypes.ReportInfo], ocr3types.ReportingPluginInfo, error)

type PredecessorRetirementReportCache 

type PredecessorRetirementReportCache interface {
	// AttestedRetirementReport returns the attested retirement report for the
	// given config digest from the local cache.
	//
	// This should return nil and not error in the case of a missing attested
	// retirement report.
	AttestedRetirementReport(predecessorConfigDigest ocr2types.ConfigDigest) ([]byte, error)
	// CheckAttestedRetirementReport verifies that an attested retirement
	// report, which may have come from another node, is valid (signed) with
	// signers corresponding to the given config digest
	CheckAttestedRetirementReport(predecessorConfigDigest ocr2types.ConfigDigest, attestedRetirementReport []byte) (RetirementReport, error)
}

The predecessor protocol instance stores its attested retirement report in this cache (locally, offchain), so it can be fetched by the successor protocol instance.

PredecessorRetirementReportCache is populated by the old protocol instance writing to it and the new protocol instance reading from it.

The sketch envisions it being implemented as a single object that is shared between different protocol instances.

type Quote added in v0.1.1 

type Quote struct {
	Bid       decimal.Decimal
	Benchmark decimal.Decimal
	Ask       decimal.Decimal
}

func (*Quote) IsValid added in v0.1.1 

func (v *Quote) IsValid() bool

func (*Quote) MarshalBinary added in v0.1.1 

func (v *Quote) MarshalBinary() (b []byte, err error)

func (*Quote) MarshalText added in v0.1.1 

func (v *Quote) MarshalText() ([]byte, error)

func (*Quote) Type added in v0.1.1 

func (v *Quote) Type() LLOStreamValue_Type

func (*Quote) UnmarshalBinary added in v0.1.1 

func (v *Quote) UnmarshalBinary(data []byte) error

func (*Quote) UnmarshalText added in v0.1.1 

func (v *Quote) UnmarshalText(data []byte) error

type Report 

type Report struct {
	ConfigDigest types.ConfigDigest
	// OCR sequence number of this report
	SeqNr uint64
	// Channel that is being reported on
	ChannelID llotypes.ChannelID
	// Report is only valid at t > ValidAfterSeconds
	ValidAfterSeconds uint32
	// ObservationTimestampSeconds is the median of all observation timestamps
	// (note that this timestamp is taken immediately before we initiate any
	// observations)
	ObservationTimestampSeconds uint32
	// Values for every stream in the channel
	Values []StreamValue
	// The contract onchain will only validate non-specimen reports. A staging
	// protocol instance will generate specimen reports so we can validate it
	// works properly without any risk of misreports landing on chain.
	Specimen bool
}

type ReportCodec 

type ReportCodec interface {
	// Encode may be lossy, so no Decode function is expected
	// Encode should handle nil stream aggregate values without panicking (it
	// may return error instead)
	Encode(context.Context, Report, llotypes.ChannelDefinition) ([]byte, error)
}

type RetirementReport 

type RetirementReport struct {
	// Carries validity time stamps between protocol instances to ensure there
	// are no gaps
	ValidAfterSeconds map[llotypes.ChannelID]uint32
}

type RetirementReportCodec added in v0.1.1 

type RetirementReportCodec interface {
	Encode(RetirementReport) ([]byte, error)
	Decode([]byte) (RetirementReport, error)
}

type ShouldRetireCache 

type ShouldRetireCache interface {
	// Should the protocol instance retire according to the configuration
	// contract?
	// See: https://github.com/goplugin/mercury-v1-sketch/blob/main/onchain/src/ConfigurationStore.sol#L18
	ShouldRetire(digest ocr2types.ConfigDigest) (bool, error)
}

type StandardRetirementReportCodec added in v0.1.1 

type StandardRetirementReportCodec struct{}

func (StandardRetirementReportCodec) Decode added in v0.1.1 

func (r StandardRetirementReportCodec) Decode(data []byte) (RetirementReport, error)

func (StandardRetirementReportCodec) Encode added in v0.1.1 

func (r StandardRetirementReportCodec) Encode(report RetirementReport) ([]byte, error)

type StreamAggregates added in v0.1.1 

type StreamAggregates map[llotypes.StreamID]map[llotypes.Aggregator]StreamValue

type StreamValue added in v0.1.1 

type StreamValue interface {
	// Binary marshaler/unmarshaler used for protobufs
	// Unmarshal should NOT panic on nil receiver, but instead return ErrNilStreamValue
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
	// TextMarshaler needed for JSON serialization and logging
	// Unmarshal should NOT panic on nil receiver, but instead return ErrNilStreamValue
	encoding.TextMarshaler
	encoding.TextUnmarshaler
	// Type is needed for proto serialization so we know how to unserialize it
	Type() LLOStreamValue_Type
}

func MedianAggregator added in v0.1.1 

func MedianAggregator(values []StreamValue, f int) (StreamValue, error)

func ModeAggregator added in v0.1.1 

func ModeAggregator(values []StreamValue, f int) (StreamValue, error)

func QuoteAggregator added in v0.1.1 

func QuoteAggregator(values []StreamValue, f int) (StreamValue, error)

func UnmarshalJSONStreamValue added in v0.1.1 

func UnmarshalJSONStreamValue(enc *JSONStreamValue) (StreamValue, error)

func UnmarshalProtoStreamValue added in v0.1.1 

func UnmarshalProtoStreamValue(enc *LLOStreamValue) (sv StreamValue, err error)

type StreamValues 

type StreamValues map[llotypes.StreamID]StreamValue

Values for a set of streams, e.g. "eth-usd", "link-usd", "eur-chf" etc StreamIDs are uint32

type Transmitter 

type Transmitter interface {
	// NOTE: Mercury doesn't actually transmit on-chain, so there is no
	// "contract" involved with the transmitter.
	// - Transmit should be implemented and send to Mercury server
	// - FromAccount() should return CSA public key
	ocr3types.ContractTransmitter[llotypes.ReportInfo]
}

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.