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 ChainTipHashProvider interface {
	// ChainTipHash returns the block hash of the current chain tip, or
	// nil when the chain is empty or the hash is unavailable.
	ChainTipHash() []byte
}

type ChainTipProvider interface {
	Tip() ochainsync.Tip
}

type ChainTipSigningProvider interface {
	WithTip(func(ochainsync.Tip) error) error
}

type ConfirmedTxRemover interface {
	RemoveTxsByHash(hashes []string)
}

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 ForgeFenceStore interface {
	// LoadLastForgedSlot returns the highest recorded slot and whether
	// any fence has been recorded yet.
	LoadLastForgedSlot() (uint64, bool, error)
	// StoreLastForgedSlot durably records slot as used. It must not
	// return until the record survives a crash.
	StoreLastForgedSlot(slot uint64) error
}

type ForgedBlockRecord struct {
	BlockHash []byte
}

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

	// Production mode configuration. Credentials must have passed
	// ValidateKESPeriod so the forger can enforce the genesis KES lifetime.
	Credentials      *PoolCredentials
	LeaderChecker    LeaderChecker
	BlockBuilder     BlockBuilder
	BlockBroadcaster BlockBroadcaster
	ConfirmedTxs     ConfirmedTxRemover
	BlockForged      BlockForgedObserver
	SlotClock        SlotClockProvider

	// OpCertLedgerView supplies the highest OpCert issue-number counter the
	// ledger has observed on chain for this pool. When non-nil, the forge
	// loop pre-flights the candidate counter against it using the same
	// era-scoped rule block application enforces (see
	// ledger/verify_opcert.go validateOpCertCounter), after leader
	// selection but before Leios work and the forge-slot fence -- a stale
	// or gapped counter is rejected there instead of reaching an
	// `AddLocalBlock` call the chain would discard anyway. Nil disables
	// the check (dev mode, embedders without ledger wiring). Requires
	// EraParams.
	OpCertLedgerView LedgerView
	// EraParams supplies the era-defining protocol parameters in effect for
	// the slot being forged, so OpCertLedgerView's counter check applies
	// the correct era-scoped rule: TPraos (Shelley-Alonzo) accepts any
	// forward counter movement, Praos (Babbage onward) additionally
	// rejects one that skips ahead of the last-seen value by more than
	// one. Required whenever OpCertLedgerView is set.
	EraParams ProtocolParamsProvider

	// ForgeFence persists the last-forged-slot fence so a restart cannot
	// sign a second block for a slot this node already used. Nil
	// disables the durable fence, which leaves only the in-memory chain
	// tip guarding against duplicate slots.
	ForgeFence ForgeFenceStore

	// 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
	// LeiosTxValidator re-validates endorser-block transactions against one
	// coherent ledger snapshot before the EB is broadcast. Production wiring
	// supplies LedgerState; nil preserves compatibility for test embedders.
	LeiosTxValidator TxValidator
	// 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
	// ForgePrimaryChainTipToleranceSlots controls how far the ledger-applied
	// tip may lag this node's own primary chain tip before the forger refuses
	// to build on it. Zero selects forgePrimaryChainTipToleranceSlots.
	ForgePrimaryChainTipToleranceSlots uint64
	// ForgeUpstreamStalenessSlots controls how far the newest block this node
	// holds may trail the corroborated upstream target before forging is
	// refused. Zero (the default) DISABLES the bound.
	//
	// It is opt-in rather than defaulted because the two sides of the
	// comparison are not measured at the same stage of the pipeline: the
	// newest block this node holds is a BLOCK, while the upstream target is
	// published when a HEADER is admitted. Between a header's admission and
	// its body being applied the two legitimately differ by the inter-block
	// gap, so a small always-on bound refuses leader slots during ordinary
	// operation -- for exponential gaps with a 20-slot mean, a bound of 5
	// fires for roughly 78% of blocks. Set it well above the expected gap, or
	// leave it off until the admitted header frontier is folded into the
	// comparison.
	ForgeUpstreamStalenessSlots uint64
	// ForgeAppliedTipStalenessSlots controls how many slots older than the
	// current slot the newest block this node holds may be before forging is
	// refused.
	//
	// There is deliberately NO default: zero disables it. A safe value depends
	// on the chain's mean block interval, which the forger cannot see, and
	// getting it wrong is expensive in the direction that matters -- at a
	// 20-slot mean interval a bound of 20 would refuse roughly a third of all
	// leader slots on a perfectly healthy chain, because block arrivals are
	// bursty rather than evenly spaced. ForgeUpstreamStalenessSlots covers the
	// same failure without that hazard by comparing against the network rather
	// than the clock. Operators who know their chain's block rate can set this
	// as a backstop for the one case the upstream comparison cannot see --
	// every peer reporting a stale target -- for which several times the mean
	// block interval is a sane starting point.
	ForgeAppliedTipStalenessSlots uint64
	// ForgeEndorserBlockStalenessSlots controls how far a corroborated Leios
	// endorser block may lead the ledger-applied tip before forging is
	// refused. Zero (the default) DISABLES the bound, and with it the whole
	// endorser-block refusal path.
	//
	// It has its own bound rather than borrowing
	// ForgePrimaryChainTipToleranceSlots, which is documented at its
	// definition as bounding a purely LOCAL block-against-block comparison
	// and defaults to 5. LeiosVerifiedEbSlot is a network-stage value: it
	// advances at leios-notify announcement time, before any header for that
	// slot has to arrive. Sharing one number would tie two unrelated risk
	// budgets together -- widening it to tolerate an endorser-block gap would
	// equally loosen the local coherence check that stops stale-parent
	// forging.
	//
	// Off by default also because the watermark is monotonic and is never
	// lowered on a fork. An endorser block corroborated for a chain this node
	// does not adopt leaves the watermark above the local tip, and an
	// always-on bound would then refuse leader slots for as long as the local
	// chain sits below that slot -- with every local indicator reading
	// healthy. Operators who enable it should set it well above the expected
	// announcement-to-apply lag.
	ForgeEndorserBlockStalenessSlots uint64
	// LeiosVerifiedEbSlot optionally reports the highest slot for which this
	// node has corroborated a Leios endorser block, which is proof a ranking
	// block exists at that slot even if its header has not arrived. Advisory
	// and monotonic; nil disables the signal.
	LeiosVerifiedEbSlot func() 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 runs its implementation's checks before AddBlock.
	// A failure prevents adoption and diffusion. The node always supplies
	// aggregate reference-script validation and, unless an operator
	// explicitly opts out via ValidateForgedBlock=false (issue #3528: fail
	// closed by default), full VRF/KES header crypto, body-hash, and
	// per-tx ledger rule validation too. Nil disables validation for
	// callers embedding this package directly.
	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 LedgerValidationResult struct {
	// Registered is true if the pool registration was found on chain.
	Registered bool
	// VRFMatched is true if Registered and the on-chain VRF key hash matched
	// the loaded VRF verification key. False otherwise, including when the VRF
	// verification key is unavailable (a seed-only VRF skey).
	VRFMatched bool
	// EraUnevaluable is non-nil when the era in effect at the requested slot
	// could not be resolved, so the era-scoped no-gap counter rule was left
	// unenforced and only the staleness rule was applied. It wraps
	// ErrOpCertEraUnevaluable. The cross-check still succeeds; callers should
	// log it where an operator will see it.
	EraUnevaluable error
}

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
	CertifiedEndorserBlockTxHashes(
		ebHash lcommon.Blake2b256,
		ebSlot uint64,
	) (hashes []string, ok bool)
	MarkEndorserBlockEmbedded(ebHash lcommon.Blake2b256, ebSlot uint64)
}

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
	// ChainTip returns the LEDGER-APPLIED tip as a point. It is a point
	// rather than a bare slot because slot alone cannot distinguish an
	// equal-slot fork: chain selection can replace the block at a slot with a
	// competing one at the same slot, and the two tips then differ only by
	// hash. Implementations must return slot and hash from a single snapshot.
	ChainTip() ocommon.Point
	// PrimaryChainTip returns this node's own primary chain tip -- the tip of
	// the primary chain, which the block builder uses as a forged block's
	// parent and which can be ahead of ChainTip while the ledger pipeline is
	// still applying blocks the node has already admitted and selected.
	// Implementations must return slot and hash from a single snapshot.
	PrimaryChainTip() ocommon.Point
	// NextSlotTime returns the wall-clock time when the next slot begins.
	NextSlotTime() (time.Time, error)
	// UpstreamTipSlot returns the latest admitted header slot from upstream
	// peers. Returns 0 if no corroborated target is available.
	UpstreamTipSlot() uint64
	// UpstreamSyncStatus reports whether a live upstream is selected and its
	// corroborated target.
	UpstreamSyncStatus() (targetSlot uint64, active bool)
}

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

type TxValidationFunc = func(
	tx ledger.Transaction,
	consumedUtxos map[utxoref.Key]struct{},
	createdUtxos map[utxoref.Key]lcommon.Utxo,
) error

type TxValidationSessionProvider interface {
	WithTxValidationSession(func(
		validate TxValidationFunc,
		stillCurrent func() bool,
	) error) error
}

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[utxoref.Key]struct{},
		createdUtxos map[utxoref.Key]lcommon.Utxo,
	) error
}