protofsm

type BroadcastTxn struct {
	// Tx is the transaction to broadcast.
	Tx *wire.MsgTx

	// Label is an optional label to attach to the transaction.
	Label string
}

type ConfMapper[Event any] func(*chainntnfs.TxConfirmation) Event

type DaemonAdapters interface {
	// SendMessages sends the target set of messages to the target peer.
	SendMessages(btcec.PublicKey, []lnwire.Message) error

	// BroadcastTransaction broadcasts a transaction with the target label.
	BroadcastTransaction(*wire.MsgTx, string) error

	// RegisterConfirmationsNtfn registers an intent to be notified once
	// txid reaches numConfs confirmations. We also pass in the pkScript as
	// the default light client instead needs to match on scripts created
	// in the block. If a nil txid is passed in, then not only should we
	// match on the script, but we should also dispatch once the
	// transaction containing the script reaches numConfs confirmations.
	// This can be useful in instances where we only know the script in
	// advance, but not the transaction containing it.
	//
	// TODO(roasbeef): could abstract further?
	RegisterConfirmationsNtfn(txid *chainhash.Hash, pkScript []byte,
		numConfs, heightHint uint32,
		opts ...chainntnfs.NotifierOption) (
		*chainntnfs.ConfirmationEvent, error)

	// RegisterSpendNtfn registers an intent to be notified once the target
	// outpoint is successfully spent within a transaction. The script that
	// the outpoint creates must also be specified. This allows this
	// interface to be implemented by BIP 158-like filtering.
	RegisterSpendNtfn(outpoint *wire.OutPoint, pkScript []byte,
		heightHint uint32) (*chainntnfs.SpendEvent, error)
}

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

type DaemonEventSet []DaemonEvent

type DaemonEvents interface {
	SendMsgEvent[any] | BroadcastTxn | RegisterSpend[any] |
		RegisterConf[any]
}

type EmittedEvent[Event any] struct {
	// InternalEvent is an optional internal event that is to be routed
	// back to the target state. This enables state to trigger one or many
	// state transitions without a new external event.
	InternalEvent []Event

	// ExternalEvent is an optional external event that is to be sent to
	// the daemon for dispatch. Usually, this is some form of I/O.
	ExternalEvents DaemonEventSet
}

type Environment interface {
	// Name returns the name of the environment. This is used to uniquely
	// identify the environment of related state machines.
	Name() string
}

type ErrorReporter interface {
	// ReportError is a method that's used to report an error that occurred
	// during state machine execution.
	ReportError(err error)
}

type MsgMapper[Event any] interface {
	// MapMsg maps a wire message into a FSM event. If the message is not
	// mappable, then an None is returned.
	MapMsg(msg msgmux.PeerMsg) fn.Option[Event]
}

type RegisterConf[Event any] struct {
	// Txid is the txid of the txn we want to watch the chain for.
	Txid chainhash.Hash

	// PkScript is the script that we expect to be created along with the
	// outpoint.
	PkScript []byte

	// HeightHint is a value used to give the chain scanner a hint on how
	// far back it needs to start its search.
	HeightHint uint32

	// NumConfs is the number of confirmations that the spending
	// transaction needs to dispatch an event.
	NumConfs fn.Option[uint32]

	// FullBlock is a boolean that indicates whether we want the full block
	// in the returned response. This is useful if callers want to create an
	// SPV proof for the transaction post conf.
	FullBlock bool

	// PostConfMapper is a special conf mapper, that if present, will be
	// used to map the protofsm confirmation event to a custom event.
	PostConfMapper fn.Option[ConfMapper[Event]]
}

type RegisterSpend[Event any] struct {
	// OutPoint is the outpoint on chain to watch.
	OutPoint wire.OutPoint

	// PkScript is the script that we expect to be spent along with the
	// outpoint.
	PkScript []byte

	// HeightHint is a value used to give the chain scanner a hint on how
	// far back it needs to start its search.
	HeightHint uint32

	// PostSpendEvent is a special spend mapper, that if present, will be
	// used to map the protofsm spend event to a custom event.
	PostSpendEvent fn.Option[SpendMapper[Event]]
}

type SendMsgEvent[Event any] struct {
	// TargetPeer is the peer to send the message to.
	TargetPeer btcec.PublicKey

	// Msgs is the set of messages to send to the target peer.
	Msgs []lnwire.Message

	// SendWhen implements a system for a conditional send once a special
	// send predicate has been met.
	//
	// TODO(roasbeef): contrast with usage of OnCommitFlush, etc
	SendWhen fn.Option[SendPredicate]

	// PostSendEvent is an optional event that is to be emitted after the
	// message has been sent. If a SendWhen is specified, then this will
	// only be executed after that returns true to unblock the send.
	PostSendEvent fn.Option[Event]
}

type SendPredicate = func() bool

type SpendMapper[Event any] func(*chainntnfs.SpendDetail) Event

type State[Event any, Env Environment] interface {
	// ProcessEvent takes an event and an environment, and returns a new
	// state transition. This will be iteratively called until either a
	// terminal state is reached, or no further internal events are
	// emitted.
	ProcessEvent(event Event, env Env) (*StateTransition[Event, Env], error)

	// IsTerminal returns true if this state is terminal, and false
	// otherwise.
	IsTerminal() bool

	// String returns a human readable string that represents the state.
	String() string
}

type StateMachine[Event any, Env Environment] struct {
	// contains filtered or unexported fields
}

type StateMachineCfg[Event any, Env Environment] struct {
	// ErrorReporter is used to report errors that occur during state
	// transitions.
	ErrorReporter ErrorReporter

	// Daemon is a set of adapters that will be used to bridge the FSM to
	// the daemon.
	Daemon DaemonAdapters

	// InitialState is the initial state of the state machine.
	InitialState State[Event, Env]

	// Env is the environment that the state machine will use to execute.
	Env Env

	// InitEvent is an optional event that will be sent to the state
	// machine as if it was emitted at the onset of the state machine. This
	// can be used to set up tracking state such as a txid confirmation
	// event.
	InitEvent fn.Option[DaemonEvent]

	// MsgMapper is an optional message mapper that can be used to map
	// normal wire messages into FSM events.
	MsgMapper fn.Option[MsgMapper[Event]]

	// CustomPollInterval is an optional custom poll interval that can be
	// used to set a quicker interval for tests.
	CustomPollInterval fn.Option[time.Duration]
}

type StateSubscriber[E any, F Environment] *fn.EventReceiver[State[E, F]]

type StateTransition[Event any, Env Environment] struct {
	// NextState is the next state to transition to.
	NextState State[Event, Env]

	// NewEvents is the set of events to emit.
	NewEvents fn.Option[EmittedEvent[Event]]
}