Merge pull request #154 from nice-bills/feat/contributor-pledge-limit

feat: add per-contributor pledge limit per campaign

Author: ritik4ever

README.md

@@ -100,6 +100,7 @@ Request body:
 - `assetCode`
 - `targetAmount`
 - `deadline`
+- `maxPerContributor` (optional): Maximum total pledge amount a single contributor can contribute to this campaign. If not set, no per-contributor limit applies. Can also be set globally via `DEFAULT_MAX_PER_CONTRIBUTOR` env variable.
 
 ### `POST /api/campaigns/:id/pledges`
 - Add a pledge to a live campaign

backend/src/config.ts

@@ -31,6 +31,7 @@ export const config = {
   contractId: process.env.CONTRACT_ID ?? "",
   sorobanNetworkPassphrase:
     process.env.SOROBAN_NETWORK_PASSPHRASE ?? "Test SDF Network ; September 2015",
+  defaultMaxPerContributor: parseInteger(process.env.DEFAULT_MAX_PER_CONTRIBUTOR, 0),
 };
 
-export const walletIntegrationReady = Boolean(config.contractId && config.sorobanRpcUrl);
+export const walletIntegrationReady = Boolean(config.contractId && config.sorobanRpcUrl);

backend/src/index.ts

@@ -39,6 +39,9 @@ import {
 } from "./validation/schemas";
 import { logError, logInfo, logRequest } from "./logger";
 
+type RequestWithId = Request & { requestId?: string };
+type CampaignListItem = ReturnType<typeof import("./services/campaignStore").getCampaign> & { progress: ReturnType<typeof import("./services/campaignStore").calculateProgress> };
+
 export const app = express();
 
 interface RequestWithId extends Request {
@@ -302,13 +305,20 @@ app.post("/api/campaigns", (req: Request, res: Response) => {
   const parsedBody = createCampaignPayloadSchema.safeParse(req.body);
   if (!parsedBody.success) {
     sendValidationError(parsedBody.error.issues);
+    return;
   }
 
   if (parsedBody.data.deadline <= Math.floor(Date.now() / 1000)) {
     throw new AppError("deadline must be in the future.", 400, "INVALID_DEADLINE");
   }
 
-  const campaign = createCampaign(parsedBody.data);
+  const campaignInput = {
+    ...parsedBody.data,
+    maxPerContributor:
+      parsedBody.data.maxPerContributor ?? (config.defaultMaxPerContributor > 0 ? config.defaultMaxPerContributor : undefined),
+  };
+
+  const campaign = createCampaign(campaignInput);
   res.status(201).json({ data: { ...campaign, progress: calculateProgress(campaign) } });
 });
 

backend/src/services/campaignStore.test.ts

@@ -24,9 +24,11 @@ let getPledges: CampaignStoreModule["getPledges"];
 let getGlobalStats: CampaignStoreModule["getGlobalStats"];
 let getDb: DbModule["getDb"];
 let getCampaignHistory: EventHistoryModule["getCampaignHistory"];
+let addPledge: CampaignStoreModule["addPledge"];
 
 const CREATOR = `G${"A".repeat(55)}`;
 const CONTRIBUTOR = `G${"B".repeat(55)}`;
+const CONTRIBUTOR2 = `G${"C".repeat(55)}`;
 const TX_HASH = "a".repeat(64);
 
 beforeAll(async () => {
@@ -40,7 +42,7 @@ beforeAll(async () => {
     reconcileOnChainPledge,
     getCampaign,
     getPledges,
-    getGlobalStats,
+
   } = await import("./campaignStore"));
   ({ getDb } = await import("./db"));
   ({ getCampaignHistory } = await import("./eventHistory"));
@@ -163,3 +165,4 @@ describe("on-chain pledge reconciliation", () => {
   });
 });
 
+

backend/src/services/campaignStore.ts

@@ -14,6 +14,7 @@ export interface CampaignInput {
     imageUrl?: string;
     externalLink?: string;
   };
+  maxPerContributor?: number;
 }
 
 export interface PledgeInput {
@@ -42,6 +43,7 @@ export interface CampaignRecord {
     imageUrl?: string;
     externalLink?: string;
   };
+  maxPerContributor?: number;
 }
 
 export interface CampaignProgress {
@@ -90,6 +92,7 @@ interface CampaignRow {
   claimed_at: number | null;
   deleted_at: number | null;
   metadata_json: string | null;
+  max_per_contributor: number | null;
 }
 
 interface PledgeRow {
@@ -136,6 +139,7 @@ function rowToCampaign(row: CampaignRow): CampaignRecord {
     claimedAt: row.claimed_at ?? undefined,
     deletedAt: row.deleted_at ?? undefined,
     metadata: row.metadata_json ? JSON.parse(row.metadata_json) : undefined,
+    maxPerContributor: row.max_per_contributor ?? undefined,
   };
 }
 
@@ -180,6 +184,19 @@ function getPledgeByTransactionHash(transactionHash: string): PledgeRecord | und
   return row ? rowToPledge(row) : undefined;
 }
 
