Pool Lifecycle

Pool Creation

A creator stakes USDC when making a prediction. This creates a betting pool both in the database and on-chain.

Creator stakes 100 USDC on YES
├── Pool created on-chain (PredictionBetting.sol)
├── Pool recorded in database (BettingPool model)
└── Status: "active"

Market End Time

The smart contract requires a future marketEndTime. It's calculated as:

1. Get Polymarket's end date (often the event START time)
2. Add 4-hour buffer (covers most sporting events)
3. Is the buffered time still in the future?
   ├── YES → Use buffered time
   └── NO → Use "now + 24 hours" as fallback

The 4-hour buffer covers most sporting events (soccer ~2h, basketball ~3h, football ~4h). The 24h fallback is arbitrary — pools close sooner via other triggers.

Pre-Creation Checks

Before creating a pool, the backend verifies:

Market hasn't already resolved on Polymarket
Creator hasn't already bet on this market
Stake amount meets minimum (1 USDC)

Pool Statuses

Status	Code	Meaning
Active	0	Accepting bets
Full	1	Pot matched or betting closed
Resolved	2	Market resolved, withdrawals enabled
Cancelled	3	Creator cancelled, refunds available

Betting Closes

Betting stops when any of these triggers fire:

Trigger	When	Status Change
Pot fully matched	Immediately	`active` → `full`
Creator clicks "Close Betting"	Immediately	`active` → `full`
Pool's marketEndTime passes	Next cron run	`active` → `full`
Polymarket market resolves	Next cron run	`active` → `resolved`

Cancellation

Creators can cancel a pool only if no bets have been placed. On cancellation:

Creator's full stake is refunded from the smart contract
Pool status → cancelled
No fees charged

Edge Cases

On-Chain Creation Failed

If the blockchain transaction fails but the database record was created:

Pool is saved with needsOnChainCreation: true
Creator sees a "Create Betting Pool On Blockchain" retry button
Viewers see "Pending Setup" status

On this page