reimbursements state

RealmPath

RealmPath is this realm's own path, used to build Render links.

Denom

Denom is the only asset this realm holds.

MaxFeeBps

MaxFeeBps is the hard ceiling on any approval fee this realm could ever charge, enforced by the feeledger the realm is constructed with — a feeBps above it is refused by the primitive's own validation, not by a check in this file. 500 bps = 5%.

ApprovalFeeBps

ApprovalFeeBps is the fee actually snapshotted into every desk: 100 bps = 1%, charged once per approval on the gross amount, floor-rounded in the claimant's favor. The most conservative live fee in this portfolio (fee\_split, crowdfund, budgets) is also 1%.

FeeCollector

FeeCollector receives withdrawn fees and swept surplus. Compile-time constant: there is no setter and no transfer path. It is the deploying namespace's address — stated plainly: the operator of this realm.

MinFunding

MinFunding keeps dust pools out: 1 GNOT per Fund call.

MinPerPeriod

MinPerPeriod is the smallest per-window approval cap a desk may carry. It exists so a desk cannot be opened that no approval could ever satisfy, and it is paired with MinRequestAmount below rather than standing alone.

MinPeriodBlocks

MinPeriodBlocks is the shortest window a desk may use. A window of a handful of blocks is a rate, not a budget, and it makes PerPeriod meaningless as a bound on worst-case loss. A periodLength of 0 is still accepted and means ONE LIFETIME WINDOW that never refills (spendbook's own semantics).

MinRequestAmount

MinRequestAmount is the smallest request that may be filed, and it is deliberately EQUAL TO MinPerPeriod rather than smaller. The two together are what make a desk's authority expressible: a desk whose per-window cap is at the floor can still approve a request at the floor. Setting this below MinPerPeriod would admit dust requests that cost the approver a transaction each; setting it above would create desks no request could use.

RequestTTL

RequestTTL is how long a request stays approvable, IN BLOCKS. No wall-clock equivalent is stated because onyx-1's block time has never been measured by this project, and converting blocks to hours with an assumed rate is how a document comes to carry a number nobody checked. It is sized to be long enough that an approver need not be online continuously and short enough that the request tree drains.

MaxLiveDesks

MaxLiveDesks caps simultaneously live desks, via spendbook's own construction bound. OpenDesk requires a funded pool, which is NOT a capital bound — see MaxOpenPerClaimant for why that mistake is not repeated here. spendbook's own MaxLiveLimit is 10000.

MaxDesksPerOwner

MaxDesksPerOwner bounds how much of the global desk cap one owner can occupy. spendbook's package documentation names this as the gap a consuming realm must close: "maxLive is a single global figure, so any owner permitted to Open can exhaust it and lock out the rest … a Book shared across mutually untrusting owners needs its own per-owner cap on top of this one." This is that cap.

MaxLiveRequests

MaxLiveRequests caps simultaneously live requests across the realm. Submit is permissionless, so this cap is exhaustible, and the package doc states that bound rather than claiming the per-identity caps below close it.

MaxOpenPerClaimant

MaxOpenPerClaimant bounds one claimant's simultaneously-pending requests. It is a GRIEF-COST multiplier and not a defence: one address is bounded, N addresses are not, and an attacker controls N. The real mitigation is RequestTTL plus permissionless ExpireRequest — see the package doc's availability section.

MaxOpenPerDesk

MaxOpenPerDesk bounds the pending requests at one desk, so a single desk's approver is not handed an unreviewable queue by one burst. It is per-desk, so filling it denies that desk only; other desks are unaffected.

MaxLabelLen

MaxLabelLen bounds a desk's free-text label.

MaxMemoLen

MaxMemoLen bounds a request's free-text memo and a rejection's reason. Larger than MaxLabelLen because a memo is the expense description — the thing an approver reads to decide — while a label only names a desk.

MaxRenderRows

MaxRenderRows bounds the lists on the index page.

desk

request

self

desks

// padID(id) -> \*desk

nextDeskID

requests

// padID(id) -> \*request

nextReqID

pools

desksByOwner

openByClaimant

openByDesk

totalPooled

lifetimeFunded

lifetimeSubmitted

lifetimeApprovals

lifetimeApproved

// gross, before the fee

lifetimeRejected

lifetimeRetracted

lifetimeExpired

lifetimeClaimed

// net, paid to claimants

lifetimeReturned

// unspent pool withdrawn by owners

ledger

book

init.41

rejectStraySend

rejectStraySend aborts when coins are attached to a non-payable call. This realm holds funds, so a stray send would become sweepable surplus, silently converting a user's coins into operator funds. Aborting reverts the transfer instead. Guarded on IsUserCall, not IsUser, because a MsgRun ephemeral can consume the OriginSend envelope before forwarding control; for a realm-routed call the envelope lands at the intermediary, so there is nothing here to reject and the guard deliberately fails open (budgets, crowdfund and treasury\_board document the same scope).

Fund

Fund adds the attached coins to the caller's own pool. Direct EOA calls with -send only (the receipt-guaranteed shape); exactly one positive ugnot coin, at least MinFunding. Anyone may fund; funding is what makes an address an owner.

WithdrawPool

WithdrawPool returns part of the caller's UNSPENT pool and reports the pool REMAINING afterwards. Unlike budgets, this is not a hazard to a counterparty, and the reason is the divergence in the package doc: an approved reimbursement has already left the pool and sits in the ledger as the claimant's. What an owner can still do is empty the pool under a live desk, so that the approver's next Approve fails on solvency and pending requests cannot be settled. That is the owner declining to spend their own money, which is theirs to decline; CloseDesk is the clean way to end the relationship.

WithdrawPoolAll

WithdrawPoolAll returns the caller's entire unspent pool and reports the amount WITHDRAWN. The return values of the two withdraw entrypoints are deliberately asymmetric, which is worth naming rather than letting a caller discover: each returns the figure its caller does not already have. WithdrawPool was told the amount and wants to know what is left; WithdrawPoolAll knows what is left (nothing) and wants to know what it got. Returning the remainder here would hand every caller a constant 0.

payOutPool

payOutPool is the shared debit-then-send path: the pool and the P term are reduced before the identical amount leaves the realm (checks-effects-interactions).

OpenDesk

OpenDesk appoints an approver with a bounded authority over the caller's pool and returns the desk id. The caller becomes the desk's owner and must already have a funded pool — not because the desk reserves anything (it does not), but because a desk over an unfunded pool is an invitation to claimants to file requests nothing can settle, and this realm declines to record one. Terms, all in the chain's own units: perPeriod the gross the approver may approve per window, at least MinPerPeriod. Required. periodLength blocks per window. 0 means ONE LIFETIME WINDOW that never refills; otherwise at least MinPeriodBlocks. total lifetime cap across every window. 0 means unlimited. expiresAt absolute block height at which the approver's authority ends. 0 means no expiry. Every bound above except the two realm minimums is validated and enforced by spendbook, and an invalid combination surfaces as that package's own sentinel error.

AmendDesk

AmendDesk changes a desk's terms. Owner only. The returned bool reports whether the new terms are in force NOW (a tighter-or-equal amendment) or queued for the next window boundary (a looser one) — spendbook's one-sided rule, and the distinction worth knowing. periodLength is NOT a parameter. spendbook makes it immutable because moving it would move every future boundary, which is an enlargement vector wearing a different hat; this realm reads the desk's own periodLength and passes it unchanged, so changing it is not merely refused, it is unexpressible. Amending does not touch pending requests. Their fee was snapshotted at Submit and their amount is fixed; what changes is whether the approver still has the authority to settle them, which Approvable reports. A QUEUED EXPIRY EXTENSION CAN BE LOST, AND THE DESK BECOMES REAPABLE IN THE MEANTIME. A widening amendment is queued rather than applied, and spendbook surfaces a queued term only through its internal at() accessor — which IsExpired does NOT use: it reads the live Terms.ExpiresAt directly. So between queueing and the next approval, IsDeskExpired and ReapDesk still read the OLD expiry. If the old expiry passes with no Approve and no restated AmendDesk in between, ANYONE may ReapDesk the desk and the queued extension dies with it. Restating the same amendment while the old expiry is still in the future makes it permanent, because spendbook writes Pending back to Terms on a spend or on a later amendment; restating it after the old expiry is refused with "allowance has expired". NO FUNDS ARE AT RISK and that is structural, not incidental: dropDesk moves no coins, and the claimant pools are keyed by CLAIMANT ADDRESS rather than by desk, so a reap strands open requests and leaves every accrued balance claimable. The root cause is in spendbook, which is already live and immutable, so the repair belongs to a future /p/ version and not to this realm. See AUDIT.md Y1 and DEPLOY\_READINESS.md.

CloseDesk

CloseDesk ends an approver's authority immediately. Owner only. The id is never reused, so a closed desk cannot be resurrected. Closing does NOT claw back credit already approved — that is the claimant's and stays claimable. It does NOT remove requests filed at this desk either: see the package doc, "a closed desk leaves its requests un-approvable". The count of those is reported in the event so the owner learns what they just stranded.

ReapDesk

ReapDesk removes a desk whose authority has EXPIRED, freeing its slot and its storage. Anyone may call it, and the reasoning is spendbook's own: an expired allowance can never authorize another approval, so removing it takes nothing from the owner and grants nothing to the caller. The chain refunds the freed storage deposit to the reaping transaction, which is the standing incentive. A desk with no expiry can never be reaped; only its owner can close it.

Submit

Submit files a reimbursement request against a desk and returns the request id. ANYONE may submit: that is the point of the realm — the party who spent the money asks, and does not need to be a signer, a delegate, or known to the desk in advance. Nothing is reserved and nothing moves. The amount and the fee are fixed here (the fee is snapshotted from the desk, so a later AmendDesk cannot change the terms of a request already filed), and the request expires at submittedAt + RequestTTL. Submitting against a desk whose approver is the submitter is permitted and useless: Approve refuses self-approval, so such a request can only be rejected, retracted or expired. It is not refused here because an approver may legitimately submit at a desk they do not approve, and a check at Submit would have to guess which desk the claimant meant.

Approve

Approve settles a request. APPROVER ONLY: the approver is the calling address, never an argument. The claimant is credited net of the fee and claims separately, which is this portfolio's standard pull shape. The checks fail in this order, and the order matters: 1. the desk must still exist (a closed or reaped desk strands its requests, by design); 2. the caller must be that desk's approver; 3. the caller must not be the request's own claimant (no self-approval); 4. the request must not have expired; 5. the owner's pool must cover the GROSS amount; 6. the desk's spendbook authority must permit the gross amount. Solvency (5) is checked BEFORE the allowance is consumed (6), so an approval refused for insolvency leaves the desk's window untouched rather than burning capacity on an approval that did not happen. This is budgets' ordering, kept for the same reason.

Reject

Reject closes a request without settling it. APPROVER ONLY. Nothing moves in any term of the invariant, and no authority is consumed — a rejection costs the desk's window nothing, which is deliberate: an approver must be able to say no as often as necessary. Rejecting an EXPIRED request is allowed. The alternative would force an approver who wants the record to carry a reason to race the expiry, and the reason is the useful artifact: ExpireRequest emits no explanation.

Retract

Retract removes the caller's own pending request. CLAIMANT ONLY. Nothing moves. Named Retract rather than Withdraw on purpose: every Withdraw\* in this portfolio moves money, and this moves none. A claimant reading a function list should not have to open the source to learn which.

ExpireRequest

ExpireRequest removes a request past its expiry, freeing its slot and its storage. ANYONE may call it, and the reasoning matches ReapDesk's: an expired request can never be approved, so removing it takes nothing from the claimant and grants nothing to the caller. The chain refunds the freed storage deposit to the expiring transaction, which is the standing incentive and the mechanism that drains the queue.

Claim

Claim pays the caller's entire settled credit out. CLAIMANT ONLY: the account is the calling address. Credit from a desk that has since been closed, expired or reaped is still claimable — it was settled under a live authority and this realm does not revisit that.

WithdrawFees

WithdrawFees pays the entire accrued fee pot to the compile-time FeeCollector. Anyone may call it: the destination is fixed, so there is nothing for a caller to steer.

SweepSurplus

SweepSurplus sends out-of-band coins to the FeeCollector: for the pool denom, everything above tracked liabilities; for any foreign denom, the full balance. Owner pools, claimant credit and the fee pot are untouchable by construction (coinio.Sweep refuses to dip below the reserve). Anyone may call it. With nothing out of band this ABORTS ("coinio: no surplus to sweep for \<denom>") rather than returning 0. That is the primitive's choice and the right one: a sweep is a transfer, and a transfer of nothing that reports success is how a caller comes to believe a balance was moved.

DeskInfo

DeskUsage

DeskUsage returns a desk's consumption AT THE CURRENT HEIGHT: what the window the chain is in right now has approved, the lifetime gross, that window's index, how many approvals there have been, how many rejections, and how many requests are pending at the desk. The two window figures are computed rather than read straight off the record, and that is the whole point of windowAt below: a window that has rolled with no approval since leaves Allowance.WindowIndex naming a window the chain has already left, and Allowance.SpentWindow holding the previous window's spend.

DeskLabel

DeskLabel returns a desk's raw label (unsanitized: callers rendering it into markdown must sanitize, as this realm's Render does).

