diff --git a/docs/proposal-kroner.md b/docs/proposal-kroner.md new file mode 100644 index 0000000..50ed2d3 --- /dev/null +++ b/docs/proposal-kroner.md @@ -0,0 +1,111 @@ +# 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.