Skip to main content

Data Flow

Beforehand uses a hybrid architecture where financial operations happen on-chain while metadata and social features are stored off-chain. This document describes how data flows through the system for key operations.

Overview​

Data flows between four main components:

  1. Frontend: React application that users interact with
  2. Smart Contracts: On-chain market contracts that handle trades and payouts
  3. Database: Supabase PostgreSQL storing metadata and social data
  4. Event Listeners: Background processes that sync on-chain events to the database

The system maintains consistency by treating on-chain data as the source of truth for financial operations, while the database provides rich metadata and social features.

Market Creation Flow​

When a user creates a market, the system deploys a new smart contract and stores metadata in the database.

Process​

  1. User fills out market form (question, description, close time, resolution time)
  2. Frontend validates input and checks user permissions
  3. Market contract is deployed on-chain via MarketFactory
  4. Contract address is returned to frontend
  5. User places initial trade (required to activate market)
  6. Market metadata is stored in database with contract address
  7. Market status is set to "pending_match"
  8. Real-time notification sent to community members

Diagram​

Market Creation Flow

Key Points​

  • Contract deployment happens first to get the address
  • Initial trade is required to activate the market
  • Database stores metadata but contract is source of truth for financial state
  • Real-time notifications alert community members of new markets

Trading Flow​

Trading involves on-chain token transactions with off-chain position tracking.

Process​

  1. User selects market and side (YES or NO)
  2. Frontend calculates current price from pool sizes
  3. User enters trade amount and confirms
  4. Frontend requests USDC approval (if needed)
  5. User approves USDC spending
  6. Frontend calls contract to buy tokens
  7. Contract mints position tokens and updates pools
  8. Contract emits Trade event
  9. Frontend queries updated token balance
  10. Database syncs position data from on-chain state
  11. Real-time updates broadcast to other users

Diagram​

Trading Flow

Key Points​

  • USDC approval is a separate transaction (one-time per market)
  • Contract automatically calculates token amount based on pool sizes
  • Position tokens are ERC20 tokens (yUSDC for YES, nUSDC for NO)
  • Event listeners sync on-chain trades to database
  • Real-time updates show trades to all users immediately

Resolution Flow​

Resolution determines the market outcome and distributes payouts to winners.

Process​

  1. Trading closes at the close time
  2. Market status updates to "closed" in database
  3. If community resolution: users vote, votes are weighted by credibility
  4. Admin reviews votes and evidence in database
  5. Admin calls resolveMarket() on contract
  6. Contract sets outcome (YES, NO, or CANCELLED)
  7. Contract enables redemption for winners
  8. Contract emits MarketResolved event
  9. Database updates with outcome
  10. Winners redeem tokens for USDC payouts
  11. Real-time notifications sent to all participants

Diagram​

Resolution Flow

Key Points​

  • Trading closes automatically at the close time
  • Community votes are weighted by credibility scores
  • Admin has final authority to resolve markets
  • Resolution happens on-chain and is immutable
  • Winners must redeem tokens to receive payouts
  • Redemption can happen anytime after resolution

Data Synchronization Flow​

The system continuously syncs on-chain contract state with the off-chain database.

Sync Mechanisms​

  1. Event Listening: Background processes listen to contract events
  2. Polling: Frontend periodically queries contract state
  3. Real-time Subscriptions: Supabase Realtime pushes database changes
  4. Manual Sync: Admin tools can force sync when needed

Diagram​

Data Synchronization Architecture

Key Points​

  • On-chain data is authoritative for financial state
  • Database provides metadata and social features
  • Frontend merges both sources for display
  • Real-time updates keep UI synchronized
  • Event listeners ensure database stays current

Event Flow​

Contract events trigger database updates and UI refreshes.

Event Types​

  • MarketCreated: New market deployed
  • Trade: User placed a trade
  • MarketResolved: Market outcome set
  • MarketCanceled: Market canceled and refunded

Diagram​

Event Flow

Error Handling​

When sync fails or data differs:

  1. On-chain is authoritative: Financial data always comes from contract
  2. Database reconciliation: Sync jobs update database to match contract
  3. User notification: Frontend shows warnings if data differs
  4. Manual override: Admins can force sync if needed

The system prioritizes on-chain accuracy for financial operations while maintaining database consistency for metadata.