Remaining

Remaining is the AUTHORITY figure for a desk: what its terms permit the approver to approve right now, ignoring whether the owner's pool can cover it.

Approvable

Approvable is the HONEST figure for a desk, and the one both an approver and a prospective claimant should read: the lesser of what the desk authorizes and what the owner's pool holds. This distinction is the realm's own — spendbook bounds permission and says so, never solvency.

PendingTerms

PendingTerms returns a queued loosening amendment on a desk and whether there is one. An amendment is queued only when it would widen the live window, and it takes effect at the next window boundary.

IsDeskExpired

IsDeskExpired reports whether a desk's authority has lapsed, which is also the condition under which anyone may ReapDesk it. It reads the LIVE expiry only. A queued expiry extension reported by PendingTerms is NOT considered here, so this can read true while an amendment widening the window is still queued — see AmendDesk for the full disclosure and why no funds are at risk.

RequestInfo

RequestMemo

RequestMemo returns a request's raw memo (unsanitized: callers rendering it into markdown must sanitize, as this realm's Render does).

IsRequestExpired

IsRequestExpired reports whether a request is past its expiry, which is both the condition under which Approve refuses and the condition under which anyone may ExpireRequest it.

ApprovalBlocker

ApprovalBlocker returns the empty string when the request could be approved right now by its desk's approver, and otherwise the single reason it could not. It is the view a UI wants before showing an approve button, and an approver wants before paying gas for a call that will abort. The reasons are reported in the same order Approve checks them, so this view and that entrypoint can never disagree about WHICH reason applies. It deliberately does NOT report "you are not the approver": the caller of a view is not the caller of the approval, so this answers about the request and the desk, not about whoever is asking.

