protofsm: add SpendMapper to craft custom spend events

In this commit, we add the SpendMapper which allows callers to create
custom spent events. Before this commit, the caller would be able to
have an event sent to them in the case a spend happens, but that event
wouldn't have any of the relevant spend details.

With this new addition, the caller can specify how to take a generic
spend event, and transform it into the state machine specific spend
event.

Author: Roasbeef

protofsm/daemon_events.go

@@ -4,6 +4,7 @@ import (
 	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/chaincfg/chainhash"
 	"github.com/btcsuite/btcd/wire"
+	"github.com/lightningnetwork/lnd/chainntnfs"
 	"github.com/lightningnetwork/lnd/fn"
 	"github.com/lightningnetwork/lnd/lnwire"
 )
@@ -67,8 +68,12 @@ type BroadcastTxn struct {
 // daemonSealed indicates that this struct is a DaemonEvent instance.
 func (b *BroadcastTxn) daemonSealed() {}
 
+// SpendMapper is a function that's used to map a spend notification to a
+// custom state machine event.
+type SpendMapper[Event any] func(*chainntnfs.SpendDetail) Event
+
 // RegisterSpend is used to request that a certain event is sent into the state
-// machien once the specified outpoint has been spent.
+// machine once the specified outpoint has been spent.
 type RegisterSpend[Event any] struct {
 	// OutPoint is the outpoint on chain to watch.
 	OutPoint wire.OutPoint
@@ -81,10 +86,9 @@ type RegisterSpend[Event any] struct {
 	// far back it needs to start its search.
 	HeightHint uint32
 
-	// PostSpendEvent is an event that's sent back to the requester once a
-	// transaction spending the outpoint has been confirmed in the main
-	// chain.
-	PostSpendEvent fn.Option[Event]
+	// 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]]
 }
 
 // daemonSealed indicates that this struct is a DaemonEvent instance.

protofsm/state_machine.go

@@ -465,13 +465,14 @@ func (s *StateMachine[Event, Env]) executeDaemonEvent( //nolint:funlen
 			defer s.wg.Done()
 			for {
 				select {
-				case <-spendEvent.Spend:
+				case spend := <-spendEvent.Spend:
 					// If there's a post-send event, then
 					// we'll send that into the current
 					// state now.
 					postSpend := daemonEvent.PostSpendEvent
-					postSpend.WhenSome(func(e Event) {
-						s.SendEvent(e)
+					postSpend.WhenSome(func(f SpendMapper[Event]) { //nolint:lll
+						customEvent := f(spend)
+						s.SendEvent(customEvent)
 					})
 
 					return