[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

@@ -84,6 +84,12 @@ var (
 	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.
 	ErrMPPPaymentAddrMismatch = errors.New("payment address mismatch")

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

payments/db/payment_test.go

@@ -1388,6 +1388,45 @@ func TestVerifyAttemptBlindedValidation(t *testing.T) {
 	require.NoError(t, verifyAttempt(payment, &matching))
 }
 
+// TestVerifyAttemptBlindedMissingTotalAmount tests that we return an error if
+// we try to register a blinded payment attempt where the final hop doesn't set
+// the total amount.
+func TestVerifyAttemptBlindedMissingTotalAmount(t *testing.T) {
+	t.Parallel()
+
+	total := lnwire.MilliSatoshi(5000)
+
+	// Payment with no existing attempts.
+	payment := makePayment(total)
+
+	// Attempt with encrypted data (blinded payment) but missing total
+	// amount.
+	attemptMissingTotal := makeLastHopAttemptInfo(
+		1,
+		lastHopArgs{
+			amt:       2500,
+			total:     0,
+			encrypted: []byte{1, 2, 3},
+		},
+	)
+	require.ErrorIs(
+		t,
+		verifyAttempt(payment, &attemptMissingTotal),
+		ErrBlindedPaymentMissingTotalAmount,
+	)
+
+	// Attempt with encrypted data and valid total amount should succeed.
+	attemptWithTotal := makeLastHopAttemptInfo(
+		2,
+		lastHopArgs{
+			amt:       2500,
+			total:     total,
+			encrypted: []byte{4, 5, 6},
+		},
+	)
+	require.NoError(t, verifyAttempt(payment, &attemptWithTotal))
+}
+
 // TestVerifyAttemptBlindedMixedWithNonBlinded tests that we return an error if
 // we try to register a non-MPP attempt for a blinded payment.
 func TestVerifyAttemptBlindedMixedWithNonBlinded(t *testing.T) {