htlcswitch: add InitAttempt for idempotent external dispatch

docs/release-notes/release-notes-0.21.0.md

@@ -48,6 +48,17 @@
 
 ## Functional Enhancements
 
+* Introduced a new `AttemptStore` interface within `htlcswitch`, and expanded
+  its `kvdb` implementation, `networkResultStore`. A [new `InitAttempt` method](https://github.com/lightningnetwork/lnd/pull/10049),
+  which serves as a "durable write of intent" or "write-ahead log" to checkpoint
+  an attempt in a new `PENDING` state prior to dispatch, now provides the
+  foundational durable storage required for external tracking of the HTLC
+  attempt lifecycle. This is a preparatory step that enables a future
+  idempotent `switchrpc.SendOnion` RPC, which will offer "at most once"
+  processing of htlc dispatch requests for remote clients. Care was taken to
+  avoid modifications to the existing flows for dispatching local payments,
+  preserving the existing battle-tested logic.
+
 ## RPC Additions
 
 * [Added support for coordinator-based MuSig2 signing

htlcswitch/interfaces.go

@@ -530,3 +530,71 @@ type AuxTrafficShaper interface {
 	// meaning that it's from a custom channel.
 	IsCustomHTLC(htlcRecords lnwire.CustomRecords) bool
 }
+
+// AttemptStore defines the interface for initializing, managing, and tracking
+// the lifecycle of HTLC payment attempts. It supports both local and remote
+// payment lifecycle controllers.
+//
+// NOTE: This store is designed to be managed by a *single* logical dispatcher
+// (e.g., a ChannelRouter instance, or a remote payment orchestrator) at a time
+// to avoid collisions of attemptIDs and ensure an unambiguous source of truth
+// for payment state. Concurrent usage by multiple dispatchers is NOT supported.
+type AttemptStore interface {
+	// InitAttempt persists the intent to dispatch a payment attempt,
+	// creating a durable record that serves as an idempotency key. This
+	// method should be called before the HTLC is dispatched to the network.
+	//
+	// NOTE: This method provides a guarantee that only one HTLC can be
+	// initialized for a given attempt ID until the ID is explicitly cleaned
+	// from the store.
+	InitAttempt(attemptID uint64) error
+
+	// StoreResult stores the result of a given payment attempt (identified
+	// by attemptID). This will be called when a result is received from the
+	// network.
+	StoreResult(attemptID uint64, result *networkResult) error
+
+	// FailPendingAttempt transitions an initialized attempt from an
+	// initialized to a failed state and records the provided reason. This
+	// is the synchronous rollback mechanism for attempts that fail before
+	// being committed to the forwarding engine. It returns an error if the
+	// underlying storage fails.
+	FailPendingAttempt(attemptID uint64, reason *LinkError) error
+
+	// FetchPendingAttempts returns a list of all attempt IDs that are
+	// currently in the pending state.
+	//
+	// NOTE: This function is primarily used by the Switch's startup logic
+	// to identify and clean up internally orphaned payment attempts. These
+	// occur when an attempt is initialized via InitAttempt but a crash
+	// prevents its full dispatch to the network (e.g., between InitAttempt
+	// and CommitCircuits). By fetching these pending attempts, the Switch
+	// can transition their state to FAILED, preventing external callers
+	// from indefinitely hanging on GetAttemptResult for an un-dispatched
+	// attempt.
+	FetchPendingAttempts() ([]uint64, error)
+
+	// GetResult returns the network result for the specified attempt ID if
+	// it's available.
+	//
+	// NOTE: This method should return ErrAttemptResultPending for attempts
+	// that have been initialized via InitAttempt but for which a final
+	// result (settle/fail) has not yet been stored. ErrPaymentIDNotFound is
+	// returned for attempts that are unknown.
+	GetResult(attemptID uint64) (*networkResult, error)
+
+	// SubscribeResult subscribes to be notified when a result for a
+	// specific attempt ID becomes available. It returns a channel that will
+	// receive the result.
+	//
+	// NOTE: For backwards compatibility, the returned channel should only
+	// receive a value for attempts that have a final result (settle/fail).
+	// Subscribers should *not* be notified of the initial pending state
+	// created by InitAttempt.
+	SubscribeResult(attemptID uint64) (<-chan *networkResult, error)
+
+	// CleanStore removes all attempt results from the store except for
+	// those listed in the keepPids map. This allows for a "delete all
+	// except" approach to cleanup.
+	CleanStore(keepPids map[uint64]struct{}) error
+}