ocr3_1types

type BlobBroadcastFetcher interface {
	BlobBroadcaster
	BlobFetcher
}

type BlobBroadcaster interface {
	// BroadcastBlob broadcasts a blob with the given payload and expiration
	// hint, returning a handle that can be used to refer to the blob in the
	// future (e.g. in a query or observation). Note that BroadcastBlob may
	// return an error, and callers must gracefully handle such an error. Errors
	// might be transient, and related to resource exhaustion prevention, so
	// callers are encouraged to employ a backoff when retrying. An error in
	// BroadcastBlob should not cause Observation to error also. BroadcastBlob
	// is a blocking call, and callers must ensure that it fits into their
	// runtime envelope.
	BroadcastBlob(ctx context.Context, payload []byte, expirationHint BlobExpirationHint) (BlobHandle, error)
}

type BlobExpirationHint interface {
	// contains filtered or unexported methods
}

type BlobExpirationHintSequenceNumber struct{ SeqNr uint64 }

type BlobFetcher interface {
	// FetchBlob fetches the payload corresponding to the BlobHandle passed.
	// Callers must gracefully handle errors returned by FetchBlob. FetchBlob is
	// a blocking call, and callers must ensure that it fits into their runtime
	// envelope.
	FetchBlob(ctx context.Context, handle BlobHandle) ([]byte, error)
}

type BlobHandle = blobtypes.BlobHandle

type Database = ocr3types.Database

type KeyValueDatabase interface {
	NewReadWriteTransaction() (KeyValueDatabaseReadWriteTransaction, error)
	NewReadTransaction() (KeyValueDatabaseReadTransaction, error)

	Close() error
}

type KeyValueDatabaseFactory interface {
	NewKeyValueDatabase(configDigest types.ConfigDigest) (KeyValueDatabase, error)
	NewKeyValueDatabaseIfExists(configDigest types.ConfigDigest) (KeyValueDatabase, error)
}

type KeyValueDatabaseIterator interface {
	// Next prepares the next key-value pair for reading. It returns true on
	// success, or false if there is no next key-value pair or an error occurred
	// while preparing it.
	Next() bool
	// Key returns the key of the current key-value pair.
	Key() []byte
	// Value returns the value of the current key-value pair. An error value
	// indicates a failure to retrieve the value, and the caller is responsible
	// for handling it. Even if all errors are nil, [KeyValueDatabaseIterator.Err] must
	// be checked after iteration is completed.
	Value() ([]byte, error)
	// Err returns any error encountered during iteration. Must be checked after
	// the end of the iteration, to ensure that no key-value pairs were missed
	// due to iteration errors. Errors in [KeyValueDatabaseIterator.Value] are distinct
	// and will not cause a non-nil error.
	Err() error
	// Close closes the iterator and releases any resources associated with it.
	// Must be called in any case, even if the iteration encountered any
	// error through [KeyValueDatabaseIterator.Value] or [KeyValueDatabaseIterator.Err].
	// After Close returns, no further calls may be made on the iterator,
	// including another Close.
	Close() error
}

type KeyValueDatabaseReadTransaction interface {
	// If the key exists, the returned value must not be nil!
	Read(key []byte) ([]byte, error)
	// Range iterates over the key-value pairs with keys in the range [loKey,
	// hiKeyExcl), in ascending order of key. Key-value stores typically store
	// keys in a sorted order, making this a fast operation. loKey can be set to
	// 0 length or nil for iteration without a lower bound. hiKeyExcl can be set
	// to 0 length or nil for iteration without an upper bound.
	//
	// WARNING: DO NOT perform any writes/deletes to the key-value store while
	// the iterator is opened.
	Range(loKey []byte, hiKeyExcl []byte) KeyValueDatabaseIterator
	// Discard discards the transaction and releases its resources. See
	// [KeyValueDatabaseReadTransaction] for the lifetime rules.
	Discard()
}

type KeyValueDatabaseReadWriteTransaction interface {
	KeyValueDatabaseReadTransaction
	// A value of nil is interpreted as an empty slice, and does *not* delete
	// the key. For deletions you must use the Delete method.
	Write(key []byte, value []byte) error
	Delete(key []byte) error

	// Commit commits the transaction. Whether it succeeds or fails, no
	// further calls other than Discard may be made on the transaction once
	// Commit returns.
	Commit() error
}

