forging

type BlockBroadcaster interface {
	// AddBlock adds a block to the local chain and propagates to peers.
	AddBlock(block ledger.Block, cbor []byte) error
}

type BlockBuilder interface {
	// BuildBlock creates a new block for the given slot.
	// Returns the block and its CBOR encoding.
	BuildBlock(slot uint64, kesPeriod uint64) (ledger.Block, []byte, error)
}

type BlockBuilderConfig struct {
	Logger          *slog.Logger
	Mempool         MempoolProvider
	PParamsProvider ProtocolParamsProvider
	ChainTip        ChainTipProvider
	EpochNonce      EpochNonceProvider
	Credentials     *PoolCredentials
	// TxValidator optionally re-validates each transaction against
	// the current ledger state before including it in a block.
	// When nil, ledger-level re-validation is skipped (but
	// intra-block double-spend detection still applies).
	TxValidator TxValidator
}

type BlockForgedObserver func(
	block ledger.Block,
	cbor []byte,
	latency time.Duration,
)

type BlockForger struct {
	// contains filtered or unexported fields
}

type BlockValidator interface {
	ValidateForgedBlock(block ledger.Block, blockCbor []byte) error
}

type ChainTipProvider interface {
	Tip() ochainsync.Tip
}

type DefaultBlockBuilder struct {
	// contains filtered or unexported fields
}

type EndorserBlockBroadcaster interface {
	BroadcastEndorserBlock(
		slot uint64,
		hash []byte,
		cbor []byte,
		txBodies [][]byte,
	) error
}

type EpochNonceProvider interface {
	// CurrentEpoch returns the current epoch number.
	CurrentEpoch() uint64
	// EpochForSlot returns the epoch containing the given slot.
	EpochForSlot(slot uint64) (uint64, error)
	// EpochNonce returns the nonce for the given epoch.
	EpochNonce(epoch uint64) []byte
}

type ForgedBlockRecord struct {
	BlockHash []byte
}

type ForgerConfig struct {
	Mode         Mode
	Logger       *slog.Logger
	SlotDuration time.Duration

	// Production mode configuration
	Credentials      *PoolCredentials
	LeaderChecker    LeaderChecker
	BlockBuilder     BlockBuilder
	BlockBroadcaster BlockBroadcaster
	BlockForged      BlockForgedObserver
	SlotClock        SlotClockProvider

	// LeiosProduceChecker enables EB forging when non-nil. Requires
	// LeiosEBBroadcaster and LeiosMempool to also be set.
	LeiosProduceChecker LeiosProduceChecker
	// LeiosEBBroadcaster propagates locally-forged EBs to peers.
	LeiosEBBroadcaster EndorserBlockBroadcaster
	// LeiosMempool provides transactions for EB building. May reuse the
	// same MempoolProvider as the RB builder.
	LeiosMempool MempoolProvider
	// LeiosCertificateProvider supplies certified EBs for Dijkstra CertRBs.
	LeiosCertificateProvider LeiosCertificateProvider
	// LeiosParentAnnouncementProvider supplies the EB hash announced by the
	// parent RB so CertRB selection cannot certify an unrelated EB.
	LeiosParentAnnouncementProvider LeiosParentAnnouncementProvider

	// ForgeSyncToleranceSlots controls how far the local chain can lag the
	// upstream tip before forging is skipped. Zero uses the default.
	ForgeSyncToleranceSlots uint64
	// ForgeStaleGapThresholdSlots controls when to log an error if the
	// chain tip is far ahead of the slot clock. Zero uses the default.
	ForgeStaleGapThresholdSlots uint64

	// BlockValidator, when non-nil, validates the forged block (VRF/KES
	// header crypto, body-hash consistency, per-tx ledger rules) before
	// AddBlock is called. A validation failure drops the block without
	// adopting or diffusing it. Nil disables self-validation (default).
	BlockValidator BlockValidator

	// Prometheus metrics registry (optional)
	PromRegistry prometheus.Registerer
}

type LeaderChecker interface {
	// ShouldProduceBlock returns true if this pool is the leader for the slot.
	ShouldProduceBlock(slot uint64) bool
	// NextLeaderSlot returns the next slot where this pool is leader.
	NextLeaderSlot(fromSlot uint64) (uint64, bool)
}

