feat(payouts): enforce configurable minimum payout via MIN_STELLAR_PAYOUT

src/config/config.service.spec.ts

@@ -0,0 +1,60 @@
+import { ConfigService } from './config.service';
+
+describe('ConfigService', () => {
+  afterEach(() => {
+    delete process.env.MIN_STELLAR_PAYOUT;
+  });
+
+  describe('minStellarPayout', () => {
+    it('defaults to 5 when MIN_STELLAR_PAYOUT is not set', () => {
+      delete process.env.MIN_STELLAR_PAYOUT;
+      const service = new ConfigService();
+      expect(service.minStellarPayout).toBe(5);
+    });
+
+    it('parses a valid positive integer', () => {
+      process.env.MIN_STELLAR_PAYOUT = '10';
+      const service = new ConfigService();
+      expect(service.minStellarPayout).toBe(10);
+    });
+
+    it('parses a valid positive decimal', () => {
+      process.env.MIN_STELLAR_PAYOUT = '2.5';
+      const service = new ConfigService();
+      expect(service.minStellarPayout).toBe(2.5);
+    });
+
+    it('throws at startup when MIN_STELLAR_PAYOUT is a non-numeric string', () => {
+      process.env.MIN_STELLAR_PAYOUT = 'five';
+      expect(() => new ConfigService()).toThrow(
+        /Invalid MIN_STELLAR_PAYOUT/,
+      );
+    });
+
+    it('throws at startup when MIN_STELLAR_PAYOUT is zero', () => {
+      process.env.MIN_STELLAR_PAYOUT = '0';
+      expect(() => new ConfigService()).toThrow(
+        /Invalid MIN_STELLAR_PAYOUT/,
+      );
+    });
+
+    it('throws at startup when MIN_STELLAR_PAYOUT is negative', () => {
+      process.env.MIN_STELLAR_PAYOUT = '-5';
+      expect(() => new ConfigService()).toThrow(
+        /Invalid MIN_STELLAR_PAYOUT/,
+      );
+    });
+
+    it('throws at startup when MIN_STELLAR_PAYOUT is empty string', () => {
+      process.env.MIN_STELLAR_PAYOUT = '';
+      expect(() => new ConfigService()).toThrow(
+        /Invalid MIN_STELLAR_PAYOUT/,
+      );
+    });
+
+    it('error message includes the invalid value', () => {
+      process.env.MIN_STELLAR_PAYOUT = 'abc';
+      expect(() => new ConfigService()).toThrow('"abc"');
+    });
+  });
+});

src/config/config.service.ts

@@ -4,6 +4,8 @@ import { Injectable } from '@nestjs/common';
 export class ConfigService {
   readonly earningsCacheTtlSeconds = parseInt(process.env.EARNINGS_CACHE_TTL ?? '3600', 10);
 
+  readonly minStellarPayout: number;
+
   readonly leaderboardEnabled = process.env.LEADERBOARD_ENABLED === 'true';
 
   readonly creatorRoyaltyBps = parseInt(process.env.CREATOR_ROYALTY_BPS ?? '1000', 10);
@@ -54,4 +56,15 @@ export class ConfigService {
   readonly redisPort = parseInt(process.env.REDIS_PORT ?? '6379', 10);
 
   readonly redisPassword = process.env.REDIS_PASSWORD;
+
+  constructor() {
+    const raw = process.env.MIN_STELLAR_PAYOUT ?? '5';
+    const parsed = parseFloat(raw);
+    if (!isFinite(parsed) || parsed <= 0) {
+      throw new Error(
+        `Invalid MIN_STELLAR_PAYOUT: "${raw}" — must be a positive number`,
+      );
+    }
+    this.minStellarPayout = parsed;
+  }
 }

src/payouts/payouts.module.ts

@@ -16,6 +16,7 @@ import { MetricsModule } from '../metrics/metrics.module';
 import { PayoutRetryProcessor } from './payout-retry.processor';
 import { PAYOUT_RETRY_QUEUE, PAYOUT_RETRY_QUEUE_PRIORITY } from './payout-retry.queue';
 import { PayoutApprovalService } from './payout-approval.service';
+import { ConfigService } from '../config/config.service';
 
 @Module({
   imports: [
@@ -42,6 +43,7 @@ import { PayoutApprovalService } from './payout-approval.service';
     PayoutMethodService,
     PayoutRetryProcessor,
     PayoutApprovalService,
+    ConfigService,
   ],
   exports: [PayoutsService, FeeService, PayoutMethodService],
 })