payroll

gnokey query vm/qeval \
  --data 'gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/payroll.AccruedTotal()' \
  --remote https://rpc.onyx.testnets.gno.land:443

import "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/payroll"

if !payroll.HasPosition(employer, who) {

rosterAt: payroll.RosterOf(employer),

openAt:   payroll.OpenPositions(),

curl -sS 'https://onyx.testnets.gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/payroll$download&file=payroll.gno' | shasum -a 256

Overview

Package payroll is employer-funded recurring salary disbursement with real ugnot custody.

The one idea

An allowance refills; a salary ACCRUES. That single sentence is why this realm exists beside budgets rather than inside it.

budgets (this portfolio, live on onyx-1) grants a delegate a rate-limited spending authority through p/spendbook: the delegate may draw at most PerPeriod per window, and a window that passes unused is gone. Use-it-or-lose-it is exactly right for a spending authority — an unspent budget is not a debt.

A salary is the dual. An employee who does not collect for three periods is owed three periods. Unclaimed pay is a LIABILITY of the employer, not an expired permission. No refilling primitive can model that, because the whole point of a refill is that the previous window is forgotten.

So the arithmetic here is accrual arithmetic, and it is the one genuinely new mechanism in this realm. Everything that touches coins is delegated to primitives this portfolio has already audited and run live: p/coinio for custody and payout guards, p/feeledger for per-employee balances and the liabilities total.

Paid in arrears

A period must COMPLETE before it is owed. At the instant a position starts, nothing is due; the first period becomes payable at StartHeight + PeriodBlocks. Paying in advance would mean the realm disbursing for time that has not elapsed, and there is no mechanism on chain to take it back if the position ends early.

A consequence worth stating plainly: a position whose PeriodBlocks never fully elapses before it is terminated pays NOTHING. That is not a rounding loss hidden in the implementation, it is the arrears rule applied honestly, and Terminate's documentation repeats it.

Accrual is permissionless, and whole-period

Gno has no autonomous execution, so "recurring" always means someone sends a transaction later. Accrue may therefore be called by ANYONE — the employee, the employer, a keeper realm, a stranger. It does only what the employer already committed to when the position was opened, it moves coins from that employer's own pool to that employee's own ledger balance, and the caller pays the gas. There is no third party who gains, so there is nothing to grief with. This is also what makes the realm composable with upkeep, the portfolio's keeper-incentive realm.

Accrual settles WHOLE periods only. If the pool covers two of three due periods, two are credited and the third stays due — it is not partially paid, and no capacity is burned. The pool bounds HOW MANY periods clear, never WHETHER a period is paid in full.

Solvency, and the lesson taken from budgets

budgets' package documentation records that a budget is authority and not a reservation: over-authorization is legal there, and solvency is enforced per-owner at draw time. The same choice is made here for the same reason, and the honest consequence is named rather than hidden:

OPENING A POSITION DOES NOT RESERVE ANY COINS.

An employer may hire more people than the pool can ever pay. Nothing in this realm prevents it, because a future funding transaction is a perfectly ordinary way to intend to meet an obligation, and refusing the hire would only move the problem to the moment the pool dips. What the realm guarantees is narrower and checkable: a period either clears in full or stays due, and no employee's accrued ledger balance can be reduced by anyone.

The monetary invariant

Two statements, because one of them is a decomposition and the other is a solvency claim, and collapsing them is how the wrong identity gets written down:

Liabilities() == TotalPooled() + AccruedTotal() + FeesAccrued() Held() == Liabilities() + Surplus()

Liabilities() is every coin owed to anyone: the employers' unallocated pools PLUS the feeledger's own total, which is itself the accrued employee balances plus the fee pot. Surplus() is coins pushed at the realm outside every entrypoint. Both lines hold after every operation and are pinned by TestMonetaryInvariant. It is the same shape budgets carries, deliberately: a reader who has checked one can check the other.

Only the first line can fail. The second is definitional — Surplus() is computed as Held()-Liabilities() — so asserting it is a tautology, and what the test actually checks is Held() >= Liabilities() beside the decomposition. A reader who takes the second line for a check has been reassured by arithmetic.

This paragraph read `Held() == TotalPooled() + Liabilities() + Surplus()` until the pre-deploy audit, which double-counts the pools because Liabilities() already contains TotalPooled(). The code was never wrong and payroll_test.gno encoded the right decomposition the whole time; the comment was, and a comment is immutable after addpkg.

Termination is two steps, and that is a protection

Terminate stops the clock. Release frees the storage. They are separate because collapsing them would destroy earned-but-unaccrued pay: an employer whose pool is short could remove a position owing three periods and the debt would vanish with the record.

So Terminate sets the end height to now and leaves the position in place, with whatever is due still due and still accruable by anyone. Release removes it, and only once nothing is due. Release is permissionless and the chain refunds the freed storage deposit to the caller, which is the standing incentive to tidy up someone else's settled position — the same mechanism budgets uses for Reap.

What this realm does NOT do

• It does not value work, verify it happened, or arbitrate a dispute about it. A position is a standing instruction from an employer, and nothing more.
• It holds ugnot and only ugnot.
• It has no admin. The deploying namespace receives protocol fees and swept surplus and has no other privilege: no setter, no pause, no ability to touch a pool or a balance. Funding a pool is what makes an address an employer, exactly as in budgets.

STORAGE

An employer record is paid for by that employer's first Fund; a position record by the Hire that opens it. Release removes a position record and the chain refunds the freed deposit to the transaction that frees it.

Imports

• chain
• chain/runtime
• chain/runtime/unsafe
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/coinio
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/feeledger
• gno.land/p/nt/avl/v0
• gno.land/p/nt/markdown/sanitize/v0
• strconv
• strings

Constants and variables

AccrueFeeBps is the fee charged on each accrual, on the gross amount, floor-rounded in the EMPLOYEE's favour: 100 bps = 1%. It matches the most conservative live fee in this portfolio (fee_split, crowdfund, budgets). It is a compile-time constant and there is no setter, so a position's economics cannot be changed under the employee after the position is opened.

const AccrueFeeBps = int64(100)

Denom is the only asset this realm holds.

const Denom = "ugnot"

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.

NOTE FOR ANY RE-NAMESPACED PORT: this is the address-as-data hazard that a namespace substitution rewrites silently while every byte-comparison still reports the tree faithful, because the rewrite IS the intended transformation. Re-state it deliberately per chain; never let it be derived.

const FeeCollector = address("g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3")

MaxFeeBps is the hard ceiling on any accrual 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%.

const MaxFeeBps = int64(500)

MaxRoster caps simultaneously-open positions per employer. Hire is permissionless to anyone with a funded pool, so this is an AVAILABILITY BOUND and it is documented rather than hidden: an employer can exhaust their OWN roster and no one else's, because the roster is per-employer. The cost of filling one is gas plus the storage deposit on every position record, held until Release.

const MaxRoster = 64

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

const MinFunding = int64(1_000_000)

MinPerPeriod is the smallest salary a position may carry. Below the fee denominator a 1% fee floors to zero, so a per-period amount of a few ugnot would be a fee-free position by accident rather than by design; 1000 ugnot keeps the fee arithmetic meaningful.

const MinPerPeriod = int64(1_000)

MinPeriodBlocks is the shortest period a position may use. A period of a handful of blocks is a rate rather than a salary, and it makes the arrears rule meaningless. Unlike budgets, a period of 0 is NOT accepted here: there is no "one lifetime window" reading of a salary, and dividing by it would panic.

const MinPeriodBlocks = int64(100)

OpenEnded is the EndHeight value meaning "no end": the position accrues until it is terminated.

const OpenEnded = int64(0)

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

const RealmPath = "/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/payroll"

Functions

AccruableAmount

func AccruableAmount(employer, employee address) int64

AccruableAmount is the gross an Accrue would settle right now, pool bound included. It is the honest number, and it can be less than DueAmount without anything being wrong — see the package doc on solvency.

Accrue

func Accrue(cur realm, employer, employee address) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as Accrue(cross(cur), ...).

Accrue settles every whole period that has completed and not yet been paid, as far as the employer's pool reaches, and credits the gross minus the accrual fee to the employee's ledger balance.

ANYONE may call this — see the package doc. It returns the gross amount settled.

AccruedTotal

func AccruedTotal() int64

AccruedTotal is the sum of every employee's unclaimed balance.

BalanceOf

func BalanceOf(employee address) int64

BalanceOf is an employee's accrued, unclaimed balance.

Claim

func Claim(cur realm) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as Claim(cross(cur), ...).

Claim pays the caller their whole accrued balance. The employee only — there is no "claim on behalf of", because that would let a third party choose the moment someone else's coins move.

DueAmount

func DueAmount(employer, employee address) int64

DueAmount is the gross that DuePeriods would settle if the pool were unbounded. Read it beside AccruableAmount: the difference between them is exactly the employer's shortfall.

It is the one arithmetic here with NO pool bound behind it, so it is the one place an int64 can wrap: perPeriod has no ceiling and due grows with the chain. Accrue cannot wrap, because its product is bounded by the pool it is about to debit (see the comment there). An unpayable position is a legal state in this realm, so the overflow is reachable in principle, and this panics rather than returning a negative salary — a view that refuses is recoverable, a view that lies is not.

DuePeriods

func DuePeriods(employer, employee address) int64

DuePeriods is duePeriods for a live position, at the current height.

Employers

func Employers() int

Employers is the number of addresses that have ever funded a pool. Note the tense: an employer record survives a pool going to zero, so this is not a count of currently-funded employers.

EndHeightOf

func EndHeightOf(employer, employee address) int64

EndHeightOf is a position's end height, or OpenEnded.

FeesAccrued

func FeesAccrued() int64

FeesAccrued is the fee pot awaiting WithdrawFees.

Fund

func Fund(cur realm) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as Fund(cross(cur), ...).

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 employer.

HasPosition

func HasPosition(employer, employee address) bool

HasPosition reports whether a position is open, without panicking on absence — every other position accessor panics, which makes them unusable as an existence probe.

Height

func Height() int64

Height is the current chain height, exposed so a caller can compute period boundaries against the same clock this realm uses.

Held

func Held() int64

Held is the realm's actual ugnot balance, read from the chain.

Hire

func Hire(cur realm, employee address, perPeriod, periodBlocks, startHeight, endHeight int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Hire(cross(cur), ...).

Hire opens a position. The caller is the employer and must already have a funded pool, which is this realm's only barrier to opening records at someone else's expense.

startHeight must not be in the past. A backdated start would make a large number of periods due in the same transaction that opened the position, draining the pool to one employee in one call — the hire would look like a schedule and behave like a withdrawal. Refusing it is cheaper to reason about than bounding it.

perPeriod is bounded below and NOT above, and the slot cost is permanent

MinPerPeriod is a floor; there is no ceiling. A position opened with a perPeriod larger than any pool that can be funded is unsettleable, because Accrue's solvency check is integer division — e.pool/perPeriod is 0 for every reachable pool, so Accrue panics on "cannot cover one period" forever. Once that position's first period completes, duePeriods is permanently non-zero, so Release refuses forever too, and the record consumes one of the employer's MaxRoster slots for good.

This is a DECLARED LIMITATION rather than a defect, and the reason is that it is strictly self-harm: owner comes from cur.Previous().Address() below and is never a parameter, so no caller can open an unpayable position on anyone else's roster, and the pool itself stays fully withdrawable through WithdrawPool. The mitigation is available and narrow: Terminate then Release BEFORE the first period completes, while duePeriods is still zero. After that the slot does not come back.

Liabilities

func Liabilities() int64

Liabilities is every coin this realm owes to anyone: pooled coins plus the ledger's own total (employee balances plus the fee pot).

OpenPositions

func OpenPositions() int

OpenPositions is the number of open positions across every employer.

PaidPeriodsOf

func PaidPeriodsOf(employer, employee address) int64

PaidPeriodsOf is how many whole periods a position has settled.

PerPeriodOf

func PerPeriodOf(employer, employee address) int64

PerPeriodOf is a position's gross salary per period.

PoolOf

func PoolOf(employer address) int64

PoolOf is an employer's unallocated pool. Zero for an address that has never funded one.

Release

func Release(cur realm, employer, employee address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Release(cross(cur), ...).

Release removes an ended, fully-settled position and frees its storage. Permissionless: the chain refunds the freed storage deposit to the caller, which is the standing incentive to tidy up a settled position that is not your own.

It refuses while anything is due, which is what makes it safe to let a stranger call: a Release cannot destroy an unpaid obligation.

Render

func Render(path string) string

RosterOf

func RosterOf(employer address) int

RosterOf is the number of open positions an employer holds.

Surplus

func Surplus() int64

Surplus is coins held beyond every obligation — what SweepSurplus would move. It is zero when every coin arrived through an entrypoint.

SweepSurplus

func SweepSurplus(cur realm) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as SweepSurplus(cross(cur), ...).

SweepSurplus sends coins held beyond every obligation to FeeCollector. The reserve passed to coinio is the realm's full liability — pooled coins plus ledger liabilities — so a sweep can never reach a coin that an employer or an employee is owed.

Terminate

func Terminate(cur realm, employee address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Terminate(cross(cur), ...).

Terminate stops the clock on a position. The employer only.

It does NOT remove the record and does not settle anything: whatever was due stays due, and anyone may still Accrue it. That separation is the employee's protection — see the package doc. Use Release to remove a settled position.

If the position has not yet reached its first complete period, this pays nothing, by the arrears rule.

TotalPooled

func TotalPooled() int64

TotalPooled is the sum of every employer's unallocated pool.

WithdrawFees

func WithdrawFees(cur realm) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as WithdrawFees(cross(cur), ...).

WithdrawFees moves the accrued fee pot to FeeCollector. Anyone may call it; the destination is a compile-time constant, so the caller cannot influence where the coins go.

WithdrawPool

func WithdrawPool(cur realm, amount int64) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as WithdrawPool(cross(cur), ...).

WithdrawPool returns unallocated pool coins to the employer. There is no lock and no notice period, and that is a DOCUMENTED asymmetry rather than an oversight: see the package doc on solvency. An employer may withdraw a pool while positions are open, which leaves those positions accruing against an empty pool — due but unsettleable until the pool is refunded. What an employer can never do is reduce a balance already accrued to an employee's ledger account.

WithdrawPoolAll

func WithdrawPoolAll(cur realm) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as WithdrawPoolAll(cross(cur), ...).

WithdrawPoolAll is WithdrawPool for the whole pool. It panics on an empty pool rather than succeeding with a zero transfer, so a caller cannot read success as evidence that coins moved.

---

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.