Docs

How Socratus works on chain.

The round lifecycle, the draw, the money, the credits router and orbio’s API, for builders and the curious. For the plain language version, read How it works.

01

Overview

Two contracts on Robinhood Chain (chain id 4663, an Arbitrum Orbit chain), neither upgradeable:

  • SocratusMine: the ring. 30 tiles, timed rounds, a draw from L2 block hashes, the fee split, the Bonanza, $SOCRA emission, refining, staking and automation. Its design is already proven on mainnet: the same mine contract has settled real rounds since September.
  • SocratusRouter: buys orbio CREDIT with ETH in one transaction. No owner, no fee, no storage.

The site is static. It reads the chain through a read-only proxy (the public node sends no CORS headers) and your wallet signs every transaction itself, so nothing about a round depends on our servers.

Tiles
30one wins each round
Round
60 sowner tunable, 20 to 600
Minimum
0.0001ETH per tile
Bonanza
1 in 625per round with winners
02

A round, phase by phase

  • Open (phase 0): deployments are accepted until the end time. A round that ends empty restarts on the next deploy and keeps its number.
  • Closing (phase 1): the first crank() after the end records the L2 sample block and reserves the round’s $SOCRA emission. No new deployments, no new stakes.
  • Settled: once the sample block and the one after it exist, crank() draws the tile, splits the money and opens the next round.

crank() is permissionless and never reverts when there is nothing to do. It returns 0 nothing, 1 closed, 2 settled and opened the next round, 3 resampled. The Socratus keeper calls it every minute and the Mine page calls it when your countdown hits zero, but any wallet can do it and earn the tip.

Settlement is lazy per miner: a round settles in one transaction however many miners it had, and each miner’s share is credited by checkpoint(), which also runs on their next deploy, claim or refine.

Recovery. A sampled hash is readable for 255 blocks. If nobody cranks inside that window, the next crank resamples instead of settling on a hash it can no longer read. Any successful call inside the window writes the draw down first, so a lapse can never redraw a result that was already knowable.

03

How the winning tile is picked

On an Orbit chain, block.number is the parent chain’s block and blockhash is not the L2 hash, so the contract reads both from the ArbSys precompile at 0x64: arbBlockNumber() and arbBlockHash().

seed    = keccak256(hash(sampleBlock), hash(sampleBlock + 1),
                    roundEntropy, roundId, mine, chainId)
winTile = seed % 30 + 1
bonanza = keccak256(seed, "bonanza") % odds == 0

The sample block is recorded at the close, so nobody knows the hashes when they deploy, and the hashes are fixed before anyone can act on them. Deploy entropy mixes in every deployment of the round.

04

Fee, split and the Bonanza

The fee (10%, capped at 20%) is charged on the ETH that sat on the 29 losing tiles. The rest of the round, its whole ETH minus the fee, is the winners’ pool, shared in proportion to each winner’s ETH on the winning tile. A round nobody won sends all of its ETH to the fee.

ShareOf the feeGoes to
stakers50%$SOCRA stakers, in ETH. While nobody is staked, it goes to the treasury.
bonanza10%The Bonanza pot, paid in full to the winners of a round that rolls 1 in 625.
treasury40%Socratus Lab, less the settle tip of 0.00002 ETH (a quarter to whoever closed the round, the rest to whoever settled it).

Shares are floored, which can leave up to one wei per winner in the contract. The books count that dust; it is never paid to anyone.

05

$SOCRA: emission, refining, staking

The mine does not mint $SOCRA. The owner sets the coin once with setCoin() after launch and funds an emission pool with fundCoin(); each round with winners then emits at most emissionPerRound, shared like the ETH, fixed and reserved at the close.

Mined $SOCRA lands as unrefined. refine() pays the unrefined balance plus the refined balance, less refineFeeBps (10%) on the unrefined part. That fee is shared pro rata among everyone still holding unrefined $SOCRA. If under 0.001 is held across all miners, the fee returns to the emission pool.

stake(amount) takes $SOCRA (approve first; a position is 0 or at least 1). Stakers earn the stakers’ share of every fee in ETH, by stake size; claimYield() and unstake() work at any time, even while paused. Nobody can stake while a round is closing, so a stake cannot straddle a settlement in one transaction.

06

Automation

setAutomation(mask, amountPerTile, rounds, reload) with the budget as msg.value sets up auto mining. The keeper (or anyone) runs autoDeploy(miners) once per round and earns autoFee (0.00001 ETH) per run from the budget. An automation keeps the auto fee it was set up under as its ceiling. cancelAutomation() refunds the unused budget in the same transaction.

07

The credits router

buyCredits(minUsdgOut, minCreditOut, recipient, maxFills, deadline) payable
  returns (creditOut, usdgIn, usdgRefund)

buyAndActivate(minUsdgOut, minCreditOut, beneficiary, maxFills, deadline) payable
  returns (creditOut, activationId, usdgRefund)
  1. Swaps all of msg.value to USDG on the Uniswap V3 WETH/USDG 0.01% pool (SwapRouter02), at least minUsdgOut, or reverts.
  2. Approves orbio’s exchange for exactly that USDG and calls buy (CREDIT goes to recipient) or buyAndActivate (orbio credits beneficiary, a wallet padded to 32 bytes).
  3. Checks at least minCreditOut arrived, resets the approval to zero and refunds any USDG the book did not take to the caller.

Both floors must be above zero, the deadline is checked, and the router holds no ETH, WETH, USDG or CREDIT between calls. Robinhood Chain has no Uniswap quoter, so the site prices a buy from the pool and orbio’s own getQuote and getActivationQuote, then sends with a 1% swap floor and a 1.5% credit floor.

08

orbio’s API

orbio’s gateway is OpenAI-compatible at https://api.orbio.so/api/v1. A wallet key is a signature of one fixed message, so no account or checkout is needed:

const signature = await wallet.signMessage({
  message: "Orbio API key · chain 4663 · epoch 0",
});
const apiKey = "sk-orb-0-" + Buffer.from(signature.slice(2), "hex").toString("base64");

GET /key returns the available balance and lifetime usage; POST /chat/completions runs a model; GET /models lists the catalogue with list prices. The balance draws from CREDIT activated for that wallet.

orbio sends no CORS headers, so Socratus pages reach it through /api/orbio/models, /api/orbio/key and /api/orbio/chat: pass-throughs that forward your request with your own key and store nothing.

09

What the owner can and cannot do

  • Can tune parameters inside hard caps (fee at most 20%, round 20 to 600 seconds). A change made while a round holds deployments waits for the next round.
  • Can pause new deployments and new stakes. Claims, refining, unstaking and cancelling automation are never paused.
  • Can set $SOCRA once, fund the emission pool, withdraw the treasury’s share, and rescue tokens sent to the contract by mistake (never players’ reserved or staked $SOCRA).
  • Cannot upgrade the contracts, pick a tile, touch players’ ETH, winnings or automation budgets, or renounce ownership into a contract nobody controls.