Merge pull request Stellar-IndigoPay#278 from scarface-dev1/feat/idempotency-key-donation-recording-148

Feat/idempotency key donation recording 118

Author: LaPoshBaby

.github/workflows/contracts.yml

@@ -43,7 +43,7 @@ jobs:
         run: cargo build --workspace --target wasm32v1-none --release
 
   fuzz:
-    name: Fuzz Tests (10k iterations)
+    name: Fuzz Tests (256 cases each)
     runs-on: ubuntu-latest
     timeout-minutes: 20
     defaults:
@@ -64,10 +64,89 @@ jobs:
         with:
           workspaces: contracts
 
-      - name: Run fuzz tests (1.5k iterations)
+      - name: Run fuzz tests
         run: cargo test --features testutils -- fuzz
         env:
-          FUZZ_ITERATIONS: 1500
+          FUZZ_ITERATIONS: 256
+
+  deep-fuzz:
+    name: Deep Fuzz (2k cases each -- nightly)
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    defaults:
+      run:
+        working-directory: contracts
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.91.0
+          targets: wasm32v1-none
+          components: rustfmt, clippy
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: contracts
+
+  deep-fuzz:
+    name: Deep Fuzz (2k cases each -- nightly)
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    defaults:
+      run:
+        working-directory: contracts
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.91.0
+          targets: wasm32v1-none
+          components: rustfmt, clippy
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: contracts
+
+      - name: Run deep fuzz tests
+        run: cargo test --features testutils -- fuzz
+        env:
+          FUZZ_ITERATIONS: 2000
+
+  deep-fuzz-pr:
+    name: Deep Fuzz (500 cases each -- PR)
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: contracts
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: 1.91.0
+          targets: wasm32v1-none
+          components: rustfmt, clippy
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: contracts
+
+      - name: Run deep fuzz tests
+        run: cargo test --features testutils -- fuzz
+        env:
+          FUZZ_ITERATIONS: 500
 
   coverage:
     name: Coverage (tarpaulin)
@@ -94,7 +173,7 @@ jobs:
           workspaces: contracts
 
       - name: Run coverage
-        run: cargo tarpaulin --config indigopay-contract/.tarpaulin.toml --out Html --out Lcov
+        run: cargo tarpaulin --config indigopay-contract/.tarpaulin.toml --features testutils --out Html --out Lcov -- --skip fuzz
 
       - name: Upload coverage report
         uses: actions/upload-artifact@v4

backend/src/db/schema.sql

@@ -279,3 +279,17 @@ CREATE INDEX IF NOT EXISTS verification_requests_status_idx
   ON verification_requests (status, submitted_at DESC);
 CREATE INDEX IF NOT EXISTS verification_requests_wallet_idx
   ON verification_requests (wallet_address);
+
+-- idempotency_keys: stores the cached HTTP response for each Idempotency-Key
+-- header value sent by clients to POST /api/donations.  Rows older than 24 h
+-- are pruned by the idempotencyCleanup cron service so that retried requests
+-- within the same window always receive the same response body and status code.
+CREATE TABLE IF NOT EXISTS idempotency_keys (
+  key              TEXT        PRIMARY KEY,
+  response_status  INTEGER     NOT NULL,
+  response_body    JSONB       NOT NULL,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idempotency_keys_created_at_idx
+  ON idempotency_keys (created_at);

backend/src/routes/donations.js

@@ -9,6 +9,7 @@ const { v4: uuid } = require("uuid");
 const { z } = require("zod");
 const logger = require("../logger");
 const pool = require("../db/pool");
+const { AppError } = require("../errors");
 const { createRateLimiter } = require("../middleware/rateLimiter");
 const { validate } = require("../middleware/validate");
 const idempotencyMiddleware = require("../middleware/idempotency");
@@ -21,18 +22,33 @@ const { mapDonationRow } = require("../services/store");
 const { enqueueProfileUpdate } = require("../services/profileQueue");
 const { enqueuePushNotification } = require("../services/pushQueue");
 const { server } = require("../services/stellar");
-const { AppError } = require("../errors");
 const donationLimiter = createRateLimiter(10, 1); // 10 requests per minute
 
 // Local EventEmitter used by both the POST /api/donations handler and the
 // GET /api/donations/stream SSE endpoint to broadcast new donations in
 // real time without going through Socket.IO.
 const donationEvents = new EventEmitter();
 
+function validateKey(k) {
+  if (!k || !/^G[A-Z0-9]{55}$/.test(k)) {
+    throw new AppError("INVALID_ADDRESS");
+  }
+}
+
+function validateTxHash(h) {
+  if (!h || !/^[a-fA-F0-9]{64}$/.test(h)) {
+    throw new AppError("INVALID_TX_HASH");
+  }
+}
 
 /**
  * Record a donation after an on-chain transaction is observed.
  *
+ * Supports an optional `Idempotency-Key` request header (UUID v4).  When
+ * supplied, the server stores the response and replays it on duplicate
+ * requests within a 24-hour window, preventing double-recording of the same
+ * donation.
+ *
  * @route POST /api/donations
  * @param {import('express').Request} req - Express request containing the donation payload.
  * @param {import('express').Response} res - Express response object.
@@ -65,7 +81,7 @@ async function recordDonation(req, res, next) {
       throw new AppError("INVALID_TX_HASH");
     }
 
-    if (!client) client = await pool.connect();
+    client = await pool.connect();
 
     const projectResult = await client.query(
       "SELECT id FROM projects WHERE id = $1",
@@ -80,10 +96,7 @@ async function recordDonation(req, res, next) {
       currency === "XLM" ? (amountXLM ?? amount) : amount,
     );
     if (isNaN(parsedAmount) || parsedAmount <= 0) {
-      throw new AppError("VALIDATION_ERROR", {
-        field: "amount",
-        detail: "Invalid amount",
-      });
+      throw new AppError("VALIDATION_ERROR", { field: "amount" });
     }
 
     // Deduplicate by tx hash
@@ -110,9 +123,7 @@ async function recordDonation(req, res, next) {
       throw new AppError("TX_NOT_FOUND");
     }
     if (!onChainTx || onChainTx.successful !== true) {
-      throw new AppError("TX_FAILED", {
-        detail: "Transaction not confirmed on Stellar",
-      });
+      throw new AppError("TX_FAILED");
     }
 
     await client.query("BEGIN");
@@ -129,7 +140,7 @@ async function recordDonation(req, res, next) {
         uuid(),
         projectId,
         donorAddress,
-        currency === "XLM" ? parsedAmount : (convertedAmountXLM || null),
+        currency === "XLM" ? parsedAmount : (convertedAmountXLM ? parseFloat(convertedAmountXLM) : null),
         parsedAmount,
         currency,
         message?.trim().slice(0, 100) || null,
@@ -144,14 +155,14 @@ async function recordDonation(req, res, next) {
       id: uuid(),
       project_id: projectId,
       donor_address: donorAddress,
-      amount_xlm: currency === "XLM" ? parsedAmount : (convertedAmountXLM || null),
+      amount_xlm: currency === "XLM" ? parsedAmount : (convertedAmountXLM ? parseFloat(convertedAmountXLM) : null),
       amount: parsedAmount,
       currency,
       message: message?.trim().slice(0, 100) || null,
       transaction_hash: transactionHash,
       source_asset: sourceAsset || null,
       conversion_path: conversionPath || null,
-      converted_amount_xlm: convertedAmountXLM || null,
+      converted_amount_xlm: convertedAmountXLM ? parseFloat(convertedAmountXLM) : null,
       created_at: new Date().toISOString(),
     };
 
@@ -416,10 +427,7 @@ router.get("/:id", async (req, res, next) => {
         id,
       )
     ) {
-      throw new AppError("VALIDATION_ERROR", {
-        field: "id",
-        detail: "Invalid donation ID",
-      });
+      throw new AppError("VALIDATION_ERROR", { field: "id", message: "Invalid donation ID" });
     }
 
     const USDC_TO_XLM_RATE = parseFloat(process.env.USDC_TO_XLM_RATE || "8.0");

backend/src/routes/donations.test.js

@@ -16,16 +16,12 @@ jest.mock("../services/profileQueue", () => ({
   enqueueProfileUpdate: jest.fn().mockResolvedValue(undefined),
 }));
 
-jest.mock("../services/pushQueue", () => ({
-  enqueuePushNotification: jest.fn().mockResolvedValue(undefined),
-}));
-
 const { server } = require("../services/stellar");
 const pool = require("../db/pool");
 const { computeBadges } = require("../services/store");
 const { enqueueProfileUpdate } = require("../services/profileQueue");
-const { recordDonation } = require("./donations");
 const { AppError } = require("../errors");
+const { recordDonation } = require("./donations");
 
 function makePublicKey(char = "A") {
   return `G${char.repeat(55)}`;
@@ -73,17 +69,20 @@ function createMockResponse() {
   };
 }
 
-async function invokeRecordDonation(body, headers = {}) {
-  const req = { body, headers };
+const STATUS_FALLBACK_CODE = { 400: "VALIDATION_ERROR", 404: "NOT_FOUND", 409: "DUPLICATE_DONATION", 413: "FILE_TOO_LARGE", 422: "SCHEMA_VALIDATION_ERROR", 429: "RATE_LIMITED" };
+
+async function invokeRecordDonation(body) {
+  const req = { body };
   const res = createMockResponse();
   const next = jest.fn((err) => {
     if (err) {
       if (err instanceof AppError) {
         res.status(err.status).json(err.toJSON());
+      } else if (err.status && err.status < 500) {
+        const code = STATUS_FALLBACK_CODE[err.status] || "VALIDATION_ERROR";
+        res.status(err.status).json({ error: { code, message: err.message } });
       } else {
-        res
-          .status(err.status || 500)
-          .json({ error: err.message || "Internal server error" });
+        res.status(500).json({ error: { code: "INTERNAL_ERROR", message: "Internal server error" } });
       }
     }
   });
@@ -221,7 +220,7 @@ describe("POST /api/donations", () => {
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(res.statusCode).toBe(404);
-    expect(res.body.error.code).toBe("PROJECT_NOT_FOUND");
+    expect(res.body.error).toEqual({ code: "PROJECT_NOT_FOUND", message: "Project not found" });
     expect(client.release).toHaveBeenCalledTimes(1);
   });
 
@@ -235,7 +234,7 @@ describe("POST /api/donations", () => {
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(res.statusCode).toBe(400);
-    expect(res.body.error.code).toBe("INVALID_ADDRESS");
+    expect(res.body.error).toEqual({ code: "INVALID_ADDRESS", message: "Invalid Stellar address" });
     expect(pool.connect).not.toHaveBeenCalled();
   });
 
@@ -249,7 +248,7 @@ describe("POST /api/donations", () => {
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(res.statusCode).toBe(400);
-    expect(res.body.error.code).toBe("INVALID_TX_HASH");
+    expect(res.body.error).toEqual({ code: "INVALID_TX_HASH", message: "Invalid transaction hash" });
     expect(pool.connect).not.toHaveBeenCalled();
   });
 
@@ -332,7 +331,7 @@ describe("POST /api/donations", () => {
 
   test("calculates badges from cumulative donations across multiple requests", async () => {
     const donorAddress = makePublicKey("F");
-    createMockClient(
+    void createMockClient(
       queryResult([{ id: "project-3" }]), // SELECT project
       queryResult([]), // dedup check
       queryResult(), // BEGIN
@@ -382,7 +381,7 @@ describe("POST /api/donations", () => {
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(res.statusCode).toBe(400);
-    expect(res.body.error.code).toBe("TX_FAILED");
+    expect(res.body.error).toEqual({ code: "TX_FAILED", message: "Transaction failed on Stellar" });
     // No DB write transaction should have been opened.
     expect(client.query).not.toHaveBeenCalledWith("BEGIN");
     expect(client.release).toHaveBeenCalledTimes(1);
@@ -404,7 +403,7 @@ describe("POST /api/donations", () => {
 
     expect(next).toHaveBeenCalledTimes(1);
     expect(res.statusCode).toBe(400);
-    expect(res.body.error.code).toBe("TX_NOT_FOUND");
+    expect(res.body.error).toEqual({ code: "TX_NOT_FOUND", message: "Transaction not found on Stellar" });
     expect(client.query).not.toHaveBeenCalledWith("BEGIN");
     expect(client.release).toHaveBeenCalledTimes(1);
   });
@@ -510,7 +509,7 @@ describe("profile upsert on first donation", () => {
       created_at: "2026-03-29T10:00:00.000Z",
     };
 
-    createMockClient(
+    void createMockClient(
       queryResult([{ id: "project-p" }]),
       queryResult([]),
       queryResult(),
@@ -549,7 +548,7 @@ describe("profile upsert on first donation", () => {
       created_at: "2026-03-29T10:00:00.000Z",
     };
 
-    createMockClient(
+    void createMockClient(
       queryResult([{ id: "project-q" }]),
       queryResult([]),
       queryResult(),
@@ -596,7 +595,7 @@ describe("profile upsert on first donation", () => {
       created_at: "2026-03-29T10:00:00.000Z",
     };
 
-    createMockClient(
+    void createMockClient(
       queryResult([{ id: "project-r" }]),
       queryResult([]),
       queryResult(),

backend/src/server.js

@@ -59,8 +59,7 @@ const { AppError } = require("./errors");
 const { startTurretsServer } = require("./services/turrets");
 const { start: startSummaryQueue } = require("./services/summaryQueue");
 const { start: startProfileQueue } = require("./services/profileQueue");
-const {
-  start: startWebhookQueue,
+const { start: startWebhookQueue,
   stop: stopWebhookQueue,
 } = require("./services/webhookQueue");
 const { start: startPushQueue } = require("./services/pushQueue");
@@ -563,7 +562,7 @@ async function startServer() {
       const sorobanEvents = require("./services/sorobanEventService");
       if (typeof sorobanEvents.stop === "function") await sorobanEvents.stop();
     } catch {
-      // Service may already be stopped; swallow.
+      // Service may already be stopped or not loaded; swallow.
     }
   });