types

Documentation

Overview

Package types contains the types and interfaces a consumer of the OCR library needs to be aware of

Index

• Constants
• type BinaryNetworkEndpointFactory
• type BootstrapperFactory
• type ConfigDigest
  • func BytesToConfigDigest(b []byte) (ConfigDigest, error)
  • func (c ConfigDigest) Hex() string
  • func (c *ConfigDigest) Scan(value interface{}) error
  • func (c ConfigDigest) Value() (driver.Value, error)
• type ConfigOverride
• type ConfigOverrider
• type ContractConfig
• type ContractConfigSubscription
• type ContractConfigTracker
• type ContractTransmitter
• type DataSource
• type Database
• type LocalConfig
• type Observation
• type OffchainPublicKey
• type OnChainSigningAddress
• type PendingTransmission
• type PersistentState
  • func (ps PersistentState) Equal(ps2 PersistentState) bool
• type PrivateKeys
• type ReportTimestamp
• type SharedSecretEncryptionPublicKey

Constants

const EnableDangerousDevelopmentMode = "enable dangerous development mode"

const MaxOracles = 31

The maximum number of oracles supported

Types

type BinaryNetworkEndpointFactory

type BinaryNetworkEndpointFactory interface {
	// failureThreshold is a remnant of P2Pv1 and is ignored.
	NewEndpoint(cd ConfigDigest, peerIDs []string,
		v2bootstrappers []commontypes.BootstrapperLocator,
		failureThreshold int, tokenBucketRefillRate float64, tokenBucketSize int,
	) (commontypes.BinaryNetworkEndpoint, error)
	PeerID() string
}

BinaryNetworkEndpointFactory creates permissioned BinaryNetworkEndpoints.

All its functions should be thread-safe.

type BootstrapperFactory

type BootstrapperFactory interface {
	// failureThreshold is a remnant of P2Pv1 and is ignored.
	NewBootstrapper(cd ConfigDigest, peerIDs []string,
		v2bootstrappers []commontypes.BootstrapperLocator,
		failureThreshold int,
	) (commontypes.Bootstrapper, error)
}

BootstrapperFactory creates permissioned Bootstrappers.

All its functions should be thread-safe.

type ConfigDigest

type ConfigDigest [16]byte

func BytesToConfigDigest

func BytesToConfigDigest(b []byte) (ConfigDigest, error)

func (ConfigDigest) Hex

func (c ConfigDigest) Hex() string

func (*ConfigDigest) Scan

func (c *ConfigDigest) Scan(value interface{}) error

Scan complies with sql Scanner interface

func (ConfigDigest) Value

func (c ConfigDigest) Value() (driver.Value, error)

Value returns this instance serialized for database storage.

type ConfigOverride

type ConfigOverride struct {
	AlphaPPB uint64
	DeltaC   time.Duration
}

type ConfigOverrider

type ConfigOverrider interface {
	// Enables locally overriding the configuration parameters in
	// ConfigOverride by returning a non-nil result.  If no override
	// is desired, return nil.
	//
	// This function is expected to return immediately.
	ConfigOverride() *ConfigOverride
}

ConfigOverrider allows overriding some OCR protocol configuration parameters.

All its functions should be thread-safe.

type ContractConfig

type ContractConfig struct {
	ConfigDigest         ConfigDigest
	Signers              []common.Address // TODO: use OnChainSigningAddress?
	Transmitters         []common.Address
	Threshold            uint8
	EncodedConfigVersion uint64
	Encoded              []byte
}

type ContractConfigSubscription

type ContractConfigSubscription interface {
	// May be closed by sender at any time
	Configs() <-chan ContractConfig
	// Calling this multiple times may return an error, but must not panic.
	Close()
}

type ContractConfigTracker

type ContractConfigTracker interface {
	SubscribeToNewConfigs(ctx context.Context) (ContractConfigSubscription, error)
	LatestConfigDetails(ctx context.Context) (changedInBlock uint64, configDigest ConfigDigest, err error)
	ConfigFromLogs(ctx context.Context, changedInBlock uint64) (ContractConfig, error)

	// LatestBlockHeight returns the height of the most recent block in the chain.
	LatestBlockHeight(ctx context.Context) (blockheight uint64, err error)
}

ContractConfigTracker tracks OffchainAggregator.ConfigSet events emitted from blockchain.

All its functions should be thread-safe.

type ContractTransmitter

