types

type BinaryNetworkEndpointFactory interface {
	NewEndpoint(cd ConfigDigest, peerIDs []string,
		v2bootstrappers []commontypes.BootstrapperLocator,
		failureThreshold int, tokenBucketRefillRate float64, tokenBucketSize int,
	) (commontypes.BinaryNetworkEndpoint, error)
	PeerID() string
}

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

type ConfigDigest [16]byte

type ConfigOverride struct {
	AlphaPPB uint64
	DeltaC   time.Duration
}

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
}

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

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

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
}

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

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
}

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
}

type Observation *big.Int

type OffchainPublicKey ed25519.PublicKey

type OnChainSigningAddress common.Address

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

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

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
}

type ReportTimestamp struct {
	ConfigDigest ConfigDigest
	Epoch        uint32
	Round        uint8
}

type SharedSecretEncryptionPublicKey [curve25519.PointSize]byte // X25519