diff --git a/docs/proposal-kroner.md b/docs/proposal-kroner.md index 50ed2d3..17f6879 100644 --- a/docs/proposal-kroner.md +++ b/docs/proposal-kroner.md @@ -1,111 +1,147 @@ -# Proposal — kroner on an account (for review) +# 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. 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. +`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. -It answers the owner's points 5 and 7 from the B3 review: +## The answers this proposal is built on -- 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. +- **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: -## Open points for the owner +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. -| 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. +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, with §3.2, §3.10, §5.2, §7.3, §7.6 and §8 gaining -the lines listed in section C. +Ready to paste into `docs/spec.md` as §3.11. -### 3.11 Kroner on an account +### 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, 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. + `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), with its generated `transfer_in`. +- `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. 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). + 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 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. +`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; the rest of the section stands. | +| §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, 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`. | +| §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 +## C. The proposed plan steps (Phase B4) -Each step names its files and its verification, in the shape of the existing plan. +Lettered, so that Phase C stays 56–71 and Phase D stays 72. -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. +**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 currency conversion anywhere. Kroner stay kroner; the app never invents a rate. +- 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 exactly as they do. -- `value_ore` keeps its meaning (the NOK value of a BTC leg) and is not a balance movement. +- 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.