type ContractTransmitter interface {

	// Transmit sends the report to the on-chain OffchainAggregator smart contract's Transmit method
	Transmit(
		ctx context.Context,
		report []byte,
		rs, ss [][32]byte, vs [32]byte,
	) error

	LatestTransmissionDetails(
		ctx context.Context,
	) (
		configDigest ConfigDigest,
		epoch uint32,
		round uint8,
		latestAnswer Observation,
		latestTimestamp time.Time,
		err error,
	)

	// LatestRoundRequested returns the configDigest, epoch, and round from the latest
	// RoundRequested event emitted by the contract. LatestRoundRequested may or may not
	// return a result if the latest such event was emitted in a block b such that
	// b.timestamp < tip.timestamp - lookback.
	//
	// If no event is found, LatestRoundRequested should return zero values, not an error.
	// An error should only be returned if an actual error occurred during execution,
	// e.g. because there was an error querying the blockchain or the database.
	//
	// As an optimization, this function may also return zero values, if no
	// RoundRequested event has been emitted after the latest NewTransmission event.
	LatestRoundRequested(
		ctx context.Context,
		lookback time.Duration,
	) (
		configDigest ConfigDigest,
		epoch uint32,
		round uint8,
		err error,
	)

	FromAddress() common.Address

	ChainID() *big.Int
}

ContractTransmitter sends new reports to the OffchainAggregator smart contract.

All its functions should be thread-safe.

type DataSource

type DataSource interface {
	// Observe queries the data source. Returns a value or an error. Once the
	// context is expires, Observe may still do cheap computations and return a
	// result, but should return as quickly as possible.
	//
	// More details: In the current implementation, the context passed to
	// Observe will time out after LocalConfig.DataSourceTimeout. However,
	// Observe should *not* make any assumptions about context timeout behavior.
	// Once the context times out, Observe should prioritize returning as
	// quickly as possible, but may still perform fast computations to return a
	// result rather than error. For example, if Observe medianizes a number
	// of data sources, some of which already returned a result to Observe prior
	// to the context's expiry, Observe might still compute their median, and
	// return it instead of an error.
	//
	// Important: Observe should not perform any potentially time-consuming
	// actions like database access, once the context passed has expired.
	Observe(context.Context, ReportTimestamp) (Observation, error)
}

DataSource implementations must be thread-safe. Observe may be called by many different threads concurrently.

type Database

type Database interface {
	ReadState(ctx context.Context, configDigest ConfigDigest) (*PersistentState, error)
	WriteState(ctx context.Context, configDigest ConfigDigest, state PersistentState) error

	ReadConfig(ctx context.Context) (*ContractConfig, error)
	WriteConfig(ctx context.Context, config ContractConfig) error

	StorePendingTransmission(context.Context, ReportTimestamp, PendingTransmission) error
	PendingTransmissionsWithConfigDigest(context.Context, ConfigDigest) (map[ReportTimestamp]PendingTransmission, error)
	DeletePendingTransmission(context.Context, ReportTimestamp) error
	DeletePendingTransmissionsOlderThan(context.Context, time.Time) error
}

Database persistently stores information on-disk. All its functions should be thread-safe.

type LocalConfig

type LocalConfig struct {
	// Timeout for blockchain queries (mediated through
	// ContractConfigTracker and ContractTransmitter).
	// (This is necessary because an oracle's operations are serialized, so
	// blocking forever on a chain interaction would break the oracle.)
	BlockchainTimeout time.Duration

	// Number of block confirmations to wait for before enacting an on-chain
	// configuration change. This value doesn't need to be very high (in
	// particular, it does not need to protect against malicious re-orgs).
	// Since configuration changes create some overhead, and mini-reorgs
	// are fairly common, recommended values are between two and ten.
	//
	// Malicious re-orgs are not any more of concern here than they are in
	// blockchain applications in general: Since nodes check the contract for the
	// latest config every ContractConfigTrackerPollInterval.Seconds(), they will
	// come to a common view of the current config within any interval longer than
	// that, as long as the latest setConfig transaction in the longest chain is
	// stable. They will thus be able to continue reporting after the poll
	// interval, unless an adversary is able to repeatedly re-org the transaction
	// out during every poll interval, which would amount to the capability to
	// censor any transaction.
	//
	// Note that 1 confirmation implies that the transaction/event has been mined in one block.
	// 0 confirmations would imply that the event would be recognised before it has even been mined, which is not currently supported.
	// e.g.
	// Current block height: 42
	// Changed in block height: 43
	// Contract config confirmations: 1
	// STILL PENDING
	//
	// Current block height: 43
	// Changed in block height: 43
	// Contract config confirmations: 1
	// CONFIRMED
	ContractConfigConfirmations uint16

	// SkipContractConfigConfirmations allows to disable the confirmations check entirely
	// This can be useful in some cases e.g. L2 which has instant finality and
	// where local block numbers do not match the on-chain value returned from
	// block.number
	SkipContractConfigConfirmations bool

	// Polling interval at which ContractConfigTracker is queried for
	// updated on-chain configurations. Recommended values are between
	// fifteen seconds and two minutes.
	ContractConfigTrackerPollInterval time.Duration

	// Interval at which we try to establish a subscription on ContractConfigTracker
	// if one doesn't exist. Recommended values are between two and five minutes.
	ContractConfigTrackerSubscribeInterval time.Duration

	// Timeout for ContractTransmitter.Transmit calls.
	ContractTransmitterTransmitTimeout time.Duration

	// Timeout for database interactions.
	// (This is necessary because an oracle's operations are serialized, so
	// blocking forever on an observation would break the oracle.)
	DatabaseTimeout time.Duration

	// Timeout for making observations using the DataSource.Observe method.
	// (This is necessary because an oracle's operations are serialized, so
	// blocking forever on an observation would break the oracle.)
	DataSourceTimeout time.Duration

	// After DataSourceTimeout expires, we additionally wait for this grace
	// period for DataSource.Observe to return a result, before forcibly moving
	// on.
	DataSourceGracePeriod time.Duration

	// DANGER, this turns off all kinds of sanity checks. May be useful for testing.
	// Set this to EnableDangerousDevelopmentMode to turn on dev mode.
	DevelopmentMode string
}

