feat(1503): implement Stellar path payment operations support

- Add sendAsset, receiveAsset, slippageTolerance parameters to POST /donations endpoint
- Update createDonationSchema to include cross-asset fields
- Enhance DonationService to automatically discover paths for cross-asset donations
- Apply slippage tolerance to minimum destination amount
- Support path payment transactions with automatic asset conversion
- Default slippageTolerance to 1% if not specified

Fixes #1503

Author: aladi11isah

src/routes/donations/create.js

@@ -282,7 +282,7 @@ router.post('/', payloadSizeLimiter(ENDPOINT_LIMITS.singleDonation), donationRat
       return await processCustodialDonation(req, res, next);
     }
 
-    const { amount, currency, donor, recipient, memo, memoType, notes, tags, encryptMemo, anonymous, sourceAsset, sourceAmount } = req.body;
+    const { amount, currency, donor, recipient, memo, memoType, notes, tags, encryptMemo, anonymous, sourceAsset, sourceAmount, sendAsset, receiveAsset, slippageTolerance } = req.body;
 
     if (!amount || !recipient) {
       throw new ValidationError('Missing required fields: amount, recipient', null, ERROR_CODES.MISSING_REQUIRED_FIELD);
@@ -313,6 +313,32 @@ router.post('/', payloadSizeLimiter(ENDPOINT_LIMITS.singleDonation), donationRat
       }
     }
 
+    let normalizedSendAsset = null;
+    let normalizedReceiveAsset = null;
+    let normalizedSlippageTolerance = null;
+    if (sendAsset || receiveAsset) {
+      if (!sendAsset || !receiveAsset) {
+        return res.status(400).json({
+          success: false,
+          error: { code: 'VALIDATION_ERROR', message: 'Both sendAsset and receiveAsset must be provided for cross-asset donations' }
+        });
+      }
+      normalizedSendAsset = parseAssetInput(sendAsset, 'sendAsset');
+      normalizedReceiveAsset = parseAssetInput(receiveAsset, 'receiveAsset');
+
+      if (slippageTolerance !== undefined && slippageTolerance !== null) {
+        if (typeof slippageTolerance !== 'number' || slippageTolerance < 0 || slippageTolerance > 1) {
+          return res.status(400).json({
+            success: false,
+            error: { code: 'VALIDATION_ERROR', message: 'slippageTolerance must be a number between 0 and 1' }
+          });
+        }
+        normalizedSlippageTolerance = slippageTolerance;
+      } else {
+        normalizedSlippageTolerance = 0.01;
+      }
+    }
+
     if (memo || memoType) {
       const memoValidator = require('../../utils/memoValidator');
       const memoValidation = memoValidator.validateWithType(memo || '', memoType || 'text');
@@ -356,6 +382,9 @@ router.post('/', payloadSizeLimiter(ENDPOINT_LIMITS.singleDonation), donationRat
       memo,
       sourceAsset: normalizedSourceAsset,
       sourceAmount: sourceAmountValidation ? sourceAmountValidation.value : undefined,
+      sendAsset: normalizedSendAsset,
+      receiveAsset: normalizedReceiveAsset,
+      slippageTolerance: normalizedSlippageTolerance,
       memoType: memoType || 'text',
       notes,
       tags,

src/routes/donations/helpers.js

@@ -73,7 +73,10 @@ const createDonationSchema = validateSchema({
       notes: { type: 'string', required: false, nullable: true },
       tags: { type: 'array', required: false, nullable: true },
       sourceAsset: { type: 'string', required: false, nullable: true },
-      sourceAmount: { types: ['number', 'numberString'], required: false, nullable: true }
+      sourceAmount: { types: ['number', 'numberString'], required: false, nullable: true },
+      sendAsset: { types: ['string', 'object'], required: false, nullable: true },
+      receiveAsset: { types: ['string', 'object'], required: false, nullable: true },
+      slippageTolerance: { type: 'number', required: false, nullable: true }
     }
   }
 });

src/services/DonationService.js

@@ -710,6 +710,9 @@ class DonationService {
     anonymous = false,
     sourceAsset,
     sourceAmount,
+    sendAsset,
+    receiveAsset,
+    slippageTolerance,
     validAfter = 0,
     validBefore = 0,
     memoEnvelope = null,
@@ -801,11 +804,22 @@ class DonationService {
     }
 
     const sourceAssetProvided = sourceAsset !== undefined && sourceAsset !== null;
-    const normalizedDestAsset = DEFAULT_DESTINATION_ASSET;
-    const normalizedSourceAsset = sourceAssetProvided
+    const sendAssetProvided = sendAsset !== undefined && sendAsset !== null;
+    const receiveAssetProvided = receiveAsset !== undefined && receiveAsset !== null;
+
+    let normalizedDestAsset = DEFAULT_DESTINATION_ASSET;
+    let normalizedSourceAsset = sourceAssetProvided
       ? parseAssetInput(sourceAsset, 'sourceAsset')
       : normalizedDestAsset;
+
+    // Handle sendAsset/receiveAsset for path payment donations
+    if (sendAssetProvided && receiveAssetProvided) {
+      normalizedSourceAsset = parseAssetInput(sendAsset, 'sendAsset');
+      normalizedDestAsset = parseAssetInput(receiveAsset, 'receiveAsset');
+    }
+
     const normalizedSourceAmount = sourceAmount ?? xlmAmount;
+    const normalizedSlippageTolerance = slippageTolerance ?? 0.01;
     const sourceSecret = this.resolvePaymentSourceSecret(sanitizedDonor);
     let stellarResult = null;
     let paymentMethod = 'record_only';
@@ -815,12 +829,15 @@ class DonationService {
 
     if (sourceSecret && sanitizedRecipient) {
       await this.checkRecipientAccountExists(sanitizedRecipient);
-      if (!sourceAssetProvided) {
+
+      const isPathPayment = sourceAssetProvided || (sendAssetProvided && receiveAssetProvided && !isSameAsset(normalizedSourceAsset, normalizedDestAsset));
+
+      if (!isPathPayment) {
         // Set correlation ID on StellarService for this request
         if (correlationId) {
           this.stellarService.setCorrelationId(correlationId);
         }
-        
+
         stellarResult = await this.stellarService.sendDonation({
           sourceSecret,
           destinationPublic: sanitizedRecipient,
@@ -837,6 +854,11 @@ class DonationService {
           this.stellarService.setCorrelationId(correlationId);
         }
 
+        // Set correlation ID on StellarService for this request
+        if (correlationId) {
+          this.stellarService.setCorrelationId(correlationId);
+        }
+
         const estimate = await this.stellarService.discoverBestPath({
           sourceAsset: normalizedSourceAsset,
           sourceAmount: normalizedSourceAmount.toString(),
@@ -851,12 +873,16 @@ class DonationService {
         selectedPath = estimate.path || [];
         conversionRate = estimate.conversionRate;
 
+        // Apply slippage tolerance to minimum destination amount
+        const estimatedDestAmount = parseFloat(estimate.destAmount);
+        const minDestAmount = estimatedDestAmount * (1 - normalizedSlippageTolerance);
+
         try {
           stellarResult = await this.stellarService.pathPayment(
             normalizedSourceAsset,
             normalizedSourceAmount.toString(),
             normalizedDestAsset,
-            estimate.destAmount,
+            minDestAmount.toString(),
             selectedPath,
             {
               sourceSecret,