type KeyValueStateReadTransaction interface {
	KeyValueStateReader

	// SeqNr returns the sequence number this transaction reads at: it shows you
	// the KeyValueState as it was once SeqNr() had been committed. Newer
	// sequence numbers may be committed while you hold the transaction; what it
	// shows you will not change.
	SeqNr() uint64

	// Discard releases the transaction. Calling it more than once is fine.
	// After Discard returns, no further calls other than Discard may be made
	// on the transaction.
	Discard()
}

type KeyValueStateReadWriter interface {
	KeyValueStateReader
	// Write writes the value for the provided key.
	// A nil key or value is interpreted as an empty slice.
	// To delete a key, use the Delete method.
	Write(key []byte, value []byte) error
	// Delete deletes the provided key and its associated value.
	// A nil key is interpreted as an empty slice.
	Delete(key []byte) error
}

type KeyValueStateReader interface {
	// Read reads the value associated with the given key.
	// A nil key is interpreted as an empty slice.
	// If the key exists, the returned value will be non-nil.
	// If the key does not exist, it returns (nil, nil).
	Read(key []byte) ([]byte, error)
}

type ReadOnlyKeyValueState interface {
	// NewReadTransaction returns a [KeyValueStateReadTransaction] over the
	// replicated KeyValueState. See [ReadOnlyKeyValueState] for transaction
	// ownership, lifetime, resource usage, and monitoring guidance.
	//
	// ctx applies only to this call, not to the returned transaction.
	// Canceling ctx does not discard the transaction or prevent further reads;
	// you must still call Discard.
	//
	// Defer Discard immediately after successfully opening a transaction:
	//
	//	readTransaction, err := keyValueState.NewReadTransaction(ctx)
	//	if err != nil {
	//		return err
	//	}
	//	defer readTransaction.Discard()
	//
	// Errors can occur during normal operation, for example when the
	// KeyValueState is temporarily unavailable while the oracle is starting up.
	// Fail the request you were serving and try again later.
	// See [ReadOnlyKeyValueState] for restrictions on use from ReportingPlugin
	// methods.
	NewReadTransaction(ctx context.Context) (KeyValueStateReadTransaction, error)
}

