dbft

type Block[H Hash] interface {
	// Hash returns block hash.
	Hash() H
	// PrevHash returns previous block hash.
	PrevHash() H
	// MerkleRoot returns a merkle root of the transaction hashes.
	MerkleRoot() H
	// Index returns block index.
	Index() uint32

	// Signature returns block's signature.
	Signature() []byte
	// Sign signs block and sets it's signature.
	Sign(key PrivateKey) error
	// Verify checks if signature is correct.
	Verify(key PublicKey, sign []byte) error

	// Transactions returns block's transaction list.
	Transactions() []Transaction[H]
	// SetTransactions sets block's transaction list. For anti-MEV extension
	// transactions provided via this call are taken directly from PreBlock level
	// and thus, may be out-of-date. Thus, with anti-MEV extension enabled it's
	// suggested to use this method as a Block finalizer since it will be called
	// right before the block approval. Do not rely on this with anti-MEV extension
	// disabled.
	SetTransactions([]Transaction[H])
}

type ChangeView interface {
	// NewViewNumber returns proposed view number.
	NewViewNumber() byte

	// Reason returns change view reason.
	Reason() ChangeViewReason
}

type ChangeViewReason byte

type Commit interface {
	// Signature returns commit's signature field
	// which is a final block signature for the current epoch for both dBFT 2.0 and
	// for anti-MEV extension.
	Signature() []byte
}

type Config[H Hash] struct {
	// Logger
	Logger *zap.Logger
	// Timer
	Timer Timer
	// TimePerBlock is the time that need to pass before another block will
	// be accepted. This value may be updated every block.
	TimePerBlock func() time.Duration
	// TimestampIncrement increment is the amount of units to add to timestamp
	// if current time is less than that of previous context.
	// By default use millisecond precision.
	TimestampIncrement uint64
	// AntiMEVExtensionEnablingHeight denotes the height starting from which dBFT
	// Anti-MEV extensions should be enabled. -1 means no extension is enabled.
	AntiMEVExtensionEnablingHeight int64
	// GetKeyPair returns an index of the node in the list of validators
	// together with it's key pair.
	GetKeyPair func([]PublicKey) (int, PrivateKey, PublicKey)
	// NewPreBlockFromContext should allocate, fill from Context and return new block.PreBlock.
	NewPreBlockFromContext func(ctx *Context[H]) PreBlock[H]
	// NewBlockFromContext should allocate, fill from Context and return new block.Block.
	NewBlockFromContext func(ctx *Context[H]) Block[H]
	// RequestTx is a callback which is called when transaction contained
	// in current block can't be found in memory pool. The slice received by
	// this callback MUST NOT be changed.
	RequestTx func(h ...H)
	// StopTxFlow is a callback which is called when the process no longer needs
	// any transactions.
	StopTxFlow func()
	// GetTx returns a transaction from memory pool.
	GetTx func(h H) Transaction[H]
	// GetVerified returns a slice of verified transactions
	// to be proposed in a new block.
	GetVerified func() []Transaction[H]
	// VerifyPreBlock verifies if preBlock is valid.
	VerifyPreBlock func(b PreBlock[H]) bool
	// VerifyBlock verifies if block is valid.
	VerifyBlock func(b Block[H]) bool
	// Broadcast should broadcast payload m to the consensus nodes.
	Broadcast func(m ConsensusPayload[H])
	// ProcessBlock is called every time new preBlock is accepted.
	ProcessPreBlock func(b PreBlock[H]) error
	// ProcessBlock is called every time new block is accepted.
	ProcessBlock func(b Block[H]) error
	// GetBlock should return block with hash.
	GetBlock func(h H) Block[H]
	// WatchOnly tells if a node should only watch.
	WatchOnly func() bool
	// CurrentHeight returns index of the last accepted block.
	CurrentHeight func() uint32
	// CurrentBlockHash returns hash of the last accepted block.
	CurrentBlockHash func() H
	// GetValidators returns list of the validators.
	// When called with a transaction list it must return
	// list of the validators of the next block.
	// If this function ever returns 0-length slice, dbft will panic.
	GetValidators func(...Transaction[H]) []PublicKey
	// NewConsensusPayload is a constructor for payload.ConsensusPayload.
	NewConsensusPayload func(*Context[H], MessageType, any) ConsensusPayload[H]
	// NewPrepareRequest is a constructor for payload.PrepareRequest.
	NewPrepareRequest func(ts uint64, nonce uint64, transactionHashes []H) PrepareRequest[H]
	// NewPrepareResponse is a constructor for payload.PrepareResponse.
	NewPrepareResponse func(preparationHash H) PrepareResponse[H]
	// NewChangeView is a constructor for payload.ChangeView.
	NewChangeView func(newViewNumber byte, reason ChangeViewReason, timestamp uint64) ChangeView
	// NewPreCommit is a constructor for payload.PreCommit.
	NewPreCommit func(data []byte) PreCommit
	// NewCommit is a constructor for payload.Commit.
	NewCommit func(signature []byte) Commit
	// NewRecoveryRequest is a constructor for payload.RecoveryRequest.
	NewRecoveryRequest func(ts uint64) RecoveryRequest
	// NewRecoveryMessage is a constructor for payload.RecoveryMessage.
	NewRecoveryMessage func() RecoveryMessage[H]
	// VerifyPrepareRequest can perform external payload verification and returns true iff it was successful.
	VerifyPrepareRequest func(p ConsensusPayload[H]) error
	// VerifyPrepareResponse performs external PrepareResponse verification and returns nil if it's successful.
	VerifyPrepareResponse func(p ConsensusPayload[H]) error
	// VerifyPreCommit performs external PreCommit verification and returns nil if it's successful.
	// Note that PreBlock-dependent PreCommit verification should be performed inside PreBlock.Verify
	// callback.
	VerifyPreCommit func(p ConsensusPayload[H]) error
	// VerifyCommit performs external Commit verification and returns nil if it's successful.
	// Note that Block-dependent Commit verification should be performed inside Block.Verify
	// callback.
	VerifyCommit func(p ConsensusPayload[H]) error
}