PoolOf

PoolOf returns an owner's unspent pool.

CreditOf

CreditOf returns a claimant's settled-but-unclaimed credit.

DesksOf

DesksOf returns how many live desks an owner currently holds.

OpenRequestsOf

OpenRequestsOf returns how many pending requests a claimant has.

OpenRequestsAt

OpenRequestsAt returns how many pending requests a desk has.

NumDesks

NumDesks returns how many desks have ever been opened. Ids are never reused, so this only grows.

LiveDesks

LiveDesks returns how many desks are currently live, from the primitive's own count.

NumRequests

NumRequests returns how many requests have ever been filed. Ids are never reused, so this only grows.

LiveRequests

LiveRequests returns how many requests are currently pending. A pending request may still be unapprovable — see ApprovalBlocker.

TotalPooled

TotalPooled returns the P term: unspent owner funds. Pending requests are NOT included; they are not liabilities.

UnclaimedCredit

UnclaimedCredit returns the claimants' share of the L term: approved and not yet claimed.

FeesAccrued

FeesAccrued returns the fee pot: charged, not yet withdrawn.

Liabilities

Liabilities returns P + L — everything this realm owes. A pending request is not part of it.

Held

Held returns H: the ugnot actually at this realm's address.

Surplus

Surplus returns H - (P + L) — out-of-band coins, sweepable.