type ReportingPlugin[RI any] 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 seqNr is increasing monotonically (though *not*
	// strictly) across the lifetime of a protocol instance.
	//
	// The keyValueStateReader gives read access to the replicated KeyValueState
	// at the point after seqNr - 1 is committed. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted at this function
	// and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	//
	// The blobBroadcastFetcher enables broadcasting and fetching blobs. Broadcasting blobs
	// can be a more efficient data dissemination method than direct use of Query/Observation
	// when data is larger. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted
	// at this function and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	Query(
		ctx context.Context,
		seqNr uint64,
		keyValueStateReader KeyValueStateReader,
		blobBroadcastFetcher BlobBroadcastFetcher,
	) (types.Query, error)

	// Observation gets an observation from the underlying data source. Returns
	// a value or an error.
	//
	// You may assume that the seqNr is increasing monotonically (though *not*
	// strictly) across the lifetime of a protocol instance.
	//
	// The keyValueStateReader gives read access to the replicated KeyValueState
	// at the point after seqNr - 1 is committed. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted at this function
	// and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	//
	// The blobBroadcastFetcher enables broadcasting and fetching blobs. Broadcasting blobs
	// can be a more efficient data dissemination method than direct use of Query/Observation
	// when data is larger. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted
	// at this function and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	Observation(
		ctx context.Context,
		seqNr uint64,
		aq types.AttributedQuery,
		keyValueStateReader KeyValueStateReader,
		blobBroadcastFetcher BlobBroadcastFetcher,
	) (types.Observation, error)

	// ValidateObservation should return an error if an observation isn't well-formed.
	// Non-well-formed observations will be discarded by the protocol.
	//
	// This function must be pure‡.
	//
	// You may assume that the seqNr is increasing monotonically (though *not*
	// strictly) across the lifetime of a protocol instance.
	//
	// This function may be called multiple times for the same seqNr, e.g. once
	// for each observation.
	//
	// The keyValueStateReader gives read access to the replicated KeyValueState
	// at the point after seqNr - 1 is committed. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted at this function
	// and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	//
	// The blobFetcher enables fetching blobs. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted at this function
	// and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	ValidateObservation(
		ctx context.Context,
		seqNr uint64,
		aq types.AttributedQuery,
		ao types.AttributedObservation,
		keyValueStateReader KeyValueStateReader,
		blobFetcher BlobFetcher,
	) error

	// ObservationQuorum indicates whether the provided valid (according to
	// ValidateObservation) observations are sufficient to construct an outcome.
	//
	// This function must be pure‡.
	//
	// This function may be called multiple times for the same seqNr, e.g. on
	// the leader as more observations arrive.
	//
	// This is an advanced feature. The "default" approach (what OCR1 & OCR2
	// did) is to have this function call
	// quorumhelper.ObservationCountReachesObservationQuorum(QuorumTwoFPlusOne, ...)
	//
	// If you write a custom implementation, be sure to consider that Byzantine
	// oracles may not contribute valid observations, and you still want your
	// plugin to remain live. This function must be monotone in aos, i.e. if
	// it returns true for aos, it must also return true for any
	// superset of aos.
	//
	// The AttributedObservations are guaranteed to be from distinct oracles.
	//
	// The keyValueStateReader gives read access to the replicated KeyValueState
	// at the point after seqNr - 1 is committed. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted at this function
	// and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	//
	// The blobFetcher enables fetching blobs. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted at this function
	// and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	ObservationQuorum(
		ctx context.Context,
		seqNr uint64,
		aq types.AttributedQuery,
		aos []types.AttributedObservation,
		keyValueStateReader KeyValueStateReader,
		blobFetcher BlobFetcher,
	) (quorumReached bool, err error)

	// StateTransition modifies the state of the Reporting Plugin, based on
	// the attributed query and the set of attributed observations of the round.
	// Generates ReportsPlusPrecursor, which encodes a possibly empty list of
	// reports.
	//
	// This function must be pure‡.
	//
	// You may assume that the seqNr is increasing monotonically (though *not*
	// strictly) across the lifetime of a protocol instance.
	//
	// You may assume that the provided list of attributed observations has been
	// (1) validated by ValidateObservation on each element, (2) checked
	// by ObservationQuorum to have reached quorum, and (3) all observations are
	// from distinct oracles.
	//
	// The keyValueStateReadWriter gives read and write access to the replicated KeyValueState
	// from the point after seqNr - 1 is committed. Writing to the keyValueStateReadWriter allows
	// a ReportingPlugin to modify the replicated KeyValueState. The keyValueStateReadWriter must not be
	// used outside the execution of this function. (It's okay to use it anywhere in the call tree rooted
	// at this function and to pass it to separate goroutines, but they must stop using it before this
	// function returns. Do not call Write or Delete concurrently from multiple goroutines; perform all
	// writes and deletes from a single goroutine.)
	//
	// The blobFetcher enables fetching blobs. It must not be used outside the execution
	// of this function. (It's okay to use it anywhere in the call tree rooted at this function
	// and to pass it to separate goroutines, but they must stop using it before this
	// function returns.)
	StateTransition(
		ctx context.Context,
		seqNr uint64,
		aq types.AttributedQuery,
		aos []types.AttributedObservation,
		keyValueStateReadWriter KeyValueStateReadWriter,
		blobFetcher BlobFetcher,
	) (ReportsPlusPrecursor, error)

	// Committed notifies the plugin that seqNr has been committed.
	// It might not be called for all sequence numbers.
	// Returning an error != nil from this method will not lead to the round being aborted/not committed.
	//
	// Don't do anything slow in here.
	//
	// The keyValueStateReader gives read access to the replicated KeyValueState
	// in the state that it is after the StateTransition for seqNr is computed.
	// It must not be used outside the execution of this function. (It's okay to
	// use it anywhere in the call tree rooted at this function and to pass it to
	// separate goroutines, but they must stop using it before this function
	// returns.)
	Committed(
		ctx context.Context,
		seqNr uint64,
		keyValueStateReader KeyValueStateReader,
	) error

	// Reports generates a (possibly empty) list of reports from a ReportsPlusPrecursor. Each report
	// will be signed and possibly be transmitted to the contract. (Depending on
	// ShouldAcceptAttestedReport & ShouldTransmitAcceptedReport)
	//
	// This function must be pure‡.
	//
	// 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.
	Reports(
		ctx context.Context,
		seqNr uint64,
		reportsPlusPrecursor ReportsPlusPrecursor,
	) ([]ocr3types.ReportPlus[RI], error)

	// ShouldAcceptAttestedReport decides whether a report should be accepted for transmission.
	// Any report passed to this function will have been attested, i.e. signed by f+1
	// oracles.
	//
	// Don't make assumptions about the seqNr order in which this function
	// is called.
	ShouldAcceptAttestedReport(
		ctx context.Context,
		seqNr uint64,
		reportWithInfo ocr3types.ReportWithInfo[RI],
	) (bool, error)

	// ShouldTransmitAcceptedReport 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 ShouldAcceptAttestedReport.
	//
	// Don't make assumptions about the seqNr 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(
		ctx context.Context,
		seqNr uint64,
		reportWithInfo ocr3types.ReportWithInfo[RI],
	) (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 plugin 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 plugin have completed.
	//
	// See [ReadOnlyKeyValueState] for transaction and goroutine cleanup
	// requirements that must be satisfied before Close returns.
	Close() error
}

