[#452] Backend: Replace mock referral yield calculation with real on-chain or ledger-backed accounting

backend/prisma/migrations/20260527000000_add_share_price_snapshots/migration.sql

@@ -0,0 +1,14 @@
+-- CreateTable
+CREATE TABLE "SharePriceSnapshot" (
+    "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    "sharePrice" TEXT NOT NULL,
+    "recordedAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "ledgerSeq" INTEGER,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- CreateIndex
+CREATE INDEX "SharePriceSnapshot_recordedAt_idx" ON "SharePriceSnapshot"("recordedAt");
+
+-- CreateIndex
+CREATE INDEX "SharePriceSnapshot_ledgerSeq_idx" ON "SharePriceSnapshot"("ledgerSeq");

backend/prisma/schema.prisma

@@ -24,6 +24,17 @@ model VaultState {
   updatedAt   DateTime @updatedAt
 }
 
+model SharePriceSnapshot {
+  id         Int      @id @default(autoincrement())
+  sharePrice String
+  recordedAt DateTime @default(now())
+  ledgerSeq  Int?
+  createdAt  DateTime @default(now())
+
+  @@index([recordedAt])
+  @@index([ledgerSeq])
+}
+
 model Transaction {
   id           String   @id @default(uuid())
   user         String

backend/src/__tests__/adminFeatures.test.ts

@@ -7,6 +7,7 @@ import { resetAuditLogs } from '../auditLog';
 describe('Admin backend features', () => {
   const adminKey = 'admin-feature-test-key';
   const authHeader = { Authorization: `ApiKey ${adminKey}` };
+  const walletAddress = 'GABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz234567';
 
   beforeAll(() => {
     registerApiKey(adminKey);
@@ -36,12 +37,17 @@ describe('Admin backend features', () => {
 
     expect(webhookResponse.status).toBe(201);
 
+    await request(app)
+      .post('/admin/allowlist/add')
+      .set(authHeader)
+      .send({ walletAddress, reason: 'admin-feature-test' });
+
     const depositResponse = await request(app)
       .post('/api/v1/vault/deposits')
       .send({
         amount: '125.00',
         asset: 'USDC',
-        walletAddress: 'GABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz234567',
+        walletAddress,
       });
 
     expect(depositResponse.status).toBe(201);

backend/src/__tests__/eventPollingService.test.ts

@@ -1,5 +1,6 @@
 import { EventPollingService } from '../eventPollingService';
 import { getPrismaClient } from '../prismaClient';
+import { createStellarRpcFetchMock } from './mocks/stellarRpc';
 
 const prisma = getPrismaClient();
 
@@ -349,4 +350,169 @@
       expect(true).toBe(true);
     });
   });
+
+  describe('Failure and Gap-Recovery Scenarios', () => {
+    it('retries after an RPC timeout without dropping events', async () => {
+      let cursor = 1000;
+      const storedEvents = new Set<string>();
+      let eventsCallCount = 0;
+
+      (prisma.eventCursor.findUnique as jest.Mock).mockImplementation(async () => ({
+        id: 1,
+        lastLedgerSeq: cursor,
+      }));
+
+      (prisma.eventCursor.upsert as jest.Mock).mockImplementation(async ({ update }) => {
+        cursor = update.lastLedgerSeq;
+        return { id: 1, lastLedgerSeq: cursor };
+      });
+
+      (prisma.processedEvent.findUnique as jest.Mock).mockImplementation(async ({ where }) => {
+        return storedEvents.has(where.id) ? { id: where.id } : null;
+      });
+
+      (prisma.processedEvent.upsert as jest.Mock).mockImplementation(async ({ create }) => {
+        storedEvents.add(create.id);
+        return create;
+      });
+
+      global.fetch = createStellarRpcFetchMock(async ({ method }) => {
+        if (method === 'getLatestLedger') {
+          return { result: { sequence: 1002 } };
+        }
+
+        eventsCallCount += 1;
+        if (eventsCallCount === 1) {
+          throw new Error('RPC timeout');
+        }
+
+        return {
+          result: {
+            events: [
+              {
+                id: 'event-1001',
+                type: 'contract',
+                ledger: 1001,
+                contractId: 'CTEST123',
+                txHash: 'tx-1001',
+              },
+              {
+                id: 'event-1002',
+                type: 'contract',
+                ledger: 1002,
+                contractId: 'CTEST123',
+                txHash: 'tx-1002',
+              },
+            ],
+          },
+        };
+      });
+
+      await (service as any).pollEvents();
+      expect(cursor).toBe(1000);
+      expect(prisma.processedEvent.upsert).not.toHaveBeenCalled();
+
+      await (service as any).pollEvents();
+
+      expect(prisma.processedEvent.upsert).toHaveBeenCalledTimes(2);
+      expect(cursor).toBe(1002);
+      expect(storedEvents.has('event-1001')).toBe(true);
+      expect(storedEvents.has('event-1002')).toBe(true);
+    });
+
+    it('re-fetches all missing ledger ranges during replay', async () => {
+      const requestedRanges: Array<{ start: number; end: number }> = [];
+      const replayService = new EventPollingService({
+        ...mockConfig,
+        batchSize: 100,
+      });
+
+      (prisma.eventCursor.findUnique as jest.Mock).mockResolvedValue({
+        id: 1,
+        lastLedgerSeq: 1000,
+      });
+
+      (prisma.eventCursor.upsert as jest.Mock).mockResolvedValue({});
+      (prisma.processedEvent.findUnique as jest.Mock).mockResolvedValue(null);
+
+      global.fetch = createStellarRpcFetchMock(async ({ method, params }) => {
+        if (method === 'getLatestLedger') {
+          return { result: { sequence: 1200 } };
+        }
+
+        requestedRanges.push({
+          start: params.startLedger,
+          end: params.startLedger + 99,
+        });
+
+        return {
+          result: {
+            events: [],
+          },
+        };
+      });
+
+      await replayService.start();
+      await replayService.stop();
+
+      expect(requestedRanges).toEqual([
+        { start: 1001, end: 1100 },
+        { start: 1101, end: 1200 },
+      ]);
+      expect(prisma.eventCursor.upsert).toHaveBeenCalledTimes(2);
+    });
+
+    it('handles duplicate event delivery idempotently with one DB record', async () => {
+      const storedEvents = new Set<string>();
+
+      (prisma.eventCursor.findUnique as jest.Mock).mockResolvedValue({
+        id: 1,
+        lastLedgerSeq: 1000,
+      });
+
+      (prisma.eventCursor.upsert as jest.Mock).mockResolvedValue({});
+
+      (prisma.processedEvent.findUnique as jest.Mock).mockImplementation(async ({ where }) => {
+        return storedEvents.has(where.id) ? { id: where.id } : null;
+      });
+
+      (prisma.processedEvent.upsert as jest.Mock).mockImplementation(async ({ create }) => {
+        storedEvents.add(create.id);
+        return create;
+      });
+
+      global.fetch = createStellarRpcFetchMock(async ({ method }) => {
+        if (method === 'getLatestLedger') {
+          return { result: { sequence: 1010 } };
+        }
+
+        return {
+          result: {
+            events: [
+              {
+                id: 'duplicate-event',
+                type: 'contract',
+                ledger: 1005,
+                contractId: 'CTEST123',
+                txHash: 'tx-dup',
+              },
+              {
+                id: 'duplicate-event',
+                type: 'contract',
+                ledger: 1005,
+                contractId: 'CTEST123',
+                txHash: 'tx-dup',
+              },
+            ],
+          },
+        };
+      });
+
+      await service.start();
+
+      expect(prisma.processedEvent.upsert).toHaveBeenCalledTimes(1);
+      expect(storedEvents.size).toBe(1);
+      expect(storedEvents.has('duplicate-event')).toBe(true);
+    });
+  });
 });

backend/src/__tests__/governance.test.ts

@@ -33,6 +33,11 @@ describe('Backend governance', () => {
       walletAddress: 'GABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz234567',
     };
 
+    await request(app)
+      .post('/admin/allowlist/add')
+      .set('Authorization', `ApiKey ${adminApiKey}`)
+      .send({ walletAddress: payload.walletAddress, reason: 'governance-test' });
+
     const first = await request(app)
       .post('/api/v1/vault/deposits')
       .set('x-idempotency-key', 'deposit-key-1')
@@ -50,13 +55,18 @@ describe('Backend governance', () => {
   });
 
   it('rejects conflicting requests that reuse the same idempotency key', async () => {
+    await request(app)
+      .post('/admin/allowlist/add')
+      .set('Authorization', `ApiKey ${adminApiKey}`)
+      .send({ walletAddress: targetWallet, reason: 'governance-test' });
+
     const first = await request(app)
       .post('/api/v1/vault/deposits')
       .set('x-idempotency-key', 'deposit-key-2')
       .send({
         amount: 250,
         asset: 'USDC',
-        walletAddress: 'GABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz234567',
+        walletAddress: targetWallet,
       });
 
     const second = await request(app)
@@ -65,7 +75,7 @@ describe('Backend governance', () => {
       .send({
         amount: 300,
         asset: 'USDC',
-        walletAddress: 'GABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz234567',
+        walletAddress: targetWallet,
       });
 
     expect(first.status).toBe(201);

backend/src/__tests__/latencyMonitoring.test.ts

@@ -189,7 +189,7 @@
       });
 
       // Manually trigger alert check for testing
       await (newService as any).checkSLOViolations();
 
       expect(global.fetch).toHaveBeenCalledWith(
         'https://hooks.slack.com/test',
@@ -216,7 +216,7 @@
       });
 
       // Manually trigger alert check for testing
       await (newService as any).checkSLOViolations();
 
       expect(global.fetch).toHaveBeenCalledWith(
         'https://events.pagerduty.com/v2/enqueue',
@@ -243,7 +243,7 @@
       });
 
       // Should not throw error, just log warning
       await expect((newService as any).checkSLOViolations()).resolves.not.toThrow();
       expect(global.fetch).not.toHaveBeenCalled();
     });
   });
