A batch of ${pending.rows.length} payout(s) failed and was marked needs_review to avoid a possible double-payout.
` + + `Payout IDs: ${ids.join(', ')}
Error: ${err.message}
` + }).catch(() => {}); } } } diff --git a/src/migrations/015_payout_batch_tx_hash.sql b/src/migrations/015_payout_batch_tx_hash.sql new file mode 100644 index 0000000..e2f0a29 --- /dev/null +++ b/src/migrations/015_payout_batch_tx_hash.sql @@ -0,0 +1,20 @@ +-- Migration 015: Allow batched payouts to share a tx_hash; tighten one-per-game guard +-- +-- `transfer_split` sends ONE on-chain transaction to many destinations, so multiple +-- payout rows in a batch legitimately share the same tx_hash. The old UNIQUE index on +-- payouts.tx_hash (migration 008) made the 2nd+ row in a batch fail to record its +-- tx_hash, leaving funds already sent but rows stranded in 'processing' — and at risk +-- of being re-sent by the retry service (a double-payout vector). +-- +-- Payout idempotency does NOT depend on tx_hash uniqueness; it is enforced by +-- idx_payouts_one_per_game (one active payout per game). So we drop the payouts +-- tx_hash unique index. (The payments.tx_hash unique index stays — incoming payments +-- are 1:1 with a transaction.) +DROP INDEX IF EXISTS idx_payouts_tx_hash_unique; + +-- Extend the one-active-payout-per-game guard to also cover 'processing', so a second +-- payable row cannot be inserted for a game while its payout is mid-flight. +DROP INDEX IF EXISTS idx_payouts_one_per_game; +CREATE UNIQUE INDEX IF NOT EXISTS idx_payouts_one_per_game +ON payouts(game_id) +WHERE game_id IS NOT NULL AND status IN ('pending', 'processing', 'completed'); diff --git a/test/batchPayout.test.js b/test/batchPayout.test.js new file mode 100644 index 0000000..7a06efc --- /dev/null +++ b/test/batchPayout.test.js @@ -0,0 +1,111 @@ +/** + * Batch payout dispatch tests (Phase 0.3). + * + * transfer_split sends ONE on-chain tx to many destinations, so every payout row in a + * batch shares that tx_hash. These tests guard: + * - the whole batch is marked completed with the shared tx_hash in one transaction + * (no row stranded mid-batch by a unique-index collision), and + * - an ambiguous batch failure is marked 'needs_review' (NOT 'failed'), so the retry + * service won't re-send and double-pay. + */ + +const GameModeManager = require('../src/game/gameModeManager'); + +const createMockDb = () => { + const mockClient = { query: jest.fn().mockResolvedValue({ rows: [] }) }; + return { + query: jest.fn().mockResolvedValue({ rows: [] }), + withTransaction: jest.fn().mockImplementation(async (cb) => cb(mockClient)), + _mockClient: mockClient + }; +}; + +const createMockPaymentConfig = () => ({ + getConfig: () => ({ + paymentsEnabled: true, + currency: { symbol: 'WOW', decimals: 11 }, + modes: { + direct: { enabled: true, price: 100000000000n }, + credits: { enabled: true, creditsPerGame: 1, packages: [{ id: 'small', credits: 10, price: '500000000000', bonus: 0 }] } + }, + payouts: { + rules: { + direct: { enabled: true, multipliers: { escape: 2, escapeWithTreasure: 3 } }, + credits: { enabled: false, multipliers: { escape: 1.5, escapeWithTreasure: 2 }, baseValue: 50000000000n } + } + }, + preferences: { preferCreditsFirst: true }, + earlyEntry: { enabled: false } + }), + getLegacyGameMode: () => 'PAID_SINGLE', + eventBus: { on: () => {} } +}); + +function buildGmm(walletService) { + const db = createMockDb(); + const debugManager = { CONSOLE_LOGGING: false, getCurrentBlockHeight: () => 1 }; + const gmm = new GameModeManager(db, walletService, debugManager, createMockPaymentConfig()); + return { gmm, db }; +} + +const TWO_PENDING = [ + { id: 10, user_id: 1, game_id: 'g1', payout_address: 'addrA', amount: '200000000000', multiplier: 2, reason: 'escape' }, + { id: 11, user_id: 2, game_id: 'g2', payout_address: 'addrB', amount: '300000000000', multiplier: 3, reason: 'escape' } +]; + +describe('Batch payout dispatch', () => { + test('marks the whole batch completed with the shared tx_hash in one transaction', async () => { + const walletService = { + processPayout: jest.fn(), + processBatchPayout: jest.fn().mockResolvedValue({ tx_hash_list: ['txSHARED'], totalFee: 200 }) + }; + const { gmm, db } = buildGmm(walletService); + + // First withTransaction = gather: SELECT returns 2 pending rows, then UPDATE ... processing. + db._mockClient.query + .mockResolvedValueOnce({ rows: TWO_PENDING }) // SELECT ... FOR UPDATE SKIP LOCKED + .mockResolvedValue({ rows: [] }); // everything else + + await gmm._processPendingPayouts(); + + // The batch RPC was called once with both destinations. + expect(walletService.processBatchPayout).toHaveBeenCalledTimes(1); + expect(walletService.processBatchPayout.mock.calls[0][0]).toHaveLength(2); + + // The completion UPDATE set the shared tx_hash on the whole batch via id = ANY(...). + const calls = db._mockClient.query.mock.calls.map(c => c[0]); + const batchUpdate = calls.find(sql => /UPDATE payouts SET tx_hash/i.test(sql) && /id = ANY/i.test(sql)); + expect(batchUpdate).toBeDefined(); + expect(batchUpdate).toMatch(/status = 'completed'/); + + const batchUpdateCall = db._mockClient.query.mock.calls.find(c => /UPDATE payouts SET tx_hash/i.test(c[0]) && /id = ANY/i.test(c[0])); + expect(batchUpdateCall[1][0]).toBe('txSHARED'); // tx_hash param + expect(batchUpdateCall[1][3]).toEqual([10, 11]); // ids array + + // Per-user stats incremented for each winner inside the same transaction (BIGINT, no float). + const statUpdates = calls.filter(sql => /UPDATE users SET total_amount_won/i.test(sql)); + expect(statUpdates.length).toBe(2); + }); + + test('an ambiguous batch failure is marked needs_review, not failed', async () => { + const walletService = { + processPayout: jest.fn(), + processBatchPayout: jest.fn().mockRejectedValue(new Error('RPC timeout')) + }; + const { gmm, db } = buildGmm(walletService); + + db._mockClient.query + .mockResolvedValueOnce({ rows: TWO_PENDING }) + .mockResolvedValue({ rows: [] }); + + await gmm._processPendingPayouts(); + + // Failure handling uses db.query (outside a transaction) to mark the batch needs_review. + const failCall = db.query.mock.calls.find(c => /needs_review/i.test(c[0])); + expect(failCall).toBeDefined(); + expect(failCall[0]).toMatch(/id = ANY/i); + // Must NOT mark them 'failed' (which the retry service would auto-resend). + const failedCall = db.query.mock.calls.find(c => /status = 'failed'/i.test(c[0])); + expect(failedCall).toBeUndefined(); + }); +});