type ReportingPluginFactory[RI any] 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(
		context.Context,
		ocr3types.ReportingPluginConfig,
		BlobBroadcastFetcher,
	) (ReportingPlugin[RI], ReportingPluginInfo, error)
}

type ReportingPluginFactory2[RI any] 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(
		context.Context,
		ocr3types.ReportingPluginConfig,
		BlobBroadcastFetcher,
		ReadOnlyKeyValueState,
	) (ReportingPlugin[RI], ReportingPluginInfo, error)
}

type ReportingPluginInfo interface {
	// contains filtered or unexported methods
}

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

	Limits ReportingPluginLimits
}

type ReportingPluginLimits struct {
	MaxQueryBytes                int
	MaxObservationBytes          int
	MaxReportsPlusPrecursorBytes int
	MaxReportBytes               int
	MaxReportCount               int

	// MaxKeyValueModifiedKeys upper bounds the number of modified keys inside
	// the StateTransition method. A key might be modified multiple times within
	// a single StateTransition, but will only count once towards the limit. A
	// modification that resets the value of a key to its original value at the
	// start of StateTransition will still count towards the limit.
	MaxKeyValueModifiedKeys int
	// MaxKeyValueModifiedKeysPlusValuesBytes upper bounds the cumulative bytes
	// for all modifications to key-values inside the StateTransition method.
	// For a write modification, both the key and the value count towards the
	// limit. For a delete modification, only the key counts towards the limit.
	// For each key, only its last modification counts towards the limit. A
	// modification that resets the value of a key to its original value at the
	// start of StateTransition will still count towards the limit.
	MaxKeyValueModifiedKeysPlusValuesBytes int

	// MaxBlobPayloadBytes upper bounds the payload bytes for a single blob. A
	// broadcast with a larger payload will be rejected.
	MaxBlobPayloadBytes int
	// MaxPerOracleUnexpiredBlobCumulativePayloadBytes upper bounds the
	// cumulative payload length for all unreaped blobs from a single oracle.
	// Inbound broadcasts that would violate this upper bound will be rejected.
	// Due to the asynchronous nature of blob reaping, an expired blob might not
	// be reaped yet, and thus might still be counted towards this upper bound.
	// The number of unreaped blobs eventually approximates the number of
	// unexpired blobs. Consequently, you must set this value loosely,
	// multiplying by a factor that accounts for a blob reaping interval in the
	// tens of seconds.
	MaxPerOracleUnexpiredBlobCumulativePayloadBytes int
	// MaxPerOracleUnexpiredBlobCount upper bounds the number of unreaped
	// blobs from a single oracle. Inbound broadcasts that would violate this
	// upper bound will be rejected. Due to the asynchronous nature of blob
	// reaping, an expired blob might not be reaped yet, and thus might still be
	// counted towards this upper bound. The number of unreaped blobs eventually
	// approximates the number of unexpired blobs. Consequently, you must set
	// this value loosely, multiplying by a factor that accounts for a blob
	// reaping interval in the tens of seconds.
	MaxPerOracleUnexpiredBlobCount int
}

type ReportsPlusPrecursor []byte