types

type Account string

type AttributedObservation struct {
	Observation Observation
	Observer    commontypes.OracleID
}

type AttributedOnchainSignature struct {
	Signature []byte
	Signer    commontypes.OracleID
}

type BinaryNetworkEndpointFactory interface {
	NewEndpoint(
		cd ConfigDigest,
		peerIDs []string,
		v2bootstrappers []commontypes.BootstrapperLocator,
		f int,
		limits BinaryNetworkEndpointLimits,
	) (commontypes.BinaryNetworkEndpoint, error)
	PeerID() string
}

type BinaryNetworkEndpointLimits struct {
	MaxMessageLength          int
	MessagesRatePerOracle     float64
	MessagesCapacityPerOracle int
	BytesRatePerOracle        float64
	BytesCapacityPerOracle    int
}

type BootstrapperFactory interface {
	NewBootstrapper(cd ConfigDigest, peerIDs []string,
		v2bootstrappers []commontypes.BootstrapperLocator,
		f int,
	) (commontypes.Bootstrapper, error)
}

type ConfigDatabase interface {
	ReadConfig(ctx context.Context) (*ContractConfig, error)
	WriteConfig(ctx context.Context, config ContractConfig) error
}

type ConfigDigest [32]byte

type ConfigDigestPrefix uint16

type ConfigEncryptionPublicKey [curve25519.PointSize]byte // X25519

type ContractConfig struct {
	ConfigDigest          ConfigDigest
	ConfigCount           uint64
	Signers               []OnchainPublicKey
	Transmitters          []Account
	F                     uint8
	OnchainConfig         []byte
	OffchainConfigVersion uint64
	OffchainConfig        []byte
}

type ContractConfigTracker interface {
	// Notify may optionally emit notification events when the contract's
	// configuration changes. This is purely used as an optimization reducing
	// the delay between a configuration change and its enactment. Implementors
	// who don't care about this may simply return a nil channel.
	//
	// The returned channel should never be closed.
	Notify() <-chan struct{}

	// LatestConfigDetails returns information about the latest configuration,
	// but not the configuration itself.
	LatestConfigDetails(ctx context.Context) (changedInBlock uint64, configDigest ConfigDigest, err error)

	// LatestConfig returns the latest configuration.
	LatestConfig(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)
}

type ContractTransmitter interface {

	// Transmit sends the report to the on-chain OCR2Aggregator smart
	// contract's Transmit method.
	//
	// In most cases, implementations of this function should store the
	// transmission in a queue/database/..., but perform the actual
	// transmission (and potentially confirmation) of the transaction
	// asynchronously.
	Transmit(
		context.Context,
		ReportContext,
		Report,
		[]AttributedOnchainSignature,
	) error

	// LatestConfigDigestAndEpoch returns the logically latest configDigest and
	// epoch for which a report was successfully transmitted.
	LatestConfigDigestAndEpoch(
		ctx context.Context,
	) (
		configDigest ConfigDigest,
		epoch uint32,
		err error,
	)

	// Account from which the transmitter invokes the contract
	FromAccount() (Account, error)
}

type Database interface {
	ConfigDatabase

	ReadState(ctx context.Context, configDigest ConfigDigest) (*PersistentState, error)
	WriteState(ctx context.Context, configDigest ConfigDigest, state PersistentState) 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
}

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. On Ethereum, recommended values are
	// between fifteen seconds and two minutes. On chains with a lower block
	// interval, a lower poll interval may be appropriate. We enforce a
	// minimum on this value in SanityCheckLocalConfig().
	ContractConfigTrackerPollInterval 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

	// OCR2's MaxDurationQuery will be computed as
	// max(MinOCR2MaxDurationQuery, MaxDurationQuery). Don't use this value
	// unless you understand the potential pitfalls of doing so. No further
	// validation will be done on this value.
	MinOCR2MaxDurationQuery 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
}

type Observation []byte

type OffchainConfigDigester interface {
	// Compute ConfigDigest for the given ContractConfig. The first two bytes of the
	// ConfigDigest must be the big-endian encoding of ConfigDigestPrefix!
	ConfigDigest(ContractConfig) (ConfigDigest, error)

	// This should return the same constant value on every invocation
	ConfigDigestPrefix() (ConfigDigestPrefix, error)
}

type OffchainKeyring interface {
	// OffchainSign returns an EdDSA-Ed25519 signature on msg produced using the
	// standard library's ed25519.Sign function.
	OffchainSign(msg []byte) (signature []byte, err error)

	// ConfigDiffieHellman multiplies point with the secret key (i.e. scalar)
	// that ConfigEncryptionPublicKey corresponds to.
	ConfigDiffieHellman(point [curve25519.PointSize]byte) (sharedPoint [curve25519.PointSize]byte, err error)

	// OffchainPublicKey returns the public component of the keypair used in SignOffchain.
	OffchainPublicKey() OffchainPublicKey

	// ConfigEncryptionPublicKey returns the public component of the keypair used in ConfigDiffieHellman.
	ConfigEncryptionPublicKey() ConfigEncryptionPublicKey
}

type OffchainPublicKey [ed25519.PublicKeySize]byte

