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 ≥ 0
  • metered(box) ≤ hours(box) ≤ 24
  • Σ live = totalLive ≤ maxLive at every open
  • a refund is paid once per box
  • burnedRoot only grows

Parameters, read live

RootboxMeter: live
reading the Meter