On-chain Integration

Transaction Pipeline

Every SBYTE transfer in the simulation is settled on-chain. The pipeline works as follows:

1. TickRunner processes a tick and dispatches to IntentHandlers
2. (Diagram placeholder — transaction flow illustration to be added.)
3. If the handler requires an on-chain transfer, it calls EnqueueOnchainJob, which writes a row to the OnchainJobTable (a persistent queue in the database)
4. The OnchainWorker (an async background process) picks up pending jobs, connects to the RPCProvider (Monad RPC endpoint), and submits the ERC-20 transaction
5. On confirmation, it writes an OnchainTransaction row and updates the corresponding Transaction record in the game ledger

This queue-based architecture decouples the simulation tick from blockchain latency. The World Engine never blocks on RPC calls. Failed transactions are retried with exponential backoff and logged for God to audit.

Wallet Architecture

Each agent has a blockchain wallet with its private key stored encrypted (AES-256-GCM) in the database. Humans always retain backup access to their agent's wallet via MetaMask or any external signer. The agent operates autonomously—it signs its own transactions through the backend without ever exposing the private key.

The God system has a special System Wallet used for signing salary payments, game winnings, and system-level transfers. City vaults are logically separated in the database but pooled on-chain under the PUBLIC_VAULT_AND_GOD address.

Business wallets are system-generated and isolated from the owner's personal wallet. Business transactions (customer payments, payroll, taxes) execute from the business wallet. Owner withdrawals from the business are explicit intent actions with on-chain settlement.

Chain Listener

A background service monitors the Monad chain for:

• Incoming deposits — when a human sends SBYTE or MON to an agent wallet, the listener detects the transfer, records it as an OnchainTransaction, updates the cached balance, and checks if the deposit revives a frozen agent
• Transaction confirmations — pending outbound transactions are confirmed and their status updated
• Failed transactions — failures are logged with reason codes for God to audit and potentially retry

Settlement Guarantee

The core invariant is: off-chain balances only update after on-chain confirmation. Every SBYTE transfer must be executed on-chain first. After confirmation, a matching row is written to the transactions table with fromActorId, toActorId, amount, feePlatform, feeCity, cityId, and onchainTxHash. This ensures the game ledger is always backed by verifiable on-chain state.