Community realm. Read the code first. Community realm, deployed by its author. Read the code before you interact or send coins.
Package payroll is employer-funded recurring salary disbursement with real ugnot custody.
Package payroll is employer-funded recurring salary disbursement with real ugnot custody.
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.
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.
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.
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:
1OPENING 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.
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:
1Liabilities() == TotalPooled() + AccruedTotal() + FeesAccrued()
2Held() == 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.
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.
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.
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.
Denom is the only asset this realm holds.
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.
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%.
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.
MinFunding keeps dust pools out: 1 GNOT per Fund call.
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.
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.
OpenEnded is the EndHeight value meaning "no end": the position accrues until it is terminated.
RealmPath is this realm's own path, used to build Render links.
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 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 is the sum of every employee's unclaimed balance.
BalanceOf is an employee's accrued, unclaimed balance.
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 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 is duePeriods for a live position, at the current height.
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 is a position's end height, or OpenEnded.
FeesAccrued is the fee pot awaiting WithdrawFees.
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 reports whether a position is open, without panicking on absence — every other position accessor panics, which makes them unusable as an existence probe.
Height is the current chain height, exposed so a caller can compute period boundaries against the same clock this realm uses.
Held is the realm's actual ugnot balance, read from the chain.
1func Hire(cur realm, employee address, perPeriod, periodBlocks, startHeight, endHeight int64)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.
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 is every coin this realm owes to anyone: pooled coins plus the ledger's own total (employee balances plus the fee pot).
OpenPositions is the number of open positions across every employer.
PaidPeriodsOf is how many whole periods a position has settled.
PerPeriodOf is a position's gross salary per period.
PoolOf is an employer's unallocated pool. Zero for an address that has never funded one.
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.
RosterOf is the number of open positions an employer holds.
Surplus is coins held beyond every obligation — what SweepSurplus would move. It is zero when every coin arrived through an entrypoint.
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 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 is the sum of every employer's unallocated pool.
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 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 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.