type LedgerView interface {
	// PoolRegistrationVRFKeyHash returns the VRF key hash recorded on
	// the most recent active pool registration certificate for poolID.
	// found is false when the pool has no on-chain registration yet.
	PoolRegistrationVRFKeyHash(poolID [28]byte) (vrfKeyHash [32]byte, found bool, err error)
	// LatestOpCertSequence returns the highest opcert IssueNumber
	// observed on chain for poolID. found is false when on-chain
	// counter tracking is not implemented or this pool has never
	// minted a block.
	LatestOpCertSequence(poolID [28]byte) (sequence uint64, found bool, err error)
}

type LeiosBlockBuilder interface {
	BuildBlockWithLeios(
		slot uint64,
		kesPeriod uint64,
		leios LeiosBlockData,
	) (ledger.Block, []byte, error)
}

type LeiosBlockData struct {
	Announcement *LeiosEndorserBlockAnnouncement
	Certificate  *lcommon.LeiosEbCertificate
}

type LeiosCertificateProvider interface {
	EligibleCertifiedEndorserBlocks() []LeiosCertifiedEndorserBlock
	MarkEndorserBlockEmbedded(ebHash lcommon.Blake2b256)
}

type LeiosCertifiedEndorserBlock struct {
	SlotNo            uint64
	EndorserBlockHash lcommon.Blake2b256
	Certificate       *lcommon.LeiosEbCertificate
	AnnouncingRbHash  lcommon.Blake2b256
}

type LeiosEndorserBlockAnnouncement struct {
	Hash lcommon.Blake2b256
	Size uint64
}

type LeiosParentAnnouncementProvider interface {
	ParentLeiosAnnouncement() (
		lcommon.Blake2b256,
		lcommon.Blake2b256,
		bool,
		error,
	)
}

type LeiosProduceChecker interface {
	MayProduceEndorserBlock(slot uint64) (allowed bool, reason string, err error)
}

type MempoolProvider interface {
	Transactions() []MempoolTransaction
}

type MempoolTransaction struct {
	Hash string
	Cbor []byte
	Type uint
}

type Mode int

type OpCert struct {
	KESVKey     []byte // KES verification key (32 bytes)
	IssueNumber uint64 // Certificate sequence number
	KESPeriod   uint64 // KES period when certificate was created
	Signature   []byte // Cold key signature (64 bytes)
	ColdVKey    []byte // Cold verification key (32 bytes)
}

type PoolCredentials struct {
	// contains filtered or unexported fields
}

type ProtocolParamsProvider interface {
	GetCurrentPParams() lcommon.ProtocolParameters
	// ProtocolParamsForSlot returns the pparams that should govern a
	// block forged at the given slot. When the slot is in an epoch
	// beyond a scheduled fork that has not yet been applied to the
	// in-memory ledger state, the returned pparams are the
	// post-fork pparams. The forger uses this to produce
	// era-correct blocks at fork boundaries.
	ProtocolParamsForSlot(slot uint64) lcommon.ProtocolParameters
}

type SlotBattleEvent struct {
	// Slot is the slot number where the battle occurred
	Slot uint64
	// LocalBlockHash is the hash of our locally forged block (if any)
	LocalBlockHash []byte
	// RemoteBlockHash is the hash of the competing block from peers
	RemoteBlockHash []byte
	// Won indicates whether our local block was selected for the chain
	Won bool
}

type SlotClockProvider interface {
	// CurrentSlot returns the current slot number based on wall-clock time.
	CurrentSlot() (uint64, error)
	// SlotsPerKESPeriod returns the number of slots in a KES period.
	SlotsPerKESPeriod() uint64
	// ChainTipSlot returns the slot number of the current chain tip.
	ChainTipSlot() uint64
	// NextSlotTime returns the wall-clock time when the next slot begins.
	NextSlotTime() (time.Time, error)
	// UpstreamTipSlot returns the latest known tip slot from upstream peers.
	// Returns 0 if no upstream tip is known.
	UpstreamTipSlot() uint64
}

type SlotTracker struct {
	// contains filtered or unexported fields
}

type TxValidator interface {
	ValidateTx(tx ledger.Transaction) error
	// ValidateTxWithOverlay re-validates with intra-block UTxO state:
	// consumedUtxos are inputs spent by earlier txs in the same block
	// (double-spend guard), createdUtxos are outputs produced by those
	// txs (enables spending intra-block outputs).
	ValidateTxWithOverlay(
		tx ledger.Transaction,
		consumedUtxos map[string]struct{},
		createdUtxos map[string]lcommon.Utxo,
	) error
}