LocalConfig contains oracle-specific configuration details which are not mandated by the on-chain configuration specification via OffchainAggregator.SetConfig

type Observation

type Observation *big.Int

Observation is the type returned by the DataSource.Observe method. Represents an int192 at time of writing

type OffchainPublicKey

type OffchainPublicKey ed25519.PublicKey

OffChainPublicKey is the public key used to cryptographically identify an oracle in inter-oracle communications.

type OnChainSigningAddress

type OnChainSigningAddress common.Address

OnChainSigningAddress is the public key used to cryptographically identify an oracle to the on-chain smart contract.

type PendingTransmission

type PendingTransmission struct {
	Time             time.Time
	Median           Observation
	SerializedReport []byte
	Rs               [][32]byte
	Ss               [][32]byte
	Vs               [32]byte
}

type PersistentState

type PersistentState struct {
	Epoch                uint32
	HighestSentEpoch     uint32
	HighestReceivedEpoch []uint32 // length: at most MaxOracles
}

func (PersistentState) Equal

func (ps PersistentState) Equal(ps2 PersistentState) bool

type PrivateKeys

type PrivateKeys interface {

	// SignOnChain returns an ethereum-style ECDSA secp256k1 signature on msg. See
	// signature.OnChainPrivateKey.Sign for the logic it needs to implement
	SignOnChain(msg []byte) (signature []byte, err error)

	// SignOffChain returns an EdDSA-Ed25519 signature on msg. See
	// signature.OffChainPrivateKey.Sign for the logic it needs to implement
	SignOffChain(msg []byte) (signature []byte, err error)

	// ConfigDiffieHellman multiplies base, as a representative of a Curve 25519
	// point, by a secret scalar, which is also the scalar to multiply
	// curve25519.BasePoint to, in order to get PublicKeyConfig
	ConfigDiffieHellman(base *[curve25519.ScalarSize]byte) (sharedPoint *[curve25519.PointSize]byte, err error)

	// PublicKeyAddressOnChain returns the address corresponding to the
	// public component of the keypair used in SignOnChain
	PublicKeyAddressOnChain() OnChainSigningAddress

	// PublicKeyOffChain returns the pbulic component of the keypair used in SignOffChain
	PublicKeyOffChain() OffchainPublicKey

	// PublicKeyConfig returns the public component of the keypair used in ConfigKeyShare
	PublicKeyConfig() [curve25519.PointSize]byte
}

PrivateKeys contains the secret keys needed for the OCR protocol, and methods which use those keys without exposing them to the rest of the application. There are three key pairs to track, here:

- The on-chain signing key pair (secp256k1), used to sign contract reports

- The off-chain key signing key pair (Ed25519), used to sign observations

- The config encryption key (X25519), used to decrypt the symmetric key which encrypts the offchain configuration data passed through the OffchainAggregator smart contract.

All its functions should be thread-safe.

type ReportTimestamp

type ReportTimestamp struct {
	ConfigDigest ConfigDigest
	Epoch        uint32
	Round        uint8
}

type SharedSecretEncryptionPublicKey

type SharedSecretEncryptionPublicKey [curve25519.PointSize]byte // X25519

SharedSecretEncryptionPublicKey is the public key used to receive an encrypted version of the secret shared amongst all oracles on a common contract.