docs/protocol.md
Protocol
The Meter
RootboxMeter is the escrow and the ledger, at 0xD7baCF58C6F9E38232ea06214d737621E47C615B on Robinhood Chain (4663). Solidity 0.8.28, OpenZeppelin 5.4, owner-controlled parameters with a 24 hour delay on increases.
State machine
box states
open() started() stop() close()
───────▶ [opened] ─────────▶ [running] ───────▶ [stopping] ───────▶ [closed]
│ │ ▲ meter() │ 15 min ▲
│ └──┘ once per hour └─ forceClose() ───┘
│ 15 min, never started: forceClose() refunds everything
└────────────────────────── kill(reason) from any live state ─▶ [killed]openedpaid, waiting for the keeper
runningstarted: hour 1 metered
stoppingowner called stop
closedsettled, refunded, disk saved
killedguardian kill: settled, refunded
Events
BoxOpened(boxId, owner, size, hours, pay, amount, resumeOf) BoxStarted(boxId, session) HourMetered(boxId, hourIndex, pay, amount) BoxExtended(boxId, addHours, amount) StopRequested(boxId) BoxClosed(boxId, hoursUsed) Refunded(boxId, owner, hours, amount) BoxKilled(boxId, reason, slashed)
Invariants
escrow(box) = paid − metered − refunded ≥ 0metered(box) ≤ hours(box) ≤ 24Σ live = totalLive ≤ maxLiveat every open- a refund is paid once per box
burnedRootonly grows
Parameters, read live
RootboxMeter: live
reading the Meter
rootboxshellboxesledgerdocs