coinio package

Package coinio is the chain-facing coin plumbing that every value-holding realm on gno.land repeats: verified payment receipt, disciplined payout, and reserve-protected surplus sweeping. It was extracted from two audited, pearl-1-validated realms (vault and bounties) whose implementations of these mechanics were line-identical.

The package is PURE and STATELESS: it holds no balances, no roles, and no configuration; all state stays in the consuming realm (and its accounting package, e.g. feeledger). It emits no events — consumers emit their own. Every function either succeeds or panics, aborting the transaction: these are payment guards, and no failure here has a meaningful recovery path.

CAPABILITY CONTRACT: pure packages cannot declare crossing functions (a first `realm` parameter), so every coin-moving function here uses the canonical secondary-parameter shape `(_ int, rlm realm, ...)` — the same pattern as chain treasury packages. Pass 0 and your crossing entrypoint's own live `cur` (forwarded through non-crossing calls keeps it current). Each function asserts rlm.IsCurrent() before acting, so a stale, stored, or Previous() realm value fails closed (the designation-forgery guard secondary realm parameters require). Coins can only move FROM rlm.Address() — the calling realm itself — so no consumer can spend another realm's funds through this package.

AUTHORIZATION is the consumer's responsibility: coinio decides HOW coins move, never WHO may move them. Gate your entrypoints before calling in.

ORDERING CONTRACT (the one invariant coinio cannot enforce): debit your own accounting BEFORE calling Payout or Sweep (checks-effects-interactions). A panic inside coinio aborts the whole transaction, reverting your debit with it — that is what makes the debit-first order safe.