feat: Implement event-sourced campaign status derivation with new sta…

backend/src/api.test.ts

@@ -5,7 +5,7 @@ import path from 'path';
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { app } from './index';
 import { initCampaignStore } from './services/campaignStore';
-import { getDb } from './services/db';
+import { getDb, resetDbForTests } from './services/db';
 
 // Mock sorobanRpc to avoid real network calls during tests
 vi.mock('./services/sorobanRpc', () => ({

backend/src/index.ts

@@ -34,7 +34,7 @@
   reconcileOnChainPledge,
   refundContributor,
   SortOrder,
   updateCampaign,
 } from './services/campaignStore';
 import { checkDbHealth } from './services/db';
 import { listCampaignHistory } from './services/eventHistory';
@@ -60,7 +60,7 @@
 
 type CampaignListItem = CampaignRecord & { progress: CampaignProgress };
 
-const CAMPAIGN_STATUSES: CampaignStatus[] = ['open', 'funded', 'claimed', 'failed'];
+const CAMPAIGN_STATUSES: CampaignStatus[] = ['open', 'funded', 'claimed', 'failed', 'canceled'];
 const CONTRACT_AMOUNT_DECIMALS = Number(process.env.CONTRACT_AMOUNT_DECIMALS ?? 2);
 const RATE_LIMIT_WINDOW_MS = 60_000;
 const RATE_LIMIT_MAX_REQUESTS = 120;
@@ -596,7 +596,7 @@
   }
 });
 
 app.use((err: any, req: Request, res: Response, _next: express.NextFunction) => {
   if (err.type === 'entity.too.large') {
     return res.status(413).json({
       success: false,

backend/src/services/campaignStore.test.ts

@@ -23,7 +23,9 @@ let getPledges: CampaignStoreModule['getPledges'];
 let getGlobalStats: CampaignStoreModule['getGlobalStats'];
 let getDb: DbModule['getDb'];
 let getCampaignHistory: EventHistoryModule['getCampaignHistory'];
+let recordEvent: EventHistoryModule['recordEvent'];
 let addPledge: CampaignStoreModule['addPledge'];
+let getCampaignWithProgress: CampaignStoreModule['getCampaignWithProgress'];
 
 const CREATOR = `G${'A'.repeat(55)}`;
 const CONTRIBUTOR = `G${'B'.repeat(55)}`;
@@ -36,6 +38,7 @@ beforeAll(async () => {
   ({
     createCampaign,
 
+    getCampaignWithProgress,
     initCampaignStore,
     listCampaigns,
     listCampaignPledges,
@@ -46,7 +49,7 @@ beforeAll(async () => {
     addPledge,
   } = await import('./campaignStore'));
   ({ getDb } = await import('./db'));
-  ({ getCampaignHistory } = await import('./eventHistory'));
+  ({ getCampaignHistory, recordEvent } = await import('./eventHistory'));
   initCampaignStore();
 });
 
@@ -166,6 +169,32 @@ describe('on-chain pledge reconciliation', () => {
   });
 });
 
+describe('event-sourced campaign status', () => {
+  it('replays lifecycle transition events to derive the final status', () => {
+    const campaign = createCampaign({
+      creator: CREATOR,
+      title: 'Lifecycle replay campaign',
+      description: 'A campaign used to verify status derivation from event history.',
+      assetCode: 'USDC',
+      targetAmount: 250,
+      deadline: Math.floor(Date.now() / 1000) + 86400,
+    });
+
+    const openedAt = campaign.createdAt + 10;
+    recordEvent(campaign.id, 'campaign_opened', openedAt, campaign.creator);
+    expect(getCampaign(campaign.id)?.createdAt).toBe(campaign.createdAt);
+
+    recordEvent(campaign.id, 'campaign_funded', openedAt + 30, campaign.creator, 250);
+    expect(getCampaignWithProgress(campaign.id)?.progress.status).toBe('funded');
+
+    recordEvent(campaign.id, 'campaign_failed', openedAt + 60, campaign.creator, 0);
+    expect(getCampaignWithProgress(campaign.id)?.progress.status).toBe('failed');
+
+    recordEvent(campaign.id, 'campaign_canceled', openedAt + 90, campaign.creator, 0);
+    expect(getCampaignWithProgress(campaign.id)?.progress.status).toBe('canceled');
+  });
+});
+
 describe('campaign pledge pagination', () => {
   it('returns pledges in reverse chronological order with pagination metadata inputs', () => {
     const futureDeadline = Math.floor(Date.now() / 1000) + 86400;

backend/src/services/campaignStore.ts

@@ -1,7 +1,13 @@
 import { getDb, initDb } from './db';
-import { getCampaignHistory, recordEvent, BlockchainMetadata } from './eventHistory';
+import {
+  getCampaignHistory,
+  recordEvent,
+  BlockchainMetadata,
+  getDerivedCampaignStatus,
+  type CampaignLifecycleStatus,
+} from './eventHistory';
 
-export type CampaignStatus = 'open' | 'funded' | 'claimed' | 'failed';
+export type CampaignStatus = CampaignLifecycleStatus;
 
 export interface CampaignInput {
   creator: string;
@@ -132,6 +138,48 @@
   return Number(value.toFixed(2));
 }
 
+function deriveLegacyCampaignStatus(campaign: CampaignRecord, at: number): CampaignStatus {
+  if (campaign.claimedAt !== undefined) {
+    return 'claimed';
+  }
+  if (campaign.pledgedAmount >= campaign.targetAmount) {
+    return 'funded';
+  }
+  if (at >= campaign.deadline) {
+    return 'failed';
+  }
+  return 'open';
+}
+
+function transitionCampaignToFailed(campaign: CampaignRecord, at: number): boolean {
+  if (
+    campaign.claimedAt === undefined &&
+    campaign.pledgedAmount < campaign.targetAmount &&
+    at >= campaign.deadline &&
+    campaign.failedAt === undefined
+  ) {
+    const db = getDb();
+    db.prepare(`UPDATE campaigns SET failed_at = ? WHERE id = ? AND failed_at IS NULL`).run(
+      campaign.deadline,
+      campaign.id,
+    );
+
+    recordEvent(
+      campaign.id,
+      'campaign_failed',
+      campaign.deadline,
+      campaign.creator,
+      campaign.pledgedAmount,
+      { targetAmount: campaign.targetAmount, deadline: campaign.deadline },
+      { source: 'local' } as BlockchainMetadata,
+    );
+
+    return true;
+  }
+
+  return false;
+}
+
 function rowToCampaign(row: CampaignRow): CampaignRecord {
   const acceptedTokens = JSON.parse(row.accepted_tokens_json);
   return {
@@ -241,24 +289,23 @@
  */
 export function calculateProgress(campaign: CampaignRecord, at = nowInSeconds()): CampaignProgress {
   const deadlineReached = at >= campaign.deadline;
+  const fallbackStatus = deriveLegacyCampaignStatus(campaign, at);
+  if (fallbackStatus === 'failed') {
+    transitionCampaignToFailed(campaign, at);
+  }
+
+  const status = getDerivedCampaignStatus(campaign.id, fallbackStatus);
   const canClaim =
+    status === 'funded' &&
     campaign.claimedAt === undefined &&
     deadlineReached &&
     campaign.pledgedAmount >= campaign.targetAmount;
   const canRefund =
+    status === 'failed' &&
     campaign.claimedAt === undefined &&
     deadlineReached &&
     campaign.pledgedAmount < campaign.targetAmount;
-  const canPledge = campaign.claimedAt === undefined && !deadlineReached;
-
-  let status: CampaignStatus = 'open';
-  if (campaign.claimedAt !== undefined) {
-    status = 'claimed';
-  } else if (campaign.pledgedAmount >= campaign.targetAmount) {
-    status = 'funded';
-  } else if (deadlineReached) {
-    status = 'failed';
-  }
+  const canPledge = status === 'open' && campaign.claimedAt === undefined && !deadlineReached;
 
   return {
     status,
@@ -340,7 +387,7 @@
   const offset = paginate ? (page - 1) * limit : 0;
 
   const whereClauses: string[] = [];
   const params: any[] = [];
 
   if (options?.searchQuery && options.searchQuery.trim()) {
     const searchTerm = `%${options.searchQuery.trim().toLowerCase()}%`;
@@ -422,15 +469,16 @@
   const pledgeCounts: Record<string, number> = {};
   const campaigns = rows.map((row) => {
     pledgeCounts[row.id] = row.pledge_count;
     const { pledge_count, ...campaignRow } = row;
 
     const now = Math.floor(Date.now() / 1000);
-    if (campaignRow.claimed_at === null && campaignRow.pledged_amount < campaignRow.target_amount && now >= campaignRow.deadline && campaignRow.failed_at === null) {
-        campaignRow.failed_at = campaignRow.deadline;
-        db.prepare(`UPDATE campaigns SET failed_at = ? WHERE id = ?`).run(campaignRow.deadline, campaignRow.id);
+    const campaign = rowToCampaign(campaignRow as CampaignRow);
+    if (transitionCampaignToFailed(campaign, now)) {
+      campaignRow.failed_at = campaign.deadline;
+      return rowToCampaign(campaignRow as CampaignRow);
     }
-    
-    return rowToCampaign(campaignRow as CampaignRow);
+
+    return campaign;
   });
 
   return {
@@ -454,11 +502,12 @@
 
   if (row) {
     const now = Math.floor(Date.now() / 1000);
-    if (row.claimed_at === null && row.pledged_amount < row.target_amount && now >= row.deadline && row.failed_at === null) {
-        row.failed_at = row.deadline;
-        db.prepare(`UPDATE campaigns SET failed_at = ? WHERE id = ?`).run(row.deadline, row.id);
+    const campaign = rowToCampaign(row);
+    if (transitionCampaignToFailed(campaign, now)) {
+      row.failed_at = campaign.deadline;
+      return rowToCampaign(row);
     }
-    return rowToCampaign(row);
+    return campaign;
   }
   return undefined;
 }
@@ -658,6 +707,15 @@
     },
     { source: 'local' } as BlockchainMetadata,
   );
+  recordEvent(
+    campaign.id,
+    'campaign_opened',
+    campaign.createdAt,
+    campaign.creator,
+    undefined,
+    { targetAmount: campaign.targetAmount, deadline: campaign.deadline },
+    { source: 'local' } as BlockchainMetadata,
+  );
 
   return campaign;
 }
@@ -732,6 +790,18 @@
     { source: 'local' } as BlockchainMetadata,
   );
 
+  if (campaign.pledgedAmount < campaign.targetAmount && nextPledgedAmount >= campaign.targetAmount) {
+    recordEvent(
+      campaignId,
+      'campaign_funded',
+      createdAt,
+      input.contributor,
+      nextPledgedAmount,
+      { targetAmount: campaign.targetAmount, assetCode },
+      { source: 'local' } as BlockchainMetadata,
+    );
+  }
+
   // Check if contributor has reached their limit and record event
   if (
     campaign.maxPerContributor !== undefined &&
@@ -850,6 +920,21 @@
         txHash: input.transactionHash,
       } as BlockchainMetadata,
     );
+
+    if (campaign.pledgedAmount < campaign.targetAmount && nextPledgedAmount >= campaign.targetAmount) {
+      recordEvent(
+        campaignId,
+        'campaign_funded',
+        createdAt,
+        input.contributor,
+        nextPledgedAmount,
+        { targetAmount: campaign.targetAmount, assetCode, onChain: true },
+        {
+          source: 'soroban',
+          txHash: input.transactionHash,
+        } as BlockchainMetadata,
+      );
+    }
   });
 
   reconcile();
@@ -947,6 +1032,18 @@
         txHash: input.transactionHash,
       } as BlockchainMetadata,
     );
+    recordEvent(
+      campaignId,
+      'campaign_claimed',
+      claimedAt,
+      input.creator,
+      campaign.pledgedAmount,
+      { targetAmount: campaign.targetAmount },
+      {
+        source: 'soroban',
+        txHash: input.transactionHash,
+      } as BlockchainMetadata,
+    );
   });
 
   commit();
@@ -993,6 +1090,16 @@
   if (changes.changes === 0) {
     throw toServiceError('Campaign not found or already deleted.', 404, 'NOT_FOUND');
   }
+
+  recordEvent(
+    campaignId,
+    'campaign_canceled',
+    deletedAt,
+    campaign.creator,
+    undefined,
+    { deletedAt },
+    { source: 'local' } as BlockchainMetadata,
+  );
 }
 
 /**

backend/src/services/eventHistory.ts

@@ -1,6 +1,18 @@
 import { getDb } from './db';
 
-export type CampaignEventType = 'created' | 'pledged' | 'claimed' | 'refunded' | 'updated';
+export type CampaignLifecycleStatus = 'open' | 'funded' | 'claimed' | 'failed' | 'canceled';
+
+export type CampaignEventType =
+  | 'created'
+  | 'pledged'
+  | 'claimed'
+  | 'refunded'
+  | 'updated'
+  | 'campaign_opened'
+  | 'campaign_funded'
+  | 'campaign_claimed'
+  | 'campaign_failed'
+  | 'campaign_canceled';
 
 export interface BlockchainMetadata {
   txHash?: string;
@@ -22,6 +34,16 @@ export interface CampaignEvent {
   blockchainMetadata?: BlockchainMetadata;
 }
 
+const STATUS_TRANSITION_EVENTS: Partial<Record<CampaignEventType, CampaignLifecycleStatus>> = {
+  campaign_opened: 'open',
+  campaign_funded: 'funded',
+  campaign_claimed: 'claimed',
+  campaign_failed: 'failed',
+  campaign_canceled: 'canceled',
+};
+
+const statusCache = new Map<string, CampaignLifecycleStatus>();
+
 interface EventRow {
   id: number;
   campaign_id: string;
@@ -59,6 +81,32 @@ function rowToEvent(row: EventRow): CampaignEvent {
  * @param metadata - Optional arbitrary key-value data about the event.
  * @param blockchainMetadata - Optional on-chain context (tx hash, ledger info, source).
  */
+export function invalidateCampaignStatusCache(campaignId: string): void {
+  statusCache.delete(campaignId);
+}
+
+export function getDerivedCampaignStatus(
+  campaignId: string,
+  fallbackStatus: CampaignLifecycleStatus,
+): CampaignLifecycleStatus {
+  const cachedStatus = statusCache.get(campaignId);
+  if (cachedStatus !== undefined) {
+    return cachedStatus;
+  }
+
+  const history = getCampaignHistory(campaignId);
+  let currentStatus = fallbackStatus;
+  for (const event of history) {
+    const nextStatus = STATUS_TRANSITION_EVENTS[event.eventType];
+    if (nextStatus) {
+      currentStatus = nextStatus;
+    }
+  }
+
+  statusCache.set(campaignId, currentStatus);
+  return currentStatus;
+}
+
 export function recordEvent(
   campaignId: string,
   eventType: CampaignEventType,
@@ -83,6 +131,8 @@ export function recordEvent(
       ? JSON.stringify(blockchainMetadata)
       : null,
   });
+
+  invalidateCampaignStatusCache(campaignId);
 }
 
 export interface CampaignHistoryPage {