Revise the kroner proposal with the owner's answers and lettered steps

This commit is contained in:
ai-bot committed 2026-11-15 13:14:01 +00:00
1 parent cc9af95ae0
commit 4ce14c6fb9
1 file changed
+102 -66
+102 -66
View File
@@ -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 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, `docs/spec.md` and `docs/TODO.md` are unchanged. The two open points are answered, the step
and say yes or no. On a yes I fold the accepted text into `docs/spec.md` and `docs/TODO.md` as a numbers are lettered so that Phase C and Phase D keep their numbers, and the design below is what
new phase, and only then write code. 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 - **P1 — answered by the owner:** a fixed, hidden account called **Bank**, and a
out, with the sums on `Inn`/`Ut` correct and no way to take out more than an account holds; `Forvaltningskostnad` that automatically generates a `transfer_in` of the same kroner to Bank,
- point 5: whether a `Forvaltningskostnad` should reduce an account's kroner. 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 | 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
| 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. | that its kroner balance is visible somewhere. If you want it out of sight there too, say so.
| 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 ## 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 Ready to paste into `docs/spec.md` as §3.11.
the lines listed in section C.
### 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 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 stored**: it is the kroner that came in minus the kroner that went out, over that account's own
transactions, as of a date. transactions, as of a date.
- A leg carries one currency (§4), so the kroner of an account are exactly `leg_in_ore` (in) and - 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 `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. 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 - A `trade` buy therefore lowers the balance by the kroner paid and a `trade` sell raises it by
kroner received, and `income`, `spend`, `gift_received` and `gift_given` do not move it at all. the kroner received. `income`, `spend`, `gift_received` and `gift_given` do not move it.
Nothing new has to be stored for this to be true. - 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 and sats move between accounts with a `transfer_out`, which carries **either sats or
kroner, never both**: 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 - `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, destination account, whose generated `transfer_in` gets `leg_in_ore` equal to the sent amount.
no lots are involved, and nothing is realized: kroner are kroner. No lot is involved and nothing is realized: kroner are kroner.
- **An empty `Til` is a withdrawal.** The amount leaves the ledger and no `transfer_in` is - **An empty `Til` is a withdrawal, and it is kroner only.** The kroner leave the ledger and no
generated. Kroner change no figure at all; sats and their cost basis leave the ledger, with no `transfer_in` is generated.
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 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 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 derived balance refuses kroner and names the shortfall in kroner. Skuld never invents coins or
kroner. kroner.
`Forvaltningskostnad` (§3.10) keeps its own line and consumes no lots, and may name the account `Forvaltningskostnad` (§3.10) keeps its own line, consumes no lots and takes no fee, and may name
the cost was paid from (P1). When it does, the kroner leave that account's balance; when it does the account the cost was paid from:
not, it stands on its own exactly as today.
- 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 ## B. What changes in the existing sections
| Section | Change | | Section | Change |
| --- | --- | | --- | --- |
| §3.2 | A line that `fee_ore` stays 0 and never enters a kroner balance. | | §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. | | §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.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`. | | §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 | `Inn`/`Ut` already carry the unit; the list needs no new column. | | §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`, and a `market_id` on `admin_cost` (P1). `GET /api/markets` carries `kroner_ore`. | | §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 **B4.1 `docs/spec.md`, `docs/TODO.md`.** Fold the approved text in: §3.11, the table above, and
phase. **Verify:** the spec reads consistently and the plan's Phase C numbers are updated. this phase. **Verify:** the spec reads consistently, and Phase C and Phase D still carry their
2. `validation.py` — a `transfer_out` carries exactly one of `leg_out_sats` / `leg_out_ore`; an numbers.
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. **B4.2 `database.py`.** Seed the `Bank` account next to the settings and the rates, with
3. `ledger.py` — `kroner_in_market(market_id, date)`, and a refusal in `rebuild()` naming the `INSERT OR IGNORE`. **Verify:** a fresh database has exactly one `Bank` row, and a second run
kroner shortfall; a kroner-only transfer consumes no lots. **Verify:** the unit tests plus a does not add another.
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 **B4.3 `validation.py`.** A `transfer_out` carries exactly one of `leg_out_sats` / `leg_out_ore`;
empty; `GET /api/markets` carries `kroner_ore`. **Verify:** `curl` a kroner transfer in, a `Til` is required for sats and may be empty for kroner; `admin_cost` may take a `market_id`.
withdrawal, and an over-drawn one. **Verify:** six payloads, clean and rejected, each with a Nynorsk message.
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. **B4.4 `ledger.py`.** `kroner_in_market(market_id, date)`, and a refusal in `rebuild()` naming
6. `static/transaction.html`, `static/transaction.js` — the currency choice on `Sendt`, an empty the kroner shortfall; a kroner-only transfer consumes no lots. **Verify:** the unit tests, plus a
`Til` allowed, the optional `Marknad` on Forvaltningskostnad. **Verify:** in the browser, a hand check of a filled account, an over-drawn one, and one that sold sats first.
kroner transfer, a withdrawal, and the refusal message.
7. `static/markets.html`, `static/markets.js` — a `Kroner` column. **Verify:** the account table **B4.5 `app.py`.** `_sync_transfer_pair()` mirrors `leg_out_ore`, writes no pair when `Til` is
shows the balance, and it drops when a cost names the account. empty, and writes the `Bank` pair for an `admin_cost` with an account; `GET /api/markets` carries
8. `tests/test_ledger.py` — the kroner balance and the refusal. **Verify:** the suite. `kroner_ore`. **Verify:** `curl` a kroner transfer in, a withdrawal, an over-drawn one, and a
9. `tests/test_tax.py` — a kroner transfer moves no figure; a cost with an account does not change `Forvaltningskostnad`.
the tax figures either. **Verify:** the suite.
**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 ## D. Deliberately not in this proposal
- No stored balance: the kroner are derived from the legs, so nothing can drift. - 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 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. - No change to the sats ledger: lots, methods and the report keep working as they do.
- `value_ore` keeps its meaning (the NOK value of a BTC leg) and is not a balance movement. - `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.