Skip to main content

Referees

The referee is the bridge between the blockchain and game logic. It watches on-chain events, executes FISE JavaScript in a deterministic sandbox, and signs settlement transactions. Without the referee, the contracts hold money but don't know who won.

What the Referee Does​

Every match on FALKEN requires a referee to:

  1. Watch — detect on-chain events (match created, player joined, move submitted)
  2. Reconstruct — rebuild the full game state from the database
  3. Execute — run the FISE game logic in a sandboxed environment
  4. Settle — sign and submit the result back on-chain

The referee never holds player funds. It only has permission to call settlement functions on the contracts. The money flows directly from the contract to the winner.

The Falken VM​

The referee software is called the Falken VM. It's a Node.js service with four components that work together:

Watcher​

The Watcher maintains a WebSocket connection to a Base RPC node and listens for contract events in real time:

  • MatchCreated — new match registered, start tracking it
  • PlayerJoined — player entered the match
  • MatchActivated — all players in, game begins
  • MovePlayed — a player submitted a move
  • EntropyRevealed — a player's salt was revealed (poker)

When a relevant event fires, the Watcher triggers the next step in the referee pipeline. It also writes events to Supabase so the dashboard and indexer stay in sync.

Reconstructor​

The Reconstructor builds the current game state from Supabase. The referee is stateless — it doesn't keep game state in memory between events. Every time it needs to act, it queries the database for:

  • Match configuration (game type, stake, players, round number)
  • All moves submitted so far
  • Entropy salts (for poker deck derivation)
  • Current phase and turn information

This stateless design means the referee can crash and restart without losing anything. The blockchain and database are the source of truth — the referee is just a processor.

FISE Sandbox​

The core execution engine. It loads the game's JavaScript from IPFS and runs it inside a QuickJS WebAssembly sandbox:

Why QuickJS WASM?

The sandbox must guarantee determinism — identical inputs must always produce identical outputs. QuickJS compiled to WebAssembly provides:

  • Memory isolation — the game logic cannot access the host process
  • No system APIs — no network, filesystem, or clock access
  • Deterministic execution — no sources of randomness or non-determinism
  • Fast startup — VMs are created and destroyed per execution, no lingering state

Code transformation happens before execution:

  • import { ethers } from 'ethers' is stripped (not available in sandbox)
  • The game class is extracted from various export patterns
  • Code is wrapped in an IIFE for safe execution

Settler​

The Settler holds the referee's private key and signs settlement transactions. When the FISE sandbox determines a winner, the Settler calls the appropriate contract function:

  • Poker — resolveRound(matchId, winnerIndex, ...) or resolveShowdownSplit(...)
  • Turn-based — settleRound(matchId, winnerIndex, result)

The Settler is the only component with signing authority. The Watcher, Reconstructor, and Sandbox never touch the private key.

Trust Model​

Current: Centralized Referee​

Today, FALKEN runs a single referee operated by the protocol team. Players trust that it executes the correct FISE code faithfully.

This trust is bounded by strong guarantees:

What the referee CAN'T doWhy
Steal fundsIt only calls settlement functions — funds flow from contract to winner, never through the referee
Use different game logicThe JS is pinned to IPFS with a hash registered on-chain — the referee can't swap it
Fabricate movesEvery move is an on-chain transaction signed by the player's wallet
Produce different results from the same inputsFISE execution is deterministic — anyone can verify by replaying
What the referee CAN doRisk
Delay settlementTimeouts protect against this — players can claim wins after deadline
Go offlineMatches stall, but funds are safe in escrow. Admin void can rescue stuck matches
Submit incorrect resultsVerifiable post-hoc, but damage is done until detected

The last point — incorrect results — is the core risk. It's mitigated today by the protocol team's reputation and the ability for anyone to independently verify results. But it's not trustless.

The path to full trustlessness is a decentralized referee network — see the roadmap for details.