Files
skuld/docs/proposal-kroner.md
T

112 lines
7.0 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 (for review)
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. Read it, answer the two open points at the top,
and say yes or no. On a yes I fold the accepted text into `docs/spec.md` and `docs/TODO.md` as a
new phase, and only then write code.
It answers the owner's points 5 and 7 from the B3 review:
- point 7: fill an exchange with kroner, move kroner (and sats) between accounts, and take kroner
out, with the sums on `Inn`/`Ut` correct and no way to take out more than an account holds;
- point 5: whether a `Forvaltningskostnad` should reduce an account's kroner.
---
## Open points for the owner
| Id | Question | My recommendation |
| --- | --- | --- |
| P1 | May a `Forvaltningskostnad` name the account the cost was paid from, so the kroner leave that account's balance? Today §3.10 says it is never attached to an account. | **Yes, optionally.** One entry instead of two, and it answers point 5 without inventing a generated row. When the account is left empty it behaves exactly as today. |
| P2 | May a `transfer_out` with an empty `Til` withdraw **sats**, and not only kroner? The sats and their cost basis would leave the ledger with no gain and no deduction — the same assumption as a gift given (Q1). | **Yes.** It is the same mechanism as kroner, and a coin that leaves the ledger has to leave the cost basis too. If you would rather not have it, sats must always have a `Til` and only kroner may be withdrawn. |
Also decide the step numbering: I propose the new phase as **steps 56–64**, which shifts Phase C
to 65–80 and Phase D to 81. If you would rather keep the Phase C numbers as they are, I can
letter the new steps `B4.1 … B4.9` instead.
---
## A. The proposed spec section
Ready to paste into `docs/spec.md` as §3.11, with §3.2, §3.10, §5.2, §7.3, §7.6 and §8 gaining
the lines listed in section C.
### 3.11 Kroner on an account
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, a `trade` sell raises it by the
kroner received, and `income`, `spend`, `gift_received` and `gift_given` do not move it at all.
Nothing new has to be stored for this to be true.
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), with its generated `transfer_in`.
- `transfer_out` with `leg_out_ore`: the kroner leave the source account and arrive on the
destination account. The generated `transfer_in` gets `leg_in_ore` equal to the sent amount,
no lots are involved, and nothing is realized: kroner are kroner.
- **An empty `Til` is a withdrawal.** The amount leaves the ledger and no `transfer_in` is
generated. Kroner change no figure at all; sats and their cost basis leave the ledger, with no
gain and no deduction, the same assumption as a gift given (Q1, P2).
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 and consumes no lots, and may name the account
the cost was paid from (P1). When it does, the kroner leave that account's balance; when it does
not, it stands on its own exactly as today.
## 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; the rest of the section stands. |
| §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, may be empty (= withdrawal)`. `Forvaltningskostnad` gets an optional `Marknad` (P1). |
| §7.4 | A `transfer_out` with an empty `Til` generates no `transfer_in`; a kroner transfer mirrors `leg_in_ore`. |
| §7.6 | `Inn`/`Ut` already carry the unit; the list needs no new column. |
| §8 | `POST`/`PATCH` accept `leg_out_ore` on a `transfer_out`, an absent `to_market_id`, and a `market_id` on `admin_cost` (P1). `GET /api/markets` carries `kroner_ore`. |
## C. The proposed plan steps
Each step names its files and its verification, in the shape of the existing plan.
1. `docs/spec.md`, `docs/TODO.md` — fold the approved text in: §3.11, the table above, and the new
phase. **Verify:** the spec reads consistently and the plan's Phase C numbers are updated.
2. `validation.py` — a `transfer_out` carries exactly one of `leg_out_sats` / `leg_out_ore`; an
empty `to_market_id` is allowed and means a withdrawal; `admin_cost` may take a `market_id`
(P1). **Verify:** four payloads, clean and rejected, in Nynorsk.
3. `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 and an over-drawn account.
4. `app.py` — `_sync_transfer_pair()` mirrors `leg_out_ore` and writes no pair when `Til` is
empty; `GET /api/markets` carries `kroner_ore`. **Verify:** `curl` a kroner transfer in, a
withdrawal, and an over-drawn one.
5. `tax.py`, `export.py` — nothing taxable changes; the CSV gains no column. **Verify:** the
suite, and that a kroner transfer moves no figure in the report.
6. `static/transaction.html`, `static/transaction.js` — the currency choice on `Sendt`, an empty
`Til` allowed, the optional `Marknad` on Forvaltningskostnad. **Verify:** in the browser, a
kroner transfer, a withdrawal, and the refusal message.
7. `static/markets.html`, `static/markets.js` — a `Kroner` column. **Verify:** the account table
shows the balance, and it drops when a cost names the account.
8. `tests/test_ledger.py` — the kroner balance and the refusal. **Verify:** the suite.
9. `tests/test_tax.py` — a kroner transfer moves no figure; a cost with an account does not change
the tax figures either. **Verify:** the suite.
## D. Deliberately not in this proposal
- No stored balance: the kroner are derived from the legs, so nothing can drift.
- No currency conversion anywhere. Kroner stay kroner; the app never invents a rate.
- No new asset, no bank import, no price feed (§11).
- No change to the sats ledger: lots, methods and the report keep working exactly as they do.
- `value_ore` keeps its meaning (the NOK value of a BTC leg) and is not a balance movement.