[Part 3|*] Implement Second Part for SQL Backend functions

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

@@ -66,6 +66,8 @@
     database](https://github.com/lightningnetwork/lnd/pull/9147)
   * Implement query methods (QueryPayments,FetchPayment) for the [payments db 
     SQL Backend](https://github.com/lightningnetwork/lnd/pull/10287)
+  * Implement insert methods for the [payments db 
+    SQL Backend](https://github.com/lightningnetwork/lnd/pull/10291)
 
 ## Code Health
 

payments/db/errors.go

@@ -83,6 +83,11 @@ var (
 	// paths or vice versa.
 	ErrMixedBlindedAndNonBlindedPayments = errors.New("mixed blinded and " +
 		"non-blinded payments")
+	// ErrBlindedPaymentMissingTotalAmount is returned if we try to
+	// register a blinded payment attempt where the final hop doesn't set
+	// the total amount.
+	ErrBlindedPaymentMissingTotalAmount = errors.New("blinded payment " +
+		"final hop must set total amount")
 
 	// ErrMPPPaymentAddrMismatch is returned if we try to register an MPP
 	// shard where the payment address doesn't match existing shards.

payments/db/interface.go

@@ -61,6 +61,17 @@ type PaymentControl interface {
 	InitPayment(lntypes.Hash, *PaymentCreationInfo) error
 
 	// RegisterAttempt atomically records the provided HTLCAttemptInfo.
+	//
+	// IMPORTANT: Callers MUST serialize calls to RegisterAttempt for the
+	// same payment hash. Concurrent calls will result in race conditions
+	// where both calls read the same initial payment state, validate
+	// against stale data, and could cause overpayment. For example:
+	//   - Both goroutines fetch payment with 400 sats sent
+	//   - Both validate sending 650 sats won't overpay (within limit)
+	//   - Both commit successfully
+	//   - Result: 1700 sats sent, exceeding the payment amount
+	// The payment router/controller layer is responsible for ensuring
+	// serialized access per payment hash.
 	RegisterAttempt(lntypes.Hash, *HTLCAttemptInfo) (*MPPayment, error)
 
 	// SettleAttempt marks the given attempt settled with the preimage. If

payments/db/kv_store.go

@@ -291,6 +291,8 @@ func (p *KVStore) InitPayment(paymentHash lntypes.Hash,
 // DeleteFailedAttempts deletes all failed htlcs for a payment if configured
 // by the KVStore db.
 func (p *KVStore) DeleteFailedAttempts(hash lntypes.Hash) error {
+	// TODO(ziggie): Refactor to not mix application logic with database
+	// logic. This decision should be made in the application layer.
 	if !p.keepFailedPaymentAttempts {
 		const failedHtlcsOnly = true
 		err := p.DeletePayment(hash, failedHtlcsOnly)

payments/db/payment.go

@@ -744,6 +744,13 @@ func verifyAttempt(payment *MPPayment, attempt *HTLCAttemptInfo) error {
 	// in the split payment is correct.
 	isBlinded := len(attempt.Route.FinalHop().EncryptedData) != 0
 
+	// For blinded payments, the last hop must set the total amount.
+	if isBlinded {
+		if attempt.Route.FinalHop().TotalAmtMsat == 0 {
+			return ErrBlindedPaymentMissingTotalAmount
+		}
+	}
+
 	// Make sure any existing shards match the new one with regards
 	// to MPP options.
 	mpp := attempt.Route.FinalHop().MPP