type OnchainKeyring interface {
	// PublicKey returns the public key of the keypair used by Sign.
	PublicKey() OnchainPublicKey

	// Sign returns a signature over ReportContext and Report.
	//
	// Reports may contain secret information.
	// Implementations of this function should be careful to not leak
	// the report's contents, e.g. by logging them or including them in
	// returned errors.
	Sign(ReportContext, Report) (signature []byte, err error)

	// Verify verifies a signature over ReportContext and Report allegedly
	// created from OnchainPublicKey.
	//
	// Implementations of this function must gracefully handle malformed or
	// adversarially crafted inputs.
	Verify(_ OnchainPublicKey, _ ReportContext, _ Report, signature []byte) bool

	// Maximum length of a signature
	MaxSignatureLength() int
}

type OnchainPublicKey []byte

type PendingTransmission struct {
	Time                 time.Time
	ExtraHash            [32]byte
	Report               Report
	AttributedSignatures []AttributedOnchainSignature
}

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

type Query []byte

type Report []byte

type ReportContext struct {
	ReportTimestamp
	// A hash over some data that is exchanged during execution of the offchain
	// protocol. The data itself is not needed onchain, but we still want to
	// include it in the signature that goes onchain.
	ExtraHash [32]byte
}

type ReportTimestamp struct {
	ConfigDigest ConfigDigest
	Epoch        uint32
	Round        uint8
}

type ReportingPlugin interface {
	// 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 sequence of epochs and the sequence of rounds
	// within an epoch are strictly monotonically increasing during the lifetime
	// of an instance of this interface.
	Query(context.Context, ReportTimestamp) (Query, error)

	// Observation gets an observation from the underlying data source. Returns
	// a value or an error.
	//
	// You may assume that the sequence of epochs and the sequence of rounds
	// within an epoch are strictly monotonically increasing during the lifetime
	// of an instance of this interface.
	Observation(context.Context, ReportTimestamp, Query) (Observation, error)

	// Decides whether a report (destined for the contract) should be generated
	// in this round. If yes, also constructs the report.
	//
	// You may assume that the sequence of epochs and the sequence of rounds
	// within an epoch are strictly monotonically increasing during the lifetime
	// of an instance of this interface. This function will always be called
	// with at least 2f+1 AttributedObservations from distinct oracles.
	Report(context.Context, ReportTimestamp, Query, []AttributedObservation) (bool, Report, error)

	// Decides whether a report should be accepted for transmission. Any report
	// passed to this function will have been signed by a quorum of oracles.
	//
	// Don't make assumptions about the epoch/round order in which this function
	// is called.
	ShouldAcceptFinalizedReport(context.Context, ReportTimestamp, Report) (bool, error)

	// Decides whether the given report should actually be broadcast to the
	// contract. This is invoked just before the broadcast occurs. Any report
	// passed to this function will have been signed by a quorum of oracles and
	// been accepted by ShouldAcceptFinalizedReport.
	//
	// Don't make assumptions about the epoch/round order in which this function
	// is called.
	//
	// As mentioned above, you should gracefully handle only a subset of a
	// ReportingPlugin's functions being invoked for a given report. For
	// example, due to reloading persisted pending transmissions from the
	// database upon oracle restart, this function  may be called with reports
	// that no other function of this instance of this interface has ever
	// been invoked on.
	ShouldTransmitAcceptedReport(context.Context, ReportTimestamp, Report) (bool, error)

	// If Close is called a second time, it may return an error but must not
	// panic. This will always be called when a ReportingPlugin is no longer
	// needed, e.g. on shutdown of the protocol instance or shutdown of the
	// oracle node. This will only be called after any calls to other functions
	// of the ReportingPlugin will have completed.
	Close() error
}

type ReportingPluginConfig struct {
	ConfigDigest ConfigDigest

	// OracleID (index) of the oracle executing this ReportingPlugin instance.
	OracleID commontypes.OracleID

	// N is the total number of nodes.
	N int

	// F is an upper bound on the number of faulty nodes.
	F int

	// Encoded configuration for the contract
	OnchainConfig []byte

	// Encoded configuration for the ReportingPlugin disseminated through the
	// contract. This value is only passed through the contract, but otherwise
	// ignored by it.
	OffchainConfig []byte

	// Estimate of the duration between rounds. You should not rely on this
	// value being accurate. Rounds might occur more or less frequently than
	// estimated.
	//
	// This value is intended for estimating the load incurred by a
	// ReportingPlugin before running it and for configuring caches.
	EstimatedRoundInterval time.Duration

	// Maximum duration the ReportingPlugin's functions are allowed to take
	MaxDurationQuery                        time.Duration
	MaxDurationObservation                  time.Duration
	MaxDurationReport                       time.Duration
	MaxDurationShouldAcceptFinalizedReport  time.Duration
	MaxDurationShouldTransmitAcceptedReport time.Duration
}

type ReportingPluginFactory interface {
	// Creates a new reporting plugin instance. The instance may have
	// associated goroutines or hold system resources, which should be
	// released when its Close() function is called.
	NewReportingPlugin(ReportingPluginConfig) (ReportingPlugin, ReportingPluginInfo, error)
}

type ReportingPluginInfo struct {
	// Used for debugging purposes.
	Name string

	// If true, quorum requirements are adjusted so that only a single report
	// will reach a quorum of signatures for any (epoch, round) tuple.
	UniqueReports bool

	Limits ReportingPluginLimits
}

type ReportingPluginLimits struct {
	MaxQueryLength       int
	MaxObservationLength int
	MaxReportLength      int
}