The Clockwork Croupier: Unpacking algo-prediction-core

How a Python daemon and a 114-byte state machine orchestrate a high-frequency prediction market on Algorand.

8 min read • View on GitHub • More from goosealgo

A mechanical pocket watch split down the middle, half physical gears and half digital code. This illustrates the split-brain architecture of the off-chain Python daemon and the on-chain Algorand smart contract. — The system relies on a continuous off-chain clock driving a rigid on-chain judge.

Key Takeaways

A Python daemon acts as the system clock to push state transitions to a rigid Algorand smart contract.
The entire market round state is packed into a highly efficient 114-byte binary-compatible ARC4 struct using Algorand Box Storage.
Integer-first math and strict accounting invariants physically separate user funds from protocol fees to prevent bank runs.
Automated deployment scripts regex-patch smart contract IDs directly into the frontend configuration.

The Split-Brain Architecture

A smart contract cannot execute itself. It requires an external trigger to advance its state. In high-frequency prediction markets, this creates a fundamental design challenge. The developers of algo-prediction-core solved this by building a split-brain system. The Algorand smart contract acts as an incorruptible judge, but a Python daemon acts as the relentless clock.

The daemon, auto_settle.py, runs constantly. It polls the Coinbase API for price data and pushes state transitions (OPEN, LOCKED, CLOSED) to the blockchain using an AtomicTransactionComposer. If the daemon fails, the contract freezes safely. If the daemon is compromised, the contract's rigid state machine rejects invalid transitions.

The settlement state machine relies on off-chain triggers to advance on-chain logic.

Packing the 114-Byte Box

Algorand's global state is highly constrained. To handle an arbitrary number of betting rounds without hitting storage limits, the project utilizes Box Storage. The developer used a BoxMap and packed 14 uint64 values and 2 uint8 values into a highly efficient 114-byte binary-compatible ARC4 Struct.

This struct holds everything necessary for a single round: prices, timestamps, pool sizes, and status flags. By keeping the data footprint exactly 114 bytes, the contract minimizes storage costs while maintaining rapid read and write access during high-frequency betting windows.

Integer-First Physics and Invariants

Financial safety in decentralized systems requires strict accounting. The contract tracks total_reserved_user_funds entirely separately from protocol fee accruals. This invariant ensures that even if the protocol generates massive fee revenue, it can never accidentally spend user-committed capital.

Two heavily armored glass vaults sitting side-by-side, one labeled USER and the other FEES. A mechanical chute sorts coins into each with a thick firewall separating them. — Strict accounting invariants physically separate user funds from protocol fees.

To prevent floating-point dust leaks, the contract enforces a multiply-before-divide strategy with eight decimal places of precision. Any integer remainders are systematically captured and routed to the protocol treasury rather than lost to rounding errors.

Web3 DevOps in Python

The repository abandons manual frontend configuration. The deploy_new.py script compiles the TEAL bytecode, deploys the application to the Algorand network, and then uses regex to patch the new App ID directly into the frontend TypeScript configuration and local environment files.

Deployment Step	Traditional dApp	algo-prediction-core
Contract Compilation	Manual CLI commands	Automated Python script
App ID Synchronization	Copy-paste to frontend	Regex-patching via script
Environment State	Often out of sync	Unified and deterministic