+function getContributorPledgedTotal(campaignId: string, contributor: string): number {
+  const db = getDb();
+  const row = db
+    .prepare(
+      `SELECT COALESCE(SUM(amount), 0) AS total
+       FROM pledges
+       WHERE campaign_id = ? AND contributor = ? AND refunded_at IS NULL`,
+    )
+    .get(campaignId, contributor) as { total: number };
+
+  return row.total;
+}
+
 export function initCampaignStore(): void {
   initDb();
 }
@@ -256,8 +273,8 @@ export function listCampaigns(options?: ListCampaignsOptions): ListCampaignsResu
   if (options?.searchQuery && options.searchQuery.trim()) {
     const searchTerm = `%${options.searchQuery.trim().toLowerCase()}%`;
     whereClauses.push(`(
-      LOWER(id) LIKE ? OR 
-      LOWER(title) LIKE ? OR 
+      LOWER(id) LIKE ? OR
+      LOWER(title) LIKE ? OR
       LOWER(creator) LIKE ?
     )`);
     params.push(searchTerm, searchTerm, searchTerm);
@@ -374,18 +391,20 @@ export function createCampaign(input: CampaignInput): CampaignRecord {
     deadline: input.deadline,
     createdAt: now,
     metadata: input.metadata,
+    maxPerContributor: input.maxPerContributor,
   };
 
   db.prepare(
     `INSERT INTO campaigns (
-      id, creator, title, description, asset_code, target_amount, pledged_amount, deadline, created_at, claimed_at, metadata_json
+      id, creator, title, description, asset_code, target_amount, pledged_amount, deadline, created_at, claimed_at, metadata_json, max_per_contributor
     ) VALUES (
-      @id, @creator, @title, @description, @assetCode, @targetAmount, @pledgedAmount, @deadline, @createdAt, @claimedAt, @metadataJson
+      @id, @creator, @title, @description, @assetCode, @targetAmount, @pledgedAmount, @deadline, @createdAt, @claimedAt, @metadataJson, @maxPerContributor
     )`,
   ).run({
     ...campaign,
     claimedAt: null,
     metadataJson: campaign.metadata ? JSON.stringify(campaign.metadata) : null,
+    maxPerContributor: campaign.maxPerContributor ?? null,
   });
 
   recordEvent(
@@ -406,6 +425,25 @@ export function createCampaign(input: CampaignInput): CampaignRecord {
   return campaign;
 }
 
+function checkContributorLimit(
+  campaign: CampaignRecord,
+  contributor: string,
+  amount: number,
+): void {
+  if (campaign.maxPerContributor === undefined) {
+    return;
+  }
+
+  const alreadyPledged = getContributorPledgedTotal(campaign.id, contributor);
+  if (alreadyPledged + amount > campaign.maxPerContributor) {
+    throw toServiceError(
+      `Contributor limit exceeded. Max: ${campaign.maxPerContributor}, Already pledged: ${alreadyPledged}, Attempted: ${amount}`,
+      400,
+      "CONTRIBUTOR_LIMIT_EXCEEDED",
+    );
+  }
+}
+
 export function addPledge(campaignId: string, input: PledgeInput): CampaignRecord {
   const db = getDb();
   const campaign = getCampaign(campaignId);
@@ -422,6 +460,8 @@ export function addPledge(campaignId: string, input: PledgeInput): CampaignRecor
     );
   }
 
+  checkContributorLimit(campaign, input.contributor, input.amount);
+
   const createdAt = nowInSeconds();
   const roundedAmount = round(input.amount);
   const nextPledgedAmount = round(campaign.pledgedAmount + roundedAmount);
@@ -489,6 +529,8 @@ export function reconcileOnChainPledge(
     );
   }
 
+  checkContributorLimit(campaign, input.contributor, input.amount);
+
   const db = getDb();
   const createdAt = input.confirmedAt ?? nowInSeconds();
   const roundedAmount = round(input.amount);
