refactor: use *uint64 for IntendedReceivingAmount to store NULL for non-payments

Non-payment transactions now store NULL instead of 0, distinguishing
"not a payment" from "zero-drop payment". Also fix stale doc comment
on transactionStatus, add doc comment to TransactionStatus field, and
remove duplicate DestinationAddressHash assignment.

Author: GrePod

internal/xrp/client.go

@@ -190,7 +190,6 @@ func (c *xrpClient) GetBlockResult(ctx context.Context, blockNum uint64) (*index
 				return nil, fmt.Errorf("isNativePayment: %w", err)
 			}
 			transactions[i].IsNativePayment = isNative
-			transactions[i].DestinationAddressHash = tx.destinationAddressHash()
 
 			transactions[i].IntendedReceivingAmount, err = tx.intendedReceivingAmount()
 			if err != nil {

internal/xrp/entities.go

@@ -6,14 +6,17 @@ import (
 
 // Transaction is the database model for an XRP ledger payment transaction.
 type Transaction struct {
-	Hash                    string  `gorm:"primaryKey;type:varchar(64)"`
-	BlockNumber             uint64  `gorm:"index;index:idx_payref_block,priority:2;index:idx_dest_block,priority:2"`
-	Timestamp               uint64  `gorm:"index"`
+	Hash        string `gorm:"primaryKey;type:varchar(64)"`
+	BlockNumber uint64 `gorm:"index;index:idx_payref_block,priority:2;index:idx_dest_block,priority:2"`
+	Timestamp   uint64 `gorm:"index"`
+	// TransactionStatus is true when the transaction result is tesSUCCESS or a
+	// destination-related failure (tecDST_TAG_NEEDED, tecNO_DST, tecNO_DST_INSUF_XRP,
+	// tecNO_PERMISSION), and false for all other results.
 	TransactionStatus       bool    `gorm:"index"`
 	PaymentReference        string  `gorm:"index:idx_payref_block,priority:1;type:varchar(64);default:null"`
 	Response                string  `gorm:"type:varchar"`
 	IsNativePayment         bool    `gorm:"index"`
-	IntendedReceivingAmount uint64  `gorm:"index:idx_payref_block,priority:3;index:idx_dest_block,priority:3"`
+	IntendedReceivingAmount *uint64 `gorm:"index:idx_payref_block,priority:3;index:idx_dest_block,priority:3"`
 	DestinationAddressHash  *string `gorm:"index:idx_dest_block,priority:1;type:varchar(64);default:null"`
 	SourceAddressesRoot     string  `gorm:"index;type:varchar(64);default:null"`
 	Sequence                uint64  `gorm:"index:idx_source_sequence,priority:2"`

internal/xrp/transaction.go

@@ -105,9 +105,9 @@ func (tx *transaction) destinationAddressHash() *string {
 	return nil
 }
 
-// transactionStatus returns a numeric status code derived from the transaction's
-// TransactionResult metadata: 0 for success, 1 for destination-related failures,
-// and 2 for all other results.
+// transactionStatus returns true when the transaction result is tesSUCCESS or a
+// destination-related failure (tecDST_TAG_NEEDED, tecNO_DST, tecNO_DST_INSUF_XRP,
+// tecNO_PERMISSION), and false for all other results.
 func (tx *transaction) transactionStatus() (bool, error) {
 	var meta struct {
 		TransactionResult string `json:"TransactionResult"`
@@ -130,23 +130,24 @@ func (tx *transaction) transactionStatus() (bool, error) {
 }
 
 // intendedReceivingAmount returns the native XRP amount in drops that the
-// sender intended to deliver. Returns 0 for non-native (token) payments.
-func (tx *transaction) intendedReceivingAmount() (uint64, error) {
+// sender intended to deliver. Returns a pointer to 0 for non-native (token) payments.
+func (tx *transaction) intendedReceivingAmount() (*uint64, error) {
 	if len(tx.Amount) == 0 || tx.Amount[0] != '"' {
-		return 0, nil
+		zero := uint64(0)
+		return &zero, nil
 	}
 
 	var s string
 	if err := json.Unmarshal(tx.Amount, &s); err != nil {
-		return 0, fmt.Errorf("unmarshal amount: %w", err)
+		return nil, fmt.Errorf("unmarshal amount: %w", err)
 	}
 
 	drops, err := strconv.ParseUint(s, 10, 64)
 	if err != nil {
-		return 0, fmt.Errorf("parse drops: %w", err)
+		return nil, fmt.Errorf("parse drops: %w", err)
 	}
 
-	return drops, nil
+	return &drops, nil
 }
 
 // sourceAddressesRoot computes the Merkle root of the double-Keccak256-hashed addresses

internal/xrp/transaction_test.go

@@ -49,27 +49,27 @@ func TestIntendedReceivingAmount(t *testing.T) {
 	tests := []struct {
 		name     string
 		amount   string
-		expected uint64
+		expected *uint64
 	}{
 		{
 			name:     "native XRP drops",
 			amount:   `"15000000"`,
-			expected: 15000000,
+			expected: uint64Ptr(15000000),
 		},
 		{
 			name:     "large native amount",
 			amount:   `"100000000000000000"`,
-			expected: 100000000000000000,
+			expected: uint64Ptr(100000000000000000),
 		},
 		{
 			name:     "token amount object",
 			amount:   `{"currency":"USD","issuer":"rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn","value":"100"}`,
-			expected: 0,
+			expected: uint64Ptr(0),
 		},
 		{
 			name:     "empty amount",
 			amount:   ``,
-			expected: 0,
+			expected: uint64Ptr(0),
 		},
 	}
 
@@ -287,3 +287,7 @@ func TestDestinationAddressHash(t *testing.T) {
 func ptr(s string) *string {
 	return &s
 }
+
+func uint64Ptr(v uint64) *uint64 {
+	return &v
+}

internal/xrp/xrp_test.go

@@ -85,7 +85,8 @@ func TestXrp(t *testing.T) {
 		require.Nil(t, tx.DestinationTag)
 
 		require.NotNil(t, tx.DestinationAddressHash)
-		require.NotZero(t, tx.IntendedReceivingAmount)
+		require.NotNil(t, tx.IntendedReceivingAmount)
+		require.NotZero(t, *tx.IntendedReceivingAmount)
 		require.True(t, tx.TransactionStatus)
 
 		require.Empty(t, blockResult.Events)