payroll 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 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%.

AccrueFeeBps

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.

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

MinFunding

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

MinPerPeriod

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

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.

MaxRoster

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.

OpenEnded

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

position

self

employers

// address string -> \*employer

positions

// "employer|employee" -> \*position

ledger

employer

init.16

rejectStraySend

rejectStraySend aborts when a direct EOA MsgCall attaches coins to a non-payable entrypoint. This realm holds funds, so such a send would become sweepable surplus, silently converting a user's coins into operator funds. THE PREDICATE IS NARROWER THAN THE FIRST SENTENCE OF THIS COMMENT USED TO BE, and the narrowing is correct rather than a gap. OriginSend() reports the coins attached to the ORIGINATING TRANSACTION, not coins this realm received in this call — there is no per-call msg.value in Gno. MsgCall is the one caller shape where the two coincide: the envelope is delivered to the realm being called. Under MsgRun the envelope lands in the caller's own ephemeral /e/ realm, and under a realm caller it lands at the first realm in the chain; in both, coins that genuinely reach payroll do so through an explicit SendCoins that OriginSend() does not describe. So widening this guard to IsUser(), or dropping the conjunct entirely, would refuse calls that sent payroll nothing while still not seeing the sends it was widened to catch. The stdlib guidance is explicit that OriginSend pairs with IsUserCall. What remains uncovered is therefore not a hole in this guard: coins can always arrive at an address by a bare MsgSend with no call at all, which no entrypoint check can intercept. That is exactly what Surplus() and SweepSurplus exist to name and reclaim.

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

WithdrawPool

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

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.

Hire

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 {#hdr-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.

Accrue

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.

Terminate

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.

Release

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.

Claim

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.

WithdrawFees

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.

SweepSurplus

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.

duePeriods

duePeriods is the number of whole periods that have completed and not been paid. It is a pure function of the position and the clock, which is what makes it unit-testable without a chain. Periods are ANCHORED to startHeight: period k closes at startHeight + k\*periodBlocks. Nothing is due at startHeight itself — salary is paid in arrears.

DuePeriods

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

DueAmount

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.

AccruableAmount

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.

PoolOf

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

RosterOf

RosterOf is the number of open positions an employer holds.

BalanceOf

BalanceOf is an employee's accrued, unclaimed balance.

PerPeriodOf

PerPeriodOf is a position's gross salary per period.

PaidPeriodsOf

PaidPeriodsOf is how many whole periods a position has settled.

EndHeightOf

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

HasPosition

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

OpenPositions

OpenPositions is the number of open positions across every employer.

Employers

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.

TotalPooled

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

AccruedTotal

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

FeesAccrued

FeesAccrued is the fee pot awaiting WithdrawFees.

Liabilities

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

Held

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

Surplus

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

Address

Height

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

posKey

getEmployer

mustEmployer

mustPosition

checkedAdd

checkedMul

checkedMul reports a\*b and whether it is exact. Both operands here are non-negative (duePeriods never returns a negative, perPeriod is validated at or above MinPerPeriod), so the division test is sufficient and the sign cases a general version would need are deliberately absent.

itoa

Render