type ConsensusMessage[H Hash] interface {
	// ViewNumber returns view number when this message was originated.
	ViewNumber() byte
	// Type returns type of this message.
	Type() MessageType
	// Payload returns this message's actual payload.
	Payload() any

	// GetChangeView returns payload as if it was ChangeView.
	GetChangeView() ChangeView
	// GetPrepareRequest returns payload as if it was PrepareRequest.
	GetPrepareRequest() PrepareRequest[H]
	// GetPrepareResponse returns payload as if it was PrepareResponse.
	GetPrepareResponse() PrepareResponse[H]
	// GetPreCommit returns payload as if it was PreCommit.
	GetPreCommit() PreCommit
	// GetCommit returns payload as if it was Commit.
	GetCommit() Commit
	// GetRecoveryRequest returns payload as if it was RecoveryRequest.
	GetRecoveryRequest() RecoveryRequest
	// GetRecoveryMessage returns payload as if it was RecoveryMessage.
	GetRecoveryMessage() RecoveryMessage[H]
}

type ConsensusPayload[H Hash] interface {
	ConsensusMessage[H]

	// ValidatorIndex returns index of validator from which
	// payload was originated from.
	ValidatorIndex() uint16

	// SetValidatorIndex sets validator index.
	SetValidatorIndex(i uint16)

	Height() uint32

	// Hash returns 32-byte checksum of the payload.
	Hash() H
}

type Context[H Hash] struct {
	// Config is dBFT's Config instance.
	Config *Config[H]

	// Priv is node's private key.
	Priv PrivateKey
	// Pub is node's public key.
	Pub PublicKey

	// BlockIndex is current block index.
	BlockIndex uint32
	// ViewNumber is current view number.
	ViewNumber byte
	// Validators is a current validator list.
	Validators []PublicKey
	// MyIndex is an index of the current node in the Validators array.
	// It is equal to -1 if node is not a validator or is WatchOnly.
	MyIndex int
	// PrimaryIndex is an index of the primary node in the current epoch.
	PrimaryIndex uint

	// PrevHash is a hash of the previous block.
	PrevHash H

	// Timestamp is a nanosecond-precision timestamp
	Timestamp uint64
	Nonce     uint64
	// TransactionHashes is a slice of hashes of proposed transactions in the current block.
	TransactionHashes []H
	// MissingTransactions is a slice of hashes containing missing transactions for the current block.
	MissingTransactions []H
	// Transactions is a map containing actual transactions for the current block.
	Transactions map[H]Transaction[H]

	// PreparationPayloads stores consensus Prepare* payloads for the current epoch.
	PreparationPayloads []ConsensusPayload[H]
	// PreCommitPayloads stores consensus PreCommit payloads sent through all epochs
	// as a part of anti-MEV dBFT extension. It is assumed that valid PreCommit
	// payloads can only be sent once by a single node per the whole set of consensus
	// epochs for particular block. Invalid PreCommit payloads are kicked off this
	// list immediately (if PrepareRequest was received for the current round, so
	// it's possible to verify PreCommit against PreBlock built on PrepareRequest)
	// or stored till the corresponding PrepareRequest receiving.
	PreCommitPayloads []ConsensusPayload[H]
	// CommitPayloads stores consensus Commit payloads sent throughout all epochs. It
	// is assumed that valid Commit payload can only be sent once by a single node per
	// the whole set of consensus epochs for particular block. Invalid commit payloads
	// are kicked off this list immediately (if PrepareRequest was received for the
	// current round, so it's possible to verify Commit against it) or stored till
	// the corresponding PrepareRequest receiving.
	CommitPayloads []ConsensusPayload[H]
	// ChangeViewPayloads stores consensus ChangeView payloads for the current epoch.
	ChangeViewPayloads []ConsensusPayload[H]
	// LastChangeViewPayloads stores consensus ChangeView payloads for the last epoch.
	LastChangeViewPayloads []ConsensusPayload[H]
	// LastSeenMessage array stores the height and view of the last seen message, for each validator.
	// If this node never heard a thing from validator i, LastSeenMessage[i] will be nil.
	LastSeenMessage []*HeightView
	// contains filtered or unexported fields
}