@@ -600,7 +642,6 @@ function reconcileOnChainClaim(
     );
   }
 
-  // Idempotency: if already claimed with this tx hash, return current state
   if (campaign.claimedAt) {
     return campaign;
   }
@@ -724,4 +765,4 @@ export function refundContributor(
     campaign: getCampaign(campaignId)!,
     refundedAmount,
   };
-}
+}

backend/src/services/db.ts

@@ -69,27 +69,28 @@ export function checkDbHealth(): {
 function migrate(database: SQLiteDatabase): void {
   database.exec(`
     CREATE TABLE IF NOT EXISTS campaigns (
-      id              TEXT PRIMARY KEY,
-      creator         TEXT NOT NULL,
-      title           TEXT NOT NULL,
-      description     TEXT NOT NULL,
-      asset_code      TEXT NOT NULL,
-      target_amount   REAL NOT NULL,
-      pledged_amount  REAL NOT NULL DEFAULT 0,
-      deadline        INTEGER NOT NULL,
-      created_at      INTEGER NOT NULL,
-      claimed_at      INTEGER,
-      metadata_json   TEXT
+      id                    TEXT PRIMARY KEY,
+      creator               TEXT NOT NULL,
+      title                 TEXT NOT NULL,
+      description           TEXT NOT NULL,
+      asset_code            TEXT NOT NULL,
+      target_amount         REAL NOT NULL,
+      pledged_amount        REAL NOT NULL DEFAULT 0,
+      deadline              INTEGER NOT NULL,
+      created_at            INTEGER NOT NULL,
+      claimed_at            INTEGER,
+      metadata_json          TEXT,
+      max_per_contributor   INTEGER
     );
 
     CREATE TABLE IF NOT EXISTS pledges (
       id                INTEGER PRIMARY KEY AUTOINCREMENT,
       campaign_id       TEXT NOT NULL,
-      contributor       TEXT NOT NULL,
-      amount            REAL NOT NULL,
-      created_at        INTEGER NOT NULL,
-      refunded_at       INTEGER,
-      transaction_hash  TEXT,
+      contributor      TEXT NOT NULL,
+      amount           REAL NOT NULL,
+      created_at       INTEGER NOT NULL,
+      refunded_at      INTEGER,
+      transaction_hash TEXT,
       FOREIGN KEY (campaign_id) REFERENCES campaigns(id)
     );
 
@@ -133,10 +134,21 @@ function migrate(database: SQLiteDatabase): void {
     // Column already exists, ignore error.
   }
 
+  const campaignColumns = database
+    .prepare(`PRAGMA table_info(campaigns)`)
+    .all() as Array<{ name: string }>;
+
+  const hasMaxPerContributor = campaignColumns.some(
+    (column) => column.name === "max_per_contributor",
+  );
+  if (!hasMaxPerContributor) {
+    database.exec(`ALTER TABLE campaigns ADD COLUMN max_per_contributor INTEGER`);
+  }
+
   database.exec(`
     CREATE INDEX IF NOT EXISTS idx_campaign_events_tx_hash
     ON campaign_events(json_extract(blockchain_metadata, '$.txHash'));
     CREATE INDEX IF NOT EXISTS idx_campaign_events_ledger
     ON campaign_events(json_extract(blockchain_metadata, '$.ledgerNumber'));
   `);
-}
+}

backend/src/validation/schemas.ts

@@ -33,6 +33,13 @@ export const positiveAmountSchema = z.coerce
   .finite("Amount must be a valid number.")
   .positive("Amount must be greater than zero.");
 
+export const optionalPositiveIntSchema = z.coerce
+  .number()
+  .finite("Value must be a valid number.")
+  .int("Value must be an integer.")
+  .nonnegative("Value must be non-negative.")
+  .optional();
+
 export const unixTimestampSchema = z.coerce
   .number()
   .int("deadline must be a valid UNIX timestamp in seconds.")
@@ -55,6 +62,7 @@ export const createCampaignPayloadSchema = z.object({
       externalLink: z.string().url().optional(),
     })
     .optional(),
+  maxPerContributor: optionalPositiveIntSchema,
 });
 
 export const createPledgePayloadSchema = z.object({
@@ -190,4 +198,4 @@ export function zodIssuesToErrorMessage(issues: z.ZodIssue[]): string {
   return zodIssuesToValidationIssues(issues)
     .map(({ field, message }) => `${field}: ${message}`)
     .join("; ");
-}
+}