coinio

curl -sS 'https://pearl.testnets.gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/coinio$download&file=coinio.gno' | shasum -a 256

Overview

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.

Imports

• chain
• chain/banker
• chain/runtime/unsafe

Functions

HeldAt

func HeldAt(addr address, denom string) int64

HeldAt returns the amount of denom held at addr. Read-only; usable from views and Render without a realm capability.

Payout

func Payout(_ int, rlm realm, to address, denom string, amount int64)

Payout sends amount of denom from the calling realm's own address to `to`. DEBIT YOUR ACCOUNTING FIRST — a panic here (or anywhere later in the transaction) reverts the debit together with the send.

Sweep

func Sweep(_ int, rlm realm, to address, denom string, reserve int64) int64

Sweep sends the surplus of a single denomination — everything the calling realm holds above `reserve` — to `to`, and returns the swept amount. Pass your total liabilities as the reserve for the denom your accounting tracks, and 0 for foreign denominations. Panics if there is no positive surplus, so reserved funds are untouchable by construction. One denomination per call keeps the operation gas- bounded regardless of how many junk denoms third parties force-send.

---

Doc text is reproduced as vm/qdoc returns it. The node markdown-escapes doc comments, so a bracket or angle bracket may carry a backslash the committed source does not have. The source itself is at source and in this repository.