Paper Trading Backend

The paper backend is the no-real-value proving ground for Arenaton Exchange. It lives in the Go pulse server and mirrors the production exchange shape while staying isolated on Polygon Amoy with PaperUSDC.

Paper mode must be useful enough to test the whole flow, but it must never blur into production funds, production order books, or production registries.

Spine

Flutter paper app
  -> PaperUSDC faucet
  -> EIP-712 order signing
  -> Go paper exchange order intake
  -> price/time matching
  -> settlement run
  -> CTF-style position deltas
  -> lifecycle and resolution
  -> direct redemption
  -> WebSocket and portfolio projection

Core Modules

Module	Responsibility
Order intake	Validate JSON, account, signature, registry, collateral, fee, expiry, and Live State Version.
Matching	Apply price/time priority, maker/taker semantics, self-trade prevention, and partial fills.
Settlement	Confirm primary split or resale transfer semantics and emit position deltas.
Lifecycle	Close, resolve, finalize, invalidate, and expose redeemable Markets.
Faucet	Mint no-value PaperUSDC with rate limits and maximum balance rules.
Indexer projection	Aggregate confirmed position deltas and subtract redemptions.
Incident controls	Pause intake, hide Markets, set close-only mode, retry settlement, and publish audit notes.
WebSocket hub	Broadcast book, fill, lifecycle, live-state, portfolio, redemption, and status events.

Order States

OPEN
  -> MATCHED_PENDING_SETTLEMENT
  -> SETTLED
  -> CANCELED
  -> EXPIRED
  -> STALE

An order becomes stale when its liveStateVersion no longer matches the Market. Material game, score, period, feed, or final-state changes must invalidate old live orders.

Matching Rules

1. Better price wins.
2. Earlier submission wins at the same price.
3. Resting orders are makers; incoming orders are takers.
4. Buy YES plus buy NO can settle as a primary binary split.
5. Buy YES plus sell YES can settle as secondary resale.
6. Buy NO plus sell NO can settle as secondary resale.
7. The same beneficial account must not self-trade.
8. Partial fills reduce remaining quantity without changing the original digest.

Settlement Modes

Primary Binary Split

YES buyer signs buy YES at price P
NO buyer signs buy NO at price 1 - P or better
settlement confirms both signatures
settlement splits Collateral into YES and NO Outcome Shares
position deltas credit both buyers

Secondary Resale

seller owns YES
seller signs sell YES
buyer signs buy YES
settlement transfers Collateral to seller
settlement transfers YES Outcome Shares to buyer
position deltas debit seller and credit buyer

Failed resale must not create user debt. If approval, balance, signature, expiry, cancellation, Live State Version, or registry validation fails, the fill stays failed/retryable according to the worker path.

Lifecycle And Redemption

DRAFT
  -> SCHEDULED
  -> OPEN_PRE_EVENT
  -> OPEN_LIVE
  -> CLOSING
  -> CLOSED_PENDING_RESOLUTION
  -> RESOLVED or INVALID
  -> REDEEMABLE

Redeemable Markets appear only after final resolution. Redemption subtracts confirmed positions from the projection and emits a redemption event.

API Surface

GET  /api/paper/markets
GET  /api/paper/markets/{marketId}
GET  /api/paper/markets/{marketId}/book
GET  /api/paper/markets/{marketId}/trades
GET  /api/paper/markets/{marketId}/rules

POST /api/paper/faucet/claim
POST /api/paper/orders
POST /api/paper/orders/{orderId}/cancel
POST /api/paper/settlement/run

GET  /api/paper/accounts/{account}/portfolio
GET  /api/paper/accounts/{account}/positions
GET  /api/paper/accounts/{account}/fills
GET  /api/paper/accounts/{account}/orders

POST /api/paper/markets/{marketId}/live-events/simulate
POST /api/paper/markets/{marketId}/close
POST /api/paper/markets/{marketId}/resolve
POST /api/paper/markets/{marketId}/resolution/finalize
POST /api/paper/markets/{marketId}/redeem

GET  /api/paper/status
WS   /api/paper/ws

Admin endpoints exist for incident controls and audit logs. They must stop new risk without mutating settled user positions or blocking allowed cancellation/redemption paths.

WebSocket Events

paper_market_book
paper_matched_pending_fill
paper_settlement_confirmed
paper_account_positions
paper_market_lifecycle
paper_redemption_confirmed
paper_market_live_state
paper_status

Safety Guarantees

• PaperUSDC has no real value.
• Paper and production order books are separate.
• Paper and production contract registries are separate.
• Paper builds refuse Polygon mainnet signing.
• Production builds refuse Amoy signing.
• Pending fills are not confirmed Outcome Shares.
• Portfolio positions derive from confirmed settlement/indexer state.
• No admin path may transfer user Collateral or Outcome Shares.

Release Evidence

Paper backend changes require evidence that order intake, matching, settlement, lifecycle, redemption, WebSocket projection, and admin incident controls still preserve user asset boundaries.