supplyverifier: rewrite supply verifier state machine

Significant rewrite of state machine events, states, and transitions.
Replaces the placeholder state machine.

Author: ffranr

tapcfg/server.go

@@ -556,6 +556,7 @@ func genServerConfig(cfg *Config, cfgLogger btclog.Logger,
 			Lnd:                   lndServices,
 			SupplyCommitView:      supplyCommitStore,
 			SupplyTreeView:        supplyTreeStore,
+			SupplySyncer:          supplySyncer,
 			GroupFetcher:          assetMintingStore,
 			IssuanceSubscriptions: universeSyncer,
 			DaemonAdapters:        lndFsmDaemonAdapters,

universe/supplyverifier/env.go

@@ -3,8 +3,10 @@ package supplyverifier
 import (
 	"context"
 	"fmt"
+	"time"
 
 	"github.com/btcsuite/btcd/wire"
+	"github.com/lightninglabs/lndclient"
 	"github.com/lightninglabs/taproot-assets/asset"
 	"github.com/lightninglabs/taproot-assets/fn"
 	"github.com/lightninglabs/taproot-assets/mssmt"
@@ -33,10 +35,17 @@ type SupplyCommitView interface {
 		assetSpec asset.Specifier,
 		localIssuerOnly bool) lfn.Result[supplycommit.PreCommits]
 
-	// SupplyCommit returns the latest supply commitment for a given asset
-	// spec.
-	SupplyCommit(ctx context.Context,
-		assetSpec asset.Specifier) supplycommit.RootCommitResp
+	// FetchStartingCommitment fetches the very first supply commitment of
+	// an asset group. If no commitment is found, it returns
+	// ErrCommitmentNotFound.
+	FetchStartingCommitment(ctx context.Context,
+		assetSpec asset.Specifier) (*supplycommit.RootCommitment, error)
+
+	// FetchLatestCommitment fetches the latest supply commitment of an
+	// asset group. If no commitment is found, it returns
+	// ErrCommitmentNotFound.
+	FetchLatestCommitment(ctx context.Context,
+		assetSpec asset.Specifier) (*supplycommit.RootCommitment, error)
 
 	// FetchCommitmentByOutpoint fetches a supply commitment by its outpoint
 	// and group key. If no commitment is found, it returns
@@ -53,12 +62,6 @@ type SupplyCommitView interface {
 		spentOutpoint wire.OutPoint) (*supplycommit.RootCommitment,
 		error)
 
-	// FetchStartingCommitment fetches the very first supply commitment of
-	// an asset group. If no commitment is found, it returns
-	// ErrCommitmentNotFound.
-	FetchStartingCommitment(ctx context.Context,
-		assetSpec asset.Specifier) (*supplycommit.RootCommitment, error)
-
 	// InsertSupplyCommit inserts a supply commitment into the database.
 	InsertSupplyCommit(ctx context.Context,
 		assetSpec asset.Specifier, commit supplycommit.RootCommitment,
@@ -100,6 +103,29 @@ type Environment struct {
 	// pre-commitments.
 	SupplyCommitView SupplyCommitView
 
+	// SupplyTreeView is used to fetch supply leaves by height.
+	SupplyTreeView SupplyTreeView
+
+	// AssetLookup is used to look up asset information such as asset groups
+	// and asset metadata.
+	AssetLookup supplycommit.AssetLookup
+
+	// Lnd is a collection of useful LND clients.
+	Lnd *lndclient.LndServices
+
+	// GroupFetcher is used to fetch asset groups.
+	GroupFetcher tapgarden.GroupFetcher
+
+	// SupplySyncer is used to retrieve supply commitments from a universe
+	// server.
+	SupplySyncer SupplySyncer
+
+	// SpendSyncDelay is the wait time after detecting a spend before
+	// starting the sync of the corresponding supply commitment. The delay
+	// allows the peer node to submit the new commitment to the universe
+	// server and for it to be available for retrieval.
+	SpendSyncDelay time.Duration
+
 	// ErrChan is the channel that is used to send errors to the caller.
 	ErrChan chan<- error
 

universe/supplyverifier/events.go

@@ -0,0 +1,80 @@
+package supplyverifier
+
+import (
+	"time"
+
+	"github.com/btcsuite/btcd/wire"
+	"github.com/lightninglabs/taproot-assets/fn"
+	"github.com/lightninglabs/taproot-assets/universe/supplycommit"
+	"github.com/lightningnetwork/lnd/chainntnfs"
+	"github.com/lightningnetwork/lnd/protofsm"
+)
+
+// Event is a special interface used to create the equivalent of a sum-type, but
+// using a "sealed" interface.
+type Event interface {
+	eventSealed()
+}
+
+// FsmEvent is a type alias for the event type of the supply verifier state
+// machine.
+type FsmEvent = protofsm.EmittedEvent[Event]
+
+// InitEvent is the first event that is sent to the state machine.
+type InitEvent struct{}
+
+// eventSealed is a special method that is used to seal the interface.
+func (i *InitEvent) eventSealed() {}
+
+// SyncVerifyEvent is sent to SyncVerifyState to prompt it to sync-verify
+// starting from the given outpoint, or from scratch if no outpoint is given.
+type SyncVerifyEvent struct {
+	// SpentCommitOutpoint is an optional outpoint that was spent which
+	// triggered the need to start syncing from the beginning. If this is
+	// None, then we will sync from the first supply commitment.
+	SpentCommitOutpoint fn.Option[wire.OutPoint]
+}
+
+// eventSealed is a special method that is used to seal the interface.
+func (e *SyncVerifyEvent) eventSealed() {}
+
+// WatchOutputsEvent is an event that carries the set of outputs to watch.
+type WatchOutputsEvent struct {
+	// PreCommits is the set of all pre-commitments that should be watched
+	// for a spend.
+	PreCommits supplycommit.PreCommits
+
+	// SupplyCommit is the latest known supply commitment that should be
+	// watched for a spend.
+	SupplyCommit *supplycommit.RootCommitment
+}
+
+// eventSealed is a special method that is used to seal the interface.
+func (e *WatchOutputsEvent) eventSealed() {}
+
+// SpendEvent is sent in response to an intent to be notified of a spend of an
+// outpoint.
+type SpendEvent struct {
+	// SpendDetail is the details of the spend that was observed on-chain.
+	SpendDetail *chainntnfs.SpendDetail
+
+	// PreCommitments is the set of all pre-commitments that were being
+	// watched for a spend.
+	PreCommitments []supplycommit.PreCommitment
+
+	// SpentPreCommitment is the pre-commitment that was spent. This will
+	// be non-nil only if the spent output was a pre-commitment.
+	SpentPreCommitment *supplycommit.PreCommitment
+
+	// SpentSupplyCommitment is the supply commitment that was spent. This
+	// will be non-nil only if the spent output was a supply commitment.
+	SpentSupplyCommitment *supplycommit.RootCommitment
+
+	// WatchStartTimestamp records when monitoring for this spend began.
+	// It is used to calculate the delay before syncing, giving the issuer
+	// time to publish the new supply commitment.
+	WatchStartTimestamp time.Time
+}
+
+// eventSealed is a special method that is used to seal the interface.
+func (s *SpendEvent) eventSealed() {}

universe/supplyverifier/manager.go

@@ -22,6 +22,13 @@ import (
 const (
 	// DefaultTimeout is the context guard default timeout.
 	DefaultTimeout = 30 * time.Second
+
+	// DefaultSpendSyncDelay is the default delay to wait after a spend
+	// notification is received before starting the sync of the
+	// corresponding supply commitment. The delay allows the peer node to
+	// submit the new commitment to the universe server and for it to be
+	// available for retrieval
+	DefaultSpendSyncDelay = 5 * time.Second
 )
 
 // DaemonAdapters is a wrapper around the protofsm.DaemonAdapters interface
@@ -372,11 +379,20 @@ func (m *Manager) Stop() error {
 func (m *Manager) startAssetSM(ctx context.Context,
 	assetSpec asset.Specifier) (*StateMachine, error) {
 
+	log.Infof("Starting supply verifier state machine (asset=%s)",
+		assetSpec.String())
+
 	// If the state machine is not found, create a new one.
 	env := &Environment{
 		AssetSpec:        assetSpec,
 		Chain:            m.cfg.Chain,
 		SupplyCommitView: m.cfg.SupplyCommitView,
+		SupplyTreeView:   m.cfg.SupplyTreeView,
+		AssetLookup:      m.cfg.AssetLookup,
+		Lnd:              m.cfg.Lnd,
+		GroupFetcher:     m.cfg.GroupFetcher,
+		SupplySyncer:     m.cfg.SupplySyncer,
+		SpendSyncDelay:   DefaultSpendSyncDelay,
 		ErrChan:          m.cfg.ErrChan,
 		QuitChan:         m.Quit,
 	}
@@ -386,9 +402,9 @@ func (m *Manager) startAssetSM(ctx context.Context,
 
 	fsmCfg := protofsm.StateMachineCfg[Event, *Environment]{
 		ErrorReporter: &errorReporter,
-		// TODO(ffranr): Set InitialState here.
-		Env:    env,
-		Daemon: m.cfg.DaemonAdapters,
+		InitialState:  &InitState{},
+		Env:           env,
+		Daemon:        m.cfg.DaemonAdapters,
 	}
 	newSm := protofsm.NewStateMachine[Event, *Environment](fsmCfg)
 
@@ -436,6 +452,9 @@ func (m *Manager) fetchStateMachine(assetSpec asset.Specifier) (*StateMachine,
 		// the cache with a new running instance.
 	}
 
+	log.Debugf("Creating new supply verifier state machine for "+
+		"group: %x", groupKey.SerializeCompressed())
+
 	ctx, cancel := m.WithCtxQuitNoTimeout()
 	defer cancel()
 

universe/supplyverifier/states.go

@@ -12,17 +12,6 @@ var (
 	ErrInvalidStateTransition = fmt.Errorf("invalid state transition")
 )
 
-// Event is a special interface used to create the equivalent of a sum-type, but
-// using a "sealed" interface.
-type Event interface {
-	eventSealed()
-}
-
-// Events is a special type constraint that enumerates all the possible protocol
-// events.
-type Events interface {
-}
-
 // StateTransition is the StateTransition type specific to the supply verifier
 // state machine.
 type StateTransition = protofsm.StateTransition[Event, *Environment]
@@ -36,6 +25,59 @@ type State interface {
 	String() string
 }
 
+// InitState is the starting state of the machine. In this state we decide
+// whether to start syncing immediately or wait for spends before syncing.
+type InitState struct {
+}
+
+// stateSealed is a special method that is used to seal the interface.
+func (s *InitState) stateSealed() {}
+
+// IsTerminal returns true if the target state is a terminal state.
+func (s *InitState) IsTerminal() bool {
+	return false
+}
+
+// String returns the name of the state.
+func (s *InitState) String() string {
+	return "InitState"
+}
+
+// SyncVerifyState is the state where we sync proofs related to a
+// supply commitment transaction.
+type SyncVerifyState struct{}
+
+// stateSealed is a special method that is used to seal the interface.
+func (s *SyncVerifyState) stateSealed() {}
+
+// IsTerminal returns true if the target state is a terminal state.
+func (s *SyncVerifyState) IsTerminal() bool {
+	return false
+}
+
+// String returns the name of the state.
+func (s *SyncVerifyState) String() string {
+	return "SyncVerifyState"
+}
+
+// WatchOutputsState waits for one of the watched outputs to be spent.
+// If an output is already spent, we transition immediately.
+// This state avoids wasted sync polling of universe servers.
+type WatchOutputsState struct{}
+
+// stateSealed is a special method that is used to seal the interface.
+func (s *WatchOutputsState) stateSealed() {}
+
+// IsTerminal returns true if the target state is a terminal state.
+func (s *WatchOutputsState) IsTerminal() bool {
+	return false
+}
+
+// String returns the name of the state.
+func (s *WatchOutputsState) String() string {
+	return "WatchOutputsState"
+}
+
 // StateMachine is a state machine that handles verifying the on-chain supply
 // commitment for a given asset.
 type StateMachine = protofsm.StateMachine[Event, *Environment]
@@ -47,16 +89,6 @@ type Config = protofsm.StateMachineCfg[Event, *Environment]
 // FsmState is a type alias for the state of the supply verifier state machine.
 type FsmState = protofsm.State[Event, *Environment]
 
-// FsmEvent is a type alias for the event type of the supply verifier state
-// machine.
-type FsmEvent = protofsm.EmittedEvent[Event]
-
 // StateSub is a type alias for the state subscriber of the supply verifier
 // state machine.
 type StateSub = protofsm.StateSubscriber[Event, *Environment]
-
-// InitEvent is the first event that is sent to the state machine.
-type InitEvent struct{}
-
-// eventSealed is a special method that is used to seal the interface.
-func (i *InitEvent) eventSealed() {}