types

type BinaryMessageWithSender struct {
	Msg    []byte
	Sender OracleID
}

type BinaryNetworkEndpoint interface {
	// SendTo(msg, to) sends msg to "to"
	SendTo(payload []byte, to OracleID)
	// Broadcast(msg) sends msg to all oracles
	Broadcast(payload []byte)
	// Receive returns channel which carries all messages sent to this oracle.
	Receive() <-chan BinaryMessageWithSender
	// Start starts the endpoint
	Start() error
	// Close stops the endpoint
	Close() error
}

type BinaryNetworkEndpointFactory interface {
	MakeEndpoint(cd ConfigDigest, peerIDs []string, bootstrappers []string, failureThreshold int) (BinaryNetworkEndpoint, error)
	PeerID() string
}

type Bootstrapper interface {
	Start() error
	Close() error
}

type BootstrapperFactory interface {
	MakeBootstrapper(cd ConfigDigest, peerIDs []string, bootstrappers []string, failureThreshold int) (Bootstrapper, error)
}

type ConfigDigest [16]byte

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
	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(
		report []byte,
		rs, ss [][32]byte, vs [32]byte,
	) (
		*types.Transaction, error,
	)

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

	FromAddress() common.Address
}

type DataSource interface {
	// Observe queries the data source. Returns a value or an error.
	// Must not block indefinitely.
	Observe(context.Context) (Observation, error)
}

type Database interface {
	ReadState(configDigest ConfigDigest) (*PersistentState, error)
	WriteState(configDigest ConfigDigest, state PersistentState) error

	ReadConfig() (*ContractConfig, error)
	WriteConfig(config ContractConfig) error

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

type LocalConfig struct {
	// Timeout for making observations.
	// (This is necessary because an oracle's operations are serialized, so
	// blocking forever on an observation would break the oracle.)
	DataSourceTimeout time.Duration

	// Timeout for blockchain interactions (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

	// 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

	// 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.
	ContractConfigConfirmations uint16
}

type LogFields map[string]interface{}

type Logger interface {
	Trace(msg string, fields LogFields)
	Debug(msg string, fields LogFields)
	Info(msg string, fields LogFields)
	Warn(msg string, fields LogFields)
	Error(msg string, fields LogFields)
}

type MonitoringEndpoint interface {
	SendLog(log []byte)
}

type Observation *big.Int

type OffchainPublicKey ed25519.PublicKey

type OnChainSigningAddress common.Address

type OracleID int

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

type PendingTransmissionKey struct {
	ConfigDigest ConfigDigest
	Epoch        uint32
	Round        uint8
}

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 SharedSecretEncryptionPublicKey [curve25519.PointSize]byte // X25519