type DBFT[H Hash] struct {
	Context[H]
	Config[H]

	*sync.Mutex
	// contains filtered or unexported fields
}

type Hash interface {
	comparable
	fmt.Stringer
}

type HeightView struct {
	Height uint32
	View   byte
}

type MessageType byte

type PreBlock[H Hash] interface {
	// Data returns PreBlock's data CNs need to exchange during PreCommit phase.
	// Data represents additional information not related to a final block signature.
	Data() []byte
	// SetData generates and sets PreBlock's data CNs need to exchange during
	// PreCommit phase.
	SetData(key PrivateKey) error
	// Verify checks if data related to PreCommit phase is correct. This method is
	// refined on PreBlock rather than on PreCommit message since PreBlock itself is
	// required for PreCommit's data verification. It's guaranteed that all
	// proposed transactions are collected by the moment of call to Verify.
	Verify(key PublicKey, data []byte) error

	// Transactions returns PreBlock's transaction list. This list may be different
	// comparing to the final set of Block's transactions.
	Transactions() []Transaction[H]
	// SetTransactions sets PreBlock's transaction list. This list may be different
	// comparing to the final set of Block's transactions.
	SetTransactions([]Transaction[H])
}

type PreCommit interface {
	// Data returns PreCommit's data that should be used for the final
	// Block construction in anti-MEV dBFT extension.
	Data() []byte
}

type PrepareRequest[H Hash] interface {
	// Timestamp returns this message's timestamp.
	Timestamp() uint64
	// Nonce is a random nonce.
	Nonce() uint64
	// TransactionHashes returns hashes of all transaction in a proposed block.
	TransactionHashes() []H
}

type PrepareResponse[H Hash] interface {
	// PreparationHash returns the hash of PrepareRequest payload
	// for this epoch.
	PreparationHash() H
}

type PrivateKey any

type PublicKey any

type RecoveryMessage[H Hash] interface {
	// AddPayload adds payload from this epoch to be recovered.
	AddPayload(p ConsensusPayload[H])
	// GetPrepareRequest returns PrepareRequest to be processed.
	GetPrepareRequest(p ConsensusPayload[H], validators []PublicKey, primary uint16) ConsensusPayload[H]
	// GetPrepareResponses returns a slice of PrepareResponse in any order.
	GetPrepareResponses(p ConsensusPayload[H], validators []PublicKey) []ConsensusPayload[H]
	// GetChangeViews returns a slice of ChangeView in any order.
	GetChangeViews(p ConsensusPayload[H], validators []PublicKey) []ConsensusPayload[H]
	// GetPreCommits returns a slice of PreCommit messages in any order.
	// If implemented on networks with no AntiMEV extension it can just
	// always return nil.
	GetPreCommits(p ConsensusPayload[H], validators []PublicKey) []ConsensusPayload[H]
	// GetCommits returns a slice of Commit in any order.
	GetCommits(p ConsensusPayload[H], validators []PublicKey) []ConsensusPayload[H]

	// PreparationHash returns has of PrepareRequest payload for this epoch.
	// It can be useful in case only PrepareResponse payloads were received.
	PreparationHash() *H
}

type RecoveryRequest interface {
	// Timestamp returns this message's timestamp.
	Timestamp() uint64
}

type Timer interface {
	// Now returns current time.
	Now() time.Time
	// Reset resets timer to the specified block height and view.
	Reset(height uint32, view byte, d time.Duration)
	// Extend extends current timer with duration d.
	Extend(d time.Duration)
	// Height returns current height set for the timer.
	Height() uint32
	// View returns current view set for the timer.
	View() byte
	// C returns channel for timer events.
	C() <-chan time.Time
}

type Transaction[H Hash] interface {
	// Hash must return cryptographic hash of the transaction.
	// Transactions which have equal hashes are considered equal.
	Hash() H
}