Escrow System

The escrow system ensures both players' funds are secure and the winner gets paid automatically.

Why Escrow?

Without escrow, wagering has a trust problem:

❌ Bad: "Send me $10, if I lose I'll send $20 back"
   → Loser can just... not pay

✅ Good: "We both send $10 to a neutral third party"
   → Neutral party pays winner automatically

PokeDexter's escrow is that neutral third party - except it's code, not a person.

How It Works

1. Escrow Creation

When a wager is accepted:

• A fresh Solana wallet (keypair) is generated just for this match
• The public address is shared with both players for deposits
• The private key is encrypted and stored securely

Each match gets its own escrow. If one is somehow compromised, others are unaffected.

2. Deposits

Both players send USDC to the escrow address:

• Server monitors the escrow balance
• Once both deposits arrive, the battle can start
• If someone doesn't deposit within 5 minutes, the wager cancels

3. Battle

Standard Pokémon battle. The escrow just holds the funds until there's a winner.

4. Settlement

When the battle ends:

1. Server determines the winner
2. Escrow sends funds to winner's wallet (minus house fee)
3. Transaction recorded on-chain
4. Wager marked as settled

No human intervention - settlement is triggered automatically by the battle ending.

Security Properties

Encrypted at Rest

Private keys are encrypted before storage. Even if the database is compromised, keys are unreadable without the encryption key.

Per-Match Isolation

Every match has its own escrow wallet. No shared funds, no cross-contamination.

Automatic Settlement

Settlement triggers on battle end - no one can delay or withhold payouts.

On-Chain Verification

All settlements are Solana transactions. Anyone can verify payouts on Solscan or Solana Explorer.

Crash Recovery

Escrow data persists to database. Server can restart without losing active wagers.

Wager Lifecycle

Edge Cases

Timeout: One Player Doesn't Deposit

After 5 minutes without both deposits:

1. Wager auto-cancels
2. Any deposited funds returned
3. Both players notified

Draw

Draws are rare but can happen (both last Pokémon faint simultaneously).

Behavior: Funds held pending admin review, typically 50/50 split.

Next Steps