Address

Height

Height returns the current chain height: the clock every window, expiry and TTL is measured against, and the one no caller can choose.

Render

Render shows the realm at "", a desk page at "desk/\<id>" and a request page at "request/\<id>". Labels and memos are free text and pass through the ecosystem sanitizer before hitting markdown.

renderIndex

renderDeskList

renderRequestList

renderDesk

renderRequest

mustDesk

mustRequest

mustAllowance

mustAllowance fetches the spendbook allowance behind a desk. The pair is created and removed together, so a missing allowance is a bug in this realm rather than a user error, and it panics rather than reporting a zero value that a reader would take for "no authority".

windowAt

windowAt returns the anchored window index containing now, and spentInWindow what that window has approved. These duplicate a line of spendbook, and the duplication is deliberate, bounded, and worth justifying because the primitive's own at() comment warns against exactly this. What is NOT reimplemented is the part that warning is about: which terms are in force after a boundary, and therefore every authority figure this realm reports — Remaining and Approvable both call through to the primitive, and nothing here second-guesses them. What is copied is pure index arithmetic over three EXPORTED fields plus the already-documented fact that the in-window spend RESETS rather than carries. The alternative is worse than the duplication: Allowance's WindowIndex and SpentWindow are the last-WRITTEN pair, so between a boundary and the next approval they describe a window the chain has left, and a Render publishing them would print "approved this window: 100000" immediately above "authorized by the terms: 100000". The two are pinned to the primitive by TestWindowRefillsAtAnchoredBoundary rather than by inspection: it approves after crossing a boundary and asserts approvedWindow equals that approval, which can only hold if windowAt agreed with spendbook's own index at the moment of the write.

spentInWindow

dropDesk

dropDesk removes a desk record and decrements its owner's live count. The allowance itself is removed by the spendbook call that precedes every caller of this helper. It deliberately does NOT remove the desk's pending requests — see the package doc, "a closed desk leaves its requests un-approvable". Its openByDesk counter IS removed, because the counter exists to bound new submissions at a live desk and a dead desk accepts none; the stranded requests remain findable by id and are still counted against their claimants' openByClaimant, which is what bounds them.

dropRequest

dropRequest removes a request record and decrements both of its counters. Every caller has already decided the request's outcome; this is only the bookkeeping.

labelOr

poolOf

setPool

ownerDesks

setOwnerDesks

decOwnerDesks

claimantOpen

setClaimantOpen

decClaimantOpen

deskOpen

setDeskOpen

itoa

boolstr

bps

bps renders a basis-point figure as a human percentage, exactly.

padID

padID encodes an id so avl's lexical order matches numeric order.

zeros

checkedAdd

checkedAdd returns a+b and reports whether the addition did not overflow int64.