@@ -302,15 +302,15 @@
       freshService.recordLatency(endpoint, 500);
 
       const metricsBefore = freshService.getDetailedMetrics();
-      const metricBefore = metricsBefore.find(m => m.endpoint === endpoint);
+      const metricBefore = metricsBefore.find((m: any) => m.endpoint === endpoint);
       expect(metricBefore?.currentP95).toBe(500);
       expect(metricBefore?.isBreaching).toBe(true);
 
       // Wait for the evaluation window to expire
       return new Promise<void>((resolve) => {
         setTimeout(() => {
           const metricsAfter = freshService.getDetailedMetrics();
-          const metricAfter = metricsAfter.find(m => m.endpoint === endpoint);
+          const metricAfter = metricsAfter.find((m: any) => m.endpoint === endpoint);
           // Stale data should be pruned, P95 should drop to 0
           expect(metricAfter?.currentP95).toBe(0);
           expect(metricAfter?.isBreaching).toBe(false);
@@ -337,7 +337,7 @@
           freshService.recordLatency(endpoint, 100);
 
           const metrics = freshService.getDetailedMetrics();
-          const metric = metrics.find(m => m.endpoint === endpoint);
+          const metric = metrics.find((m: any) => m.endpoint === endpoint);
           // Only the fresh data point should count
           expect(metric?.dataPoints).toBe(1);
           expect(metric?.currentP95).toBe(100);

backend/src/__tests__/mocks/stellarRpc.ts

@@ -0,0 +1,18 @@
+type RpcMethod = 'getLatestLedger' | 'getEvents';
+
+interface RpcRequest {
+  method: RpcMethod;
+  params?: any;
+}
+
+type RpcHandler = (request: RpcRequest) => Promise<any>;
+
+export function createStellarRpcFetchMock(handler: RpcHandler): jest.Mock {
+  return jest.fn(async (_url: string, options: any) => {
+    const body = JSON.parse(options.body || '{}');
+    const payload = await handler({ method: body.method, params: body.params });
+    return {
+      json: async () => payload,
+    };
+  });
+}