Files
skuld/docs/proposal-kroner.md
T

148 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Proposal — kroner on an account (revised with the owner's answers)
This is a **proposal**, not the contract and not the plan. Nothing here is implemented, and
`docs/spec.md` and `docs/TODO.md` are unchanged. The two open points are answered, the step
numbers are lettered so that Phase C and Phase D keep their numbers, and the design below is what
I will write into the spec and the plan, and then build, on your yes.
## The answers this proposal is built on
- **P1 — answered by the owner:** a fixed, hidden account called **Bank**, and a
`Forvaltningskostnad` that automatically generates a `transfer_in` of the same kroner to Bank,
so that `Ut` and `Inn` are equal and the cost is not deducted from the netto.
- **P2 — answered by the owner:** a withdrawal without `Til` applies to **kroner only**, and only
when the account actually holds the kroner (for instance after selling sats for kroner). A
`transfer_out` of sats therefore always needs a `Til`.
Two things follow from P1 that I want on the record, because they are consequences of the design
and not extra features:
1. **The kroner land on Bank, they do not vanish.** After a `Forvaltningskostnad` of 500 kr from
an exchange, the exchange is 500 kr lighter and Bank is 500 kr heavier. The money still exists
in the ledger. That is what makes `Ut` and `Inn` equal. If you would rather the kroner leave
the ledger altogether, say so and I drop the generated row.
2. **`admin_cost_ore` is still its own line in the report**, and it is subtracted from `netto_ore`
only when `deduct_admin_costs` is on — which is off by default, so by default nothing is
deducted. The pair of rows does not change any tax figure.
And one small decision I have taken, which you can overrule: **Bank is hidden from the account
pickers in the transaction form, but it is listed on `/marknader`** (as an archived account), so
that its kroner balance is visible somewhere. If you want it out of sight there too, say so.
---
## A. The proposed spec section
Ready to paste into `docs/spec.md` as §3.11.
### 3.11 Kroner on an account, and the bank
A market can hold kroner as well as sats. The kroner balance of an account is **derived and never
stored**: it is the kroner that came in minus the kroner that went out, over that account's own
transactions, as of a date.
- A leg carries one currency (§4), so the kroner of an account are exactly `leg_in_ore` (in) and
`leg_out_ore` (out) of its transactions. `value_ore` is not a balance movement — it is the NOK
value of a BTC leg — and `fee_ore` is always 0 (§3.2), so neither enters the balance.
- A `trade` buy therefore lowers the balance by the kroner paid and a `trade` sell raises it by
the kroner received. `income`, `spend`, `gift_received` and `gift_given` do not move it.
- Nothing new is stored for this: the balance is a sum over the rows that already exist.
**One account is the bank.** It is named `Bank`, has `kind = 'other'`, `taxable = 0` and
`archived = 1`, and it is seeded on first run like the rates. It is the counterparty for the
kroner that leave an exchange through a `Forvaltningskostnad` (§3.10), so that the outflow and
the inflow of a cost are equal. It is hidden from the account pickers of the transaction form and
is not part of any tax figure.
Kroner and sats move between accounts with a `transfer_out`, which carries **either sats or
kroner, never both**:
- `transfer_out` with `leg_out_sats`: exactly as today (§3.3), and `Til` is required.
- `transfer_out` with `leg_out_ore`: the kroner leave the source account and arrive on the
destination account, whose generated `transfer_in` gets `leg_in_ore` equal to the sent amount.
No lot is involved and nothing is realized: kroner are kroner.
- **An empty `Til` is a withdrawal, and it is kroner only.** The kroner leave the ledger and no
`transfer_in` is generated.
A `transfer_out` is refused when the source account does not hold enough of the currency as of
the transaction date: the lot ledger refuses sats and names the shortfall in sats (§5.2), and the
derived balance refuses kroner and names the shortfall in kroner. Skuld never invents coins or
kroner.
`Forvaltningskostnad` (§3.10) keeps its own line, consumes no lots and takes no fee, and may name
the account the cost was paid from:
- With an account: the kroner leave that account's balance, and a `transfer_in` of the same
kroner is generated on `Bank`, with the same date and `transfer_group`. `Ut` and `Inn` are
equal, and no tax figure changes.
- Without an account: the row stands on its own, exactly as today, and no kroner move.
## B. What changes in the existing sections
| Section | Change |
| --- | --- |
| §3.2 | A line that `fee_ore` stays 0 and never enters a kroner balance. |
| §3.10 | `market_id` may name the account the cost was paid from, and then a `transfer_in` to `Bank` is generated. The rest of the section stands, including the setting. |
| §3.11 | New, above. |
| §5.2 | A kroner-only `transfer_out` consumes no lots. |
| §7.3 | `Overføring ut` gets `Sendt: Antall, Valuta (sats/kr)` and `Til: account selector, required for sats, may be empty for kr`. `Forvaltningskostnad` gets `Kostnad: Antall, Valuta (kr)` plus an optional `Marknad` (the account it was paid from). `Bank` never appears in a picker. |
| §7.4 | A `transfer_out` with an empty `Til` generates no `transfer_in`; a kroner transfer mirrors `leg_in_ore`; a `Forvaltningskostnad` with an account generates a `transfer_in` to `Bank`. |
| §7.6 | No new column: `Inn` and `Ut` already carry the unit. |
| §8 | `POST`/`PATCH` accept `leg_out_ore` on a `transfer_out`, an absent `to_market_id` for kroner only, and a `market_id` on `admin_cost`. `GET /api/markets` carries `kroner_ore`. |
## C. The proposed plan steps (Phase B4)
Lettered, so that Phase C stays 56–71 and Phase D stays 72.
**B4.1 `docs/spec.md`, `docs/TODO.md`.** Fold the approved text in: §3.11, the table above, and
this phase. **Verify:** the spec reads consistently, and Phase C and Phase D still carry their
numbers.
**B4.2 `database.py`.** Seed the `Bank` account next to the settings and the rates, with
`INSERT OR IGNORE`. **Verify:** a fresh database has exactly one `Bank` row, and a second run
does not add another.
**B4.3 `validation.py`.** A `transfer_out` carries exactly one of `leg_out_sats` / `leg_out_ore`;
`Til` is required for sats and may be empty for kroner; `admin_cost` may take a `market_id`.
**Verify:** six payloads, clean and rejected, each with a Nynorsk message.
**B4.4 `ledger.py`.** `kroner_in_market(market_id, date)`, and a refusal in `rebuild()` naming
the kroner shortfall; a kroner-only transfer consumes no lots. **Verify:** the unit tests, plus a
hand check of a filled account, an over-drawn one, and one that sold sats first.
**B4.5 `app.py`.** `_sync_transfer_pair()` mirrors `leg_out_ore`, writes no pair when `Til` is
empty, and writes the `Bank` pair for an `admin_cost` with an account; `GET /api/markets` carries
`kroner_ore`. **Verify:** `curl` a kroner transfer in, a withdrawal, an over-drawn one, and a
`Forvaltningskostnad`.
**B4.6 `tax.py`, `export.py`.** Nothing taxable changes. **Verify:** the suite, and that a kroner
transfer and a `Forvaltningskostnad` move no figure in the report and no column in the CSV.
**B4.7 `static/transaction.html`, `static/transaction.js`.** The currency choice on `Sendt`, an
empty `Til` allowed for kroner only, the optional `Marknad` on `Forvaltningskostnad`, and `Bank`
kept out of the pickers. **Verify:** in the browser, a kroner transfer, a withdrawal, a
`Forvaltningskostnad`, and the refusal message.
**B4.8 `static/markets.html`, `static/markets.js`.** A `Kroner` column. **Verify:** the balance
is shown, it drops when a cost names the account, and it rises when a transfer arrives.
**B4.9 `tests/test_ledger.py`, `tests/test_tax.py`.** The kroner balance, the refusals, the
generated `Bank` pair, and that no tax figure moves. **Verify:** `python3 -m unittest discover
-s tests -v` — green.
## D. Deliberately not in this proposal
- No stored balance: the kroner are derived from the legs, so nothing can drift.
- No conversion between kroner and sats anywhere, and no rate is ever invented.
- No sats withdrawal: a `transfer_out` of sats always needs a `Til` (P2).
- No new asset, no bank import, no price feed (§11).
- No change to the sats ledger: lots, methods and the report keep working as they do.
- `value_ore` keeps its meaning and is not a balance movement.
## E. What I need from you
A **yes**, or a correction on any of the three points above: the kroner landing on `Bank` instead
of vanishing, `admin_cost_ore` keeping its setting, or `Bank` being visible on `/marknader`.
On a yes I write B4.1 first (spec and plan only), show you that, and then build the rest, one
file per turn. I am not starting Phase C.