multi: stage boarding actor client

baselib/protofsm/transition_table.go

@@ -0,0 +1,187 @@
+package protofsm
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+)
+
+// TransitionEntry represents a single state transition with type safety.
+// This provides at-a-glance visibility into how states transition in response
+// to events, including any outbox messages emitted.
+type TransitionEntry[S, E, M any] struct {
+	// Event is the event that triggers this transition.
+	Event E
+
+	// ToState is the destination state after this transition.
+	ToState S
+
+	// Description explains why this transition occurs and any important
+	// context about validation or security checks.
+	Description string
+
+	// EmitsOutbox contains the strongly-typed outbox messages emitted
+	// during this transition. These messages flow between FSMs via gRPC.
+	EmitsOutbox []M
+
+	// IsTerminal indicates the ToState is a terminal state that only
+	// self-loops.
+	IsTerminal bool
+}
+
+// StateTransitions holds all transitions from a single state.
+type StateTransitions[S, E, M any] struct {
+	// FromState is the source state for these transitions.
+	FromState S
+
+	// Transitions is the list of possible transitions from this state.
+	Transitions []TransitionEntry[S, E, M]
+}
+
+// TransitionTable defines all valid state transitions for a state machine.
+// This provides complete, at-a-glance visibility into the state machine
+// behavior and serves as both documentation and a validation target for tests.
+//
+// This is intended to be used as a static compile-time structure.
+type TransitionTable[S, E, M any] struct {
+	// MachineName identifies which state machine this table describes.
+	MachineName string
+
+	// States contains the transitions for each state in the machine.
+	States []StateTransitions[S, E, M]
+}
+
+// GetTransitionsFrom returns all possible transitions from the given state.
+// This allows callers to quickly see what events a state can handle and
+// where they lead.
+func (tt *TransitionTable[S, E, M]) GetTransitionsFrom(
+	fromState S) []TransitionEntry[S, E, M] {
+
+	fromType := reflect.TypeOf(fromState)
+	for _, st := range tt.States {
+		if reflect.TypeOf(st.FromState) == fromType {
+			return st.Transitions
+		}
+	}
+
+	return nil
+}
+
+// GetTransitionsFor returns all transitions triggered by a specific event type
+// across all states. The result includes the source state for context.
+func (tt *TransitionTable[S, E, M]) GetTransitionsFor(
+	event E) []TransitionWithSource[S, E, M] {
+
+	var result []TransitionWithSource[S, E, M]
+	eventType := reflect.TypeOf(event)
+
+	for _, st := range tt.States {
+		for _, t := range st.Transitions {
+			if reflect.TypeOf(t.Event) == eventType {
+				result = append(result, TransitionWithSource[S, E, M]{
+					FromState:       st.FromState,
+					TransitionEntry: t,
+				})
+			}
+		}
+	}
+
+	return result
+}
+
+// TransitionWithSource pairs a transition with its source state.
+type TransitionWithSource[S, E, M any] struct {
+	// FromState is the state this transition originates from.
+	FromState S
+
+	// TransitionEntry contains the transition details.
+	TransitionEntry[S, E, M]
+}
+
+// GetTerminalTransitions returns all transitions that lead to terminal states.
+func (tt *TransitionTable[S, E, M]) GetTerminalTransitions() []TransitionWithSource[
+	S, E, M] {
+
+	var terminals []TransitionWithSource[S, E, M]
+
+	for _, st := range tt.States {
+		for _, t := range st.Transitions {
+			if t.IsTerminal {
+				terminals = append(
+					terminals, TransitionWithSource[S, E, M]{
+						FromState:       st.FromState,
+						TransitionEntry: t,
+					},
+				)
+			}
+		}
+	}
+
+	return terminals
+}
+
+// RenderMarkdown generates a markdown table showing all transitions.
+func (tt *TransitionTable[S, E, M]) RenderMarkdown() string {
+	var sb strings.Builder
+
+	sb.WriteString(fmt.Sprintf("# %s State Transitions\n\n",
+		tt.MachineName))
+	sb.WriteString("| From State | Event | To State | " +
+		"Outbox Messages | Description |\n")
+	sb.WriteString("|------------|-------|----------|" +
+		"-----------------|-------------|\n")
+
+	for _, st := range tt.States {
+		fromStateName := trimPackagePrefix(
+			reflect.TypeOf(st.FromState).String(),
+		)
+
+		for _, t := range st.Transitions {
+			event := trimPackagePrefix(
+				reflect.TypeOf(t.Event).String(),
+			)
+			toStateName := trimPackagePrefix(
+				reflect.TypeOf(t.ToState).String(),
+			)
+
+			terminal := ""
+			if t.IsTerminal {
+				terminal = " (terminal)"
+			}
+
+			outbox := ""
+			if len(t.EmitsOutbox) > 0 {
+				var msgTypes []string
+				for _, msg := range t.EmitsOutbox {
+					msgType := trimPackagePrefix(
+						reflect.TypeOf(msg).String(),
+					)
+					msgTypes = append(msgTypes, msgType)
+				}
+				outbox = strings.Join(msgTypes, ", ")
+			}
+
+			sb.WriteString(fmt.Sprintf(
+				"| %s | %s | %s%s | %s | %s |\n",
+				fromStateName, event, toStateName, terminal,
+				outbox, t.Description,
+			))
+		}
+	}
+
+	return sb.String()
+}
+
+// trimPackagePrefix removes common package prefixes from type names for
+// cleaner output.
+func trimPackagePrefix(typeName string) string {
+	// Remove pointer prefix if present.
+	typeName = strings.TrimPrefix(typeName, "*")
+
+	// Find the last dot and take everything after it.
+	if idx := strings.LastIndex(typeName, "."); idx != -1 {
+		return typeName[idx+1:]
+	}
+
+	return typeName
+}

chainsource/messages.go

@@ -271,6 +271,10 @@ type ConfirmationEvent struct {
 	// NumConfs is the actual number of confirmations at the time of this
 	// event.
 	NumConfs uint32
+
+	// Tx is the confirmed transaction. This allows consumers to inspect
+	// transaction outputs without making additional chain queries.
+	Tx *wire.MsgTx
 }
 
 // MessageType returns the message type identifier for logging and debugging.

go.mod

@@ -19,6 +19,7 @@ require (
 	github.com/lib/pq v1.10.9
 	github.com/lightninglabs/darepo-client/baselib v0.0.0-00010101000000-000000000000
 	github.com/lightninglabs/lndclient v1.0.1-0.20251120145443-a0342758fc5b
+	github.com/lightninglabs/taproot-assets v0.7.0
 	github.com/lightninglabs/taproot-assets/taprpc v1.0.11
 	github.com/lightningnetwork/lnd v0.20.0-beta
 	github.com/lightningnetwork/lnd/clock v1.1.1
@@ -36,11 +37,14 @@ require (
 	dario.cat/mergo v1.0.1 // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/NebulousLabs/fastrand v0.0.0-20181203155948-6fb6489aac4e // indirect
+	github.com/NebulousLabs/go-upnp v0.0.0-20180202185039-29b680b06c82 // indirect
 	github.com/Nvveen/Gotty v0.0.0-20120604004816-cd527374f1e5 // indirect
+	github.com/Yawning/aez v0.0.0-20211027044916-e49e68abd344 // indirect
 	github.com/aead/chacha20 v0.0.0-20180709150244-8b13a72661da // indirect
 	github.com/aead/siphash v1.0.1 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
-	github.com/btcsuite/btcd/btcutil/psbt v1.1.8 // indirect
+	github.com/btcsuite/btcd/btcutil/psbt v1.1.10 // indirect
 	github.com/btcsuite/btcd/v2transport v1.0.1 // indirect
 	github.com/btcsuite/btclog v0.0.0-20241003133417-09c4e92e319c // indirect
 	github.com/btcsuite/btcwallet/wallet/txauthor v1.3.5 // indirect
@@ -55,6 +59,7 @@ require (
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/containerd/continuity v0.4.5 // indirect
 	github.com/coreos/go-semver v0.3.0 // indirect
+	github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf // indirect
 	github.com/coreos/go-systemd/v22 v22.5.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/decred/dcrd/crypto/blake256 v1.1.0 // indirect
@@ -66,7 +71,7 @@ require (
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/fergusstrange/embedded-postgres v1.25.0 // indirect
-	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
@@ -77,7 +82,7 @@ require (
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/websocket v1.5.0 // indirect
-	github.com/grpc-ecosystem/go-grpc-middleware v1.3.0 // indirect
+	github.com/grpc-ecosystem/go-grpc-middleware v1.4.0 // indirect
 	github.com/grpc-ecosystem/go-grpc-prometheus v1.2.0 // indirect
 	github.com/grpc-ecosystem/grpc-gateway v1.16.0 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.20.0 // indirect
@@ -90,7 +95,10 @@ require (
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/pgtype v1.14.4 // indirect
 	github.com/jackc/pgx/v4 v4.18.3 // indirect
+	github.com/jackc/puddle v1.3.0 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/jackpal/gateway v1.0.5 // indirect
+	github.com/jackpal/go-nat-pmp v0.0.0-20170405195558-28a68d0c24ad // indirect
 	github.com/jessevdk/go-flags v1.4.0 // indirect
 	github.com/jonboulle/clockwork v0.2.2 // indirect
 	github.com/jrick/logrotate v1.1.2 // indirect
@@ -99,9 +107,11 @@ require (
 	github.com/kkdai/bstream v1.0.0 // indirect
 	github.com/klauspost/compress v1.17.9 // indirect
 	github.com/lightninglabs/gozmq v0.0.0-20191113021534-d20a764486bf // indirect
+	github.com/lightninglabs/lightning-node-connect/hashmailrpc v1.0.3 // indirect
 	github.com/lightninglabs/neutrino v0.16.2-0.20250820152345-800584718688 // indirect
 	github.com/lightninglabs/neutrino/cache v1.1.2 // indirect
 	github.com/lightningnetwork/lightning-onion v1.2.1-0.20240815225420-8b40adf04ab9 // indirect
+	github.com/lightningnetwork/lnd/cert v1.2.2 // indirect
 	github.com/lightningnetwork/lnd/healthcheck v1.2.6 // indirect
 	github.com/lightningnetwork/lnd/kvdb v1.4.16 // indirect
 	github.com/lightningnetwork/lnd/queue v1.1.1 // indirect
@@ -111,8 +121,8 @@ require (
 	github.com/lightningnetwork/lnd/tor v1.1.6 // indirect
 	github.com/ltcsuite/ltcd v0.0.0-20190101042124-f37f8bf35796 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/matttproud/golang_protobuf_extensions v1.0.1 // indirect
-	github.com/miekg/dns v1.1.43 // indirect
+	github.com/matttproud/golang_protobuf_extensions v1.0.2-0.20181231171920-c182affec369 // indirect
+	github.com/miekg/dns v1.1.50 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
 	github.com/moby/sys/user v0.3.0 // indirect
 	github.com/moby/term v0.5.0 // indirect
@@ -124,10 +134,10 @@ require (
 	github.com/opencontainers/runc v1.2.8 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/prometheus/client_golang v1.11.1 // indirect
+	github.com/prometheus/client_golang v1.14.0 // indirect
 	github.com/prometheus/client_model v0.3.0 // indirect
-	github.com/prometheus/common v0.26.0 // indirect
-	github.com/prometheus/procfs v0.6.0 // indirect
+	github.com/prometheus/common v0.37.0 // indirect
+	github.com/prometheus/procfs v0.8.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rogpeppe/fastuuid v1.2.0 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
@@ -136,11 +146,13 @@ require (
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7 // indirect
 	github.com/tmc/grpc-websocket-proxy v0.0.0-20201229170055-e5319fda7802 // indirect
+	github.com/tv42/zbase32 v0.0.0-20160707012821-501572607d02 // indirect
 	github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
 	github.com/xi2/xz v0.0.0-20171230120015-48954b6210f8 // indirect
 	github.com/xiang90/probing v0.0.0-20190116061207-43a291ad63a2 // indirect
+	gitlab.com/yawning/bsaes.git v0.0.0-20190805113838-0a714cd429ec // indirect
 	go.etcd.io/bbolt v1.4.3 // indirect
 	go.etcd.io/etcd/api/v3 v3.5.12 // indirect
 	go.etcd.io/etcd/client/pkg/v3 v3.5.12 // indirect
@@ -151,23 +163,25 @@ require (
 	go.etcd.io/etcd/server/v3 v3.5.12 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.49.0 // indirect
-	go.opentelemetry.io/otel v1.35.0 // indirect
+	go.opentelemetry.io/otel v1.37.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.29.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.20.0 // indirect
-	go.opentelemetry.io/otel/metric v1.35.0 // indirect
-	go.opentelemetry.io/otel/sdk v1.35.0 // indirect
-	go.opentelemetry.io/otel/trace v1.35.0 // indirect
+	go.opentelemetry.io/otel/metric v1.37.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.37.0 // indirect
+	go.opentelemetry.io/otel/trace v1.37.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.3.1 // indirect
-	go.uber.org/atomic v1.7.0 // indirect
+	go.uber.org/atomic v1.10.0 // indirect
 	go.uber.org/multierr v1.6.0 // indirect
-	go.uber.org/zap v1.17.0 // indirect
-	golang.org/x/crypto v0.37.0 // indirect
-	golang.org/x/net v0.39.0 // indirect
+	go.uber.org/zap v1.23.0 // indirect
+	golang.org/x/crypto v0.44.0 // indirect
+	golang.org/x/mod v0.30.0 // indirect
+	golang.org/x/net v0.47.0 // indirect
 	golang.org/x/sync v0.18.0 // indirect
-	golang.org/x/sys v0.36.0 // indirect
-	golang.org/x/term v0.31.0 // indirect
-	golang.org/x/text v0.24.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/term v0.37.0 // indirect
+	golang.org/x/text v0.31.0 // indirect
 	golang.org/x/time v0.5.0 // indirect
+	golang.org/x/tools v0.39.0 // indirect
 	google.golang.org/genproto v0.0.0-20240213162025-012b6fc9bca9 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20250324211829-b45e905df463 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250324211829-b45e905df463 // indirect