The Sandbox.sol contractComing soon

Sandbox.sol is the on-chain half of Sandbox, on Robinhood Chain (chain id 4663). It combines two things: a registry of published games (hash, URI, title, creator) and a vault of ETH, fed by the creator fees of the $SANDBOX token, redistributed every epoch — that is, every 24 hours — to the builders whose games were played the most.

Overview#

Types#

Game#

Epoch#

Constants#

Game registry#

function publish(bytes32 contentHash, string calldata uri, string calldata title)
    external payable returns (uint256 gameId);

function update(uint256 gameId, bytes32 contentHash, string calldata uri, string calldata title) external;

function setHidden(uint256 gameId, bool hidden) external;

function transferGame(uint256 gameId, address to) external;

function tip(uint256 gameId) external payable;

function gameCount() external view returns (uint256);
function getGame(uint256 gameId) external view returns (Game memory);
function gamesOf(address creator) external view returns (uint256[] memory);

Site side, see Publishing a game.

Epochs and rewards#

function currentEpoch() public view returns (uint256);
function unallocated() public view returns (uint256);

function settle(uint256 epoch, uint256[] calldata gameIds, uint256[] calldata weights, uint256 amount) external;

function claim(uint256 epoch, uint256 gameId) external;
function claimMany(uint256 epoch, uint256[] calldata gameIds) external;
function pending(uint256 epoch, uint256 gameId) external view returns (uint256);

function sweepUnclaimed(uint256 epoch) external;

// public state
mapping(uint256 => Epoch) public epochs;
mapping(uint256 => mapping(uint256 => uint256)) public weightOf;
mapping(uint256 => mapping(uint256 => bool)) public claimed;
uint256 public reserved;

settle#

Operator only, once per 24-hour window. Writes the weights of a finished epoch (epoch < currentEpoch()), once, with 1 to 200 existing games, no duplicates, non-zero weights, and amount ≤ unallocated() (the vault’s balance minus ETH already reserved). The amount is added to reserved.

claim / claimMany / pending#

Callable by anyone. The share amount × weight / totalWeight is paid to the game’s current creator, once per game per epoch. claimMany skips games already claimed or with no weight. pending returns the share still owed, 0 otherwise.

sweepUnclaimed#

Owner only, 90 days after settlement: sends the epoch’s unclaimed remainder to the treasury and closes its claims (sweptAt).

Weight formula and schedule: Epoch rewards.

Pons fee harvest#

function setPonsToken(address token) external;
function harvest() external;
receive() external payable;

• setPonsToken(token): owner, once. The token must exist on the Pons factory and have this contract as creatorFeeRecipient, otherwise NotAPonsToken or WrongFeeRecipient.
• harvest(): open to all, never blocked by the pause. While on the bonding curve it calls sweepFees on the curve; once the token is in its Uniswap V4 pool, sweepPoolFees on the hook. Each call is wrapped in try/catch, then the fee escrow is claimed if it holds anything. Emits Harvested(amount).
• receive(): accepts ETH from anyone (pushed fees, donations) and emits Funded.

Administration#

function setOperator(address operator_) external;
function setTreasury(address treasury_) external;
function setPublishFee(uint256 fee) external;
function pause() external;
function unpause() external;
function transferOwnership(address to) external;
function acceptOwnership() external;

All owner only, except acceptOwnership which must be called by the pendingOwner. Zero addresses are refused for the operator and treasury; setPublishFee refuses more than 0.01 ETH.

Events#

Errors#

Security#

• No owner withdrawal. ETH only leaves through claim / claimMany, tip and sweepUnclaimed (to the treasury, after 90 days).
• Reserved accounting. reserved tracks ETH promised to settled epochs; settle can only commit unallocated(), that is, the free part of the vault.
• Two-step ownership (transferOwnership then acceptOwnership).
• Reentrancy guard on tip, claim, claimMany, sweepUnclaimed and harvest.
• Scoped pause. Pausing blocks publish, update, tip, settle, claim and claimMany; never receive or harvest.
• Safe sweep. After sweepUnclaimed, sweptAt closes the epoch’s claims, so the same share is never paid twice.

Tests#

Foundry, solc 0.8.26, EVM cancun, via_ir. 46 unit tests with Pons mocks (publishing, updates, hiding, transfer, tips, fee cap, settlement, exact shares and rounding, reentrancy, sweep, pause, ownership, every harvest branch) and 2 tests on a Robinhood Chain fork that launch a real token on Pons V2 with this contract as fee recipient, trade on the curve, harvest, settle and claim.

cd contracts
forge test -vv
forge test --match-path test/SandboxFork.t.sol -vv
forge test --gas-report

Gas costs#

See also#