payroll/docs/operations.md

# Running payroll

## The scheduler

One permanent task (`ext_payroll_scheduler`), started with the extension.
It waits ~20s after boot, then every 5 minutes asks each **active**
contract whether it owes a payday.

Minutes, not seconds, on purpose: a payday is a calendar event, so paying
a few minutes into the day costs nothing, and a tight loop would only
multiply log noise while a contract cannot be funded. The post-boot pass
means an instance that was down over a payday catches up on restart rather
than waiting a full interval.

Days are **UTC**. An instance whose operators think in a far-eastern or
far-western timezone will see paydays land on what is locally the previous
or next day.

## How one period is paid

```
create_invoice(employee_wallet, amount, currency, internal=True)
        │        ← this is also where a fiat contract is priced in sats
        ▼
   invoice.amount (msat)  ← canonical for this period, recorded as-is
        │
        ▼
pay_invoice(source_wallet, invoice.bolt11)
```

A plain internal LNbits wallet-to-wallet transfer. The invoice carries
`extra = {tag: "payroll", contract_id, period, payday}`, so a payroll
transfer is identifiable from the payments list on either wallet.

The sat amount is derived exactly once, by LNbits' own invoice pricing, and
everything downstream reuses that number. Re-deriving it from
`amount × rate` at any later point would drift — FX moves between quote and
settlement, and rounding accumulates over a year of paydays.

If a payout fails after the invoice exists, an unpaid internal invoice is
left on the employee's wallet. It was never settled and expires on its own;
that is the deliberate price of not pricing the period a second time just
to run a balance check.

## Pricing a back-dated period

A period whose payday is **today or ahead** is priced by LNbits itself —
`create_invoice(amount, currency)` does the conversion, and nothing here
touches the network. Every pricing mode agrees in that case.

A period whose payday is **in the past** is where the modes diverge:

| mode | converts at | use when |
|---|---|---|
| `payday` (default) | BTC's value on the payday | the expense belongs to that date |
| `current` | today's rate | the debt reads "we owe EUR 800, whenever it settles" |
| `manual` | a rate you state (`100000` EUR/BTC) | the figure was agreed, not looked up |

`manual` is an instruction, not a lookup, so it applies to **every** period —
a contract pegged to an agreed rate honours it whether the payday is last
month or next week.

`payday` and `current` only diverge for a payday already past. For one that
is today or ahead there is no history to consult, so `payday` collapses into
`current`: a future rate is not knowable, and the live one is the only
defensible answer. The pay-now dialog says so outright, naming the period's
date, rather than leaving a hint to be missed beside a control that appears
to do something.

Set per contract; overridable per payout via `pricing_mode` / `manual_rate`
on `pay-now`, which is how you enter one back-dated payment without editing
the contract.

Historical rates come from `rates.py` — Kraken's daily OHLC series first
(one request covers every date in a backfill), CoinGecko by date as the
fallback for currencies Kraken does not quote. **Not** from LNbits' own
exchange providers: those are spot tickers with no date parameter, and the
rate history behind the admin chart is RAM-only, single-currency and wiped
on restart.

How far back this actually reaches, measured against both live APIs:

| payday age | major pair (EUR, GBP, USD…) | currency Kraken doesn't quote |
|---|---|---|
| under 1 year | Kraken | CoinGecko |
| 1–2 years | Kraken | **unavailable** |
| over 2 years | **unavailable** | **unavailable** |

CoinGecko's free tier returns `401 Unauthorized` past 365 days — a plan
limit wearing an auth error's clothes. Unavailable means the period fails
and says so; it never guesses.

The two sources disagree by a couple of percent on the same date (for
2026-05-15: Kraken 68,047.50 EUR/BTC, CoinGecko 69,743.26 — one exchange's
close versus a cross-exchange average). That is why the ledger records
`rate_source` beside `rate` instead of presenting a bare figure as canonical.

Payroll does the conversion itself in **every** mode and hands
`create_invoice` a sat amount. Not because it has to for `current` mode, but
because knowing the rate *before* the invoice exists is what lets the memo
name it. It stays a single conversion — `fiat_amount_as_satoshis` is the
function `create_invoice` would have called — and payroll stamps the same
`fiat_currency` / `fiat_amount` / `fiat_rate` / `btc_rate` keys onto the
payment that `calculate_fiat_amounts` would have, so a payroll payment reads
like any other fiat-priced one.

Both wallets therefore show a memo naming the rate applied:

```
dev retainer — 2026-08-01 · 10 EUR @ 54,487 EUR/BTC
dev retainer — 2026-08-29 · 10 EUR @ 67,596.6 EUR/BTC
```

Which is the point: 18,353 sat and 14,794 sat are both "ten euro", and only
the rate says why they differ.

**A rate that cannot be established fails the period.** There is deliberately
no fallback to today's rate: one that moved 30% since the payday would pay
30% off and record nothing about it. The failure goes through the same
retry-then-pause path as an underfunded wallet, and names the date and
currency it could not price.

## What a failure does

A failed period does **not** advance `periods_done`, so the next tick
retries the same payday. Later periods do not jump the queue: the backlog
halts at the first failure so paydays settle in order.

The common failure is an underfunded source wallet, and the log line says
so explicitly with both figures:

```
payroll: contract a1b2c3d4 period 3 failed: insufficient balance in source
wallet: 12000 sat available, 80000 sat required
```

Retries are bounded. After `MAX_PERIOD_ATTEMPTS` (5) failures on the *same*
period, the contract is **paused** and the operator has to act. Pausing
rather than abandoning the period is the point: a payday that cannot be
funded is a fact somebody needs to see, and silently dropping it is the one
outcome payroll must never produce.

### Two kinds of pause, and why resume must tell them apart

| paused by | `paused_reason` | resume does |
|---|---|---|
| the operator | empty | **writes off** the missed paydays |
| payroll | names the period and cause | **keeps** them; they settle next tick |

These mean opposite things. An operator pause *is* the decision not to pay
those periods. An automatic pause means payroll could not pay them and
nobody decided anything — the money is still owed, and the operator has just
fixed whatever blocked it.

Sharing one path between the two destroys money silently: fix the cause,
click resume, and the backlog vanishes while the contract looks healthy.
`resume` therefore infers from `paused_reason`, and `catch_up` overrides it.
The console asks a different question for each and flags a payroll-paused
contract in the table with its reason.

## The payout ledger

Every attempt — paid, skipped *and* failed — is written to
`payroll.payouts`. `GET /payroll/api/v1/payouts` returns them newest first,
filterable by `contract_id` and `status`. "Why did nobody get paid on the
1st" is the question the ledger exists to answer, which is why failures are
in it rather than only in the log.

Rows are self-describing: each one copies the terms in force at the time
(amount, currency, both wallet ids) rather than pointing at the contract,
so a payout still reads correctly after its contract is edited or deleted.
There is deliberately no foreign key to `contracts` — deleting a contract
must not take its history with it.

The attempt counter is derived by counting a period's prior failures in the
ledger, not from a column on the contract, so it survives a restart and the
rows that produced the number are right there to audit.

## Back-dated start dates

Creating a contract with a start date in the past is normally an
*anchoring* choice — "we pay on the 1st" — not a request for back-pay.
Periods whose payday fell before the contract row existed are therefore
**skipped**, and skipping still consumes the period, so the schedule stays
aligned to the anchor.

Tick `backfill` on the contract to pay them instead.

Either way a single tick will not fire more than `MAX_CATCH_UP_PERIODS`
(12) periods for one contract, so a mistyped start date cannot turn into a
hundred transfers.

## Double-payment guard

Each contract has an in-process `asyncio.Lock`, and `run_due_periods`
re-reads the contract row under it. The scheduler is a single task, so the
lock exists for the off-cycle paths that can land mid-tick.

This is per-process. Two LNbits processes sharing one database would not
be serialised by it — payroll assumes the single-writer deployment LNbits
itself assumes.

## Previewing a schedule

`POST /payroll/api/v1/schedule/preview` draws a calendar from loose terms
(`start_date`, `frequency`, `total_periods`) — no employee or wallet
required, because the schedule is usually the thing worth sanity-checking
first, and a mistyped start date is cheapest to fix before anything is
saved. `GET /payroll/api/v1/contracts/{id}/schedule` does the same for a
live contract, from its current position.

Both return `ends_on`, the contract's last payday. "12 monthly payments
from 15 Jan" is much easier to check against "ends 15 Dec" than against a
list of twelve dates.

## Paying off-cycle

`POST /payroll/api/v1/contracts/{id}/pay-now` settles the contract's next
period immediately, whatever the calendar says, and consumes it.

One endpoint covers both "run it now" (don't wait for the tick) and "pay it
early", because they are the same operation — they differ only in whether
today happens to be the payday. It bypasses the back-dated skip: that guard
exists to stop a *new* contract firing surprise back-pay, and an operator
explicitly asking to pay a period is not a surprise.

It is recorded in the ledger like any other payout, with the early payment
noted in `detail`, and the ledger row is returned even when the payout
failed — a manual payout that did not land is exactly when you want to know
why.

## Accounting export

`GET /payroll/api/v1/payouts.csv` (super user) exports the ledger, with
optional `contract_id`, `status`, `since` and `until`. `since`/`until` bound
the **payday**, not the row timestamp, so an accounting period contains the
paydays that belong to it even when one took three days of retries to
settle.

Every exported field is neutralised against spreadsheet formula injection —
a cell beginning `=`, `+`, `-` or `@` is prefixed with an apostrophe.
`detail` carries exception text and the memo carries operator input, and
neither is worth trusting to a colleague's Excel.

## What an employee can see

`/payroll/api/v1/my/payouts`, `/my/payouts.csv` and `/my/contracts` are
gated on a **wallet invoice key**, not on admin rights: whoever holds the
read key for a wallet may see what payroll has paid into that wallet, and
nothing else. They live on a separate router from the super-user API so
they cannot inherit — or accidentally shed — the wrong gate.

Scoped to the wallet rather than to the account on purpose: an invoice key
names exactly one wallet, so there is no lookup that could widen the result
to a sibling wallet the key does not cover.

**The employee must also have `payroll` enabled on their account.** LNbits
gates extension routes per user, not just the UI — `_check_user_access`
runs `check_user_extension_access` (`lnbits/decorators.py:420`) on every
extension path. Without it the endpoint answers `{"detail": "Extension
'payroll' not enabled."}` however valid the invoice key is. Enable it via
`LNBITS_USER_DEFAULT_EXTENSIONS` or per account in the Admin UI.

For the same reason `payroll` must stay **out** of
`LNBITS_ADMIN_EXTENSIONS`: that list trips the earlier branch of the same
check, *"User not authorized for extension"*, which a non-admin can never
clear. It would lock employees out of their own payslips permanently, and
it buys nothing — the operator console is already gated in code by
`check_super_user` on the router and `user.super_user` on the page route.

Known wart: an employee with the extension enabled sees "Payroll" in their
menu, and clicking it hits the operator console route, which 403s. Tracked
as a follow-up — the page should render their payslips instead.