Adopt the one-row bank cost and the bank account in the proposal

This commit is contained in:
ai-bot committed 2026-11-15 13:30:30 +00:00
1 parent 4ce14c6fb9
commit 569844d7a5
1 file changed
+101 -93
+101 -93
View File
@@ -1,147 +1,155 @@
# Proposal — kroner on an account (revised with the owner's answers) # Proposal — kroner on an account, and the bank (third revision)
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 is implemented, and
`docs/spec.md` and `docs/TODO.md` are unchanged. The two open points are answered, the step `docs/spec.md` and `docs/TODO.md` are unchanged. On your yes I write B4.1 first — the spec and the
numbers are lettered so that Phase C and Phase D keep their numbers, and the design below is what plan only — and show you that before any code.
I will write into the spec and the plan, and then build, on your yes.
## The answers this proposal is built on ## The model, as you described it
- **P1 — answered by the owner:** a fixed, hidden account called **Bank**, and a **The bank is a fictional account that pays the costs, and it can never go negative.**
`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 - `Bank` is a real row in `markets`, seeded on first run: `kind = 'other'`, `taxable = 0`,
and not extra features: `archived = 1`. Its id is kept in the setting `bank_market_id`, so nothing has to guess it by
name.
- A `Forvaltningskostnad` of 500 kr is **one row**, with `market_id` = Bank, and it carries two
kroner legs that the server fills from the single amount you type:
`leg_out_ore` = 500 kr (out of the bank) and `leg_in_ore` = 500 kr (back into the bank).
The bank's balance is therefore +500 − 500 = 0, it never goes negative, and no other account is
touched. **No second row is generated** — your last paragraph is right, and it saves the pair
of lines.
- The row shows in `/transaksjonar` exactly as you wrote it:
`{dato}; Forvaltningskostnad; Bank; ; ; 500 kr; 500 kr; ; 0 kr; Ja`
- The tax figure for a `Forvaltningskostnad` is the kroner that are **out** of the bank, which is
the sum of `leg_out_ore` over the year's taxable `Forvaltningskostnad` rows. That is what the
code already computes as `admin_cost_ore`. Rett tenkt.
- You cannot move kroner or sats in or out of the bank by hand: no other transaction may name it,
and it is kept out of the account pickers.
- `Bank` is hidden in `/transaksjon` (no picker) and in `/marknader`, and it is **not** hidden in
`/transaksjonar`, where its name appears in the `Konto` column.
1. **The kroner land on Bank, they do not vanish.** After a `Forvaltningskostnad` of 500 kr from The rest of the proposal stands as before: kroner live on an account as a derived balance, and
an exchange, the exchange is 500 kr lighter and Bank is 500 kr heavier. The money still exists kroner move between real accounts with a `transfer_out` that carries either sats or kroner.
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 ## What I need from you
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. 1. **The deduction, asked again in plain words.** The tax report shows one line,
`Forvaltningskostnad`, with the year's total (say 500 kr). The only question is whether that
total reduces the netto you pay tax on:
- **As it is today (default): no.** With 295 000 kr in gain and 500 kr in cost, the netto is
295 000 kr and the skatt is **64 900 kr**. The cost is a line of its own, not deducted.
- **With the setting `deduct_admin_costs` on: yes.** The netto becomes 294 500 kr and the skatt
**64 790 kr**, that is 110 kr less.
Which do you want? I recommend keeping the default (off), because whether a
forvaltningskostnad is deductible is your call and is still open as Q2 in the spec. Tell me
and I set it in the spec, or leave the setting as it is.
2. **Is it all right that `Bank` also disappears from the main sheet `/` and from the account
rows of the report?** It holds no sats, so it would otherwise show as a row of zeroes. I
propose to keep it out of both, and to show it only in `/transaksjonar`.
3. **A yes** to the rest, or a correction.
--- ---
## A. The proposed spec section ## A. The proposed spec section
Ready to paste into `docs/spec.md` as §3.11.
### 3.11 Kroner on an account, and the bank ### 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**: 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). `value_ore` is not a balance movement — it is the NOK value of a BTC leg —
value of a BTC leg — and `fee_ore` is always 0 (§3.2), so neither enters the balance. 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 - A `trade` buy lowers the balance by the kroner paid and a `trade` sell raises it by the kroner
the kroner received. `income`, `spend`, `gift_received` and `gift_given` do not move it. 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. - Nothing new is stored for this: it is a sum over rows that already exist.
**One account is the bank.** It is named `Bank`, has `kind = 'other'`, `taxable = 0` and **The bank.** One account is the bank: the row `Bank` in `markets`, `kind = 'other'`,
`archived = 1`, and it is seeded on first run like the rates. It is the counterparty for the `taxable = 0`, `archived = 1`, seeded on first run and named by the setting `bank_market_id`. It
kroner that leave an exchange through a `Forvaltningskostnad` (§3.10), so that the outflow and is the counterparty for the costs and it can never go negative:
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 - A `Forvaltningskostnad` is one row on the bank. The amount is entered once, in kroner, and the
row carries `leg_out_ore` and `leg_in_ore` of the same amount, so the bank's balance is
unchanged and no other account is touched.
- The bank is hidden from the account pickers and from the account admin, and no other
transaction may name it. Its name is shown in the transaction list.
- It holds no sats, and it is not part of any tax figure except through the cost line below.
Kroner and sats move between real 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), and `Til` is required. - `transfer_out` with `leg_out_sats`: 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 and arrive on the destination,
destination account, whose generated `transfer_in` gets `leg_in_ore` equal to the sent amount. whose generated `transfer_in` gets `leg_in_ore` equal to the sent amount. No lot is involved
No lot is involved and nothing is realized: kroner are kroner. 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 - **An empty `Til` is a withdrawal, and it is kroner only.** The kroner leave the ledger and no
`transfer_in` is generated. `transfer_in` is generated. A `transfer_out` of sats always needs a `Til`.
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. A buy that overdraws the kroner balance is not refused; it is shown as a negative balance.
`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 ## 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, and then a `transfer_in` to `Bank` is generated. The rest of the section stands, including the setting. | | §3.10 | The cost is one row on the bank, in kroner, with the two legs of §3.11. It consumes no lots and takes no fee. Its own `taxable` flag, ticked by default, decides whether it counts. |
| §3.11 | New, above. | | §3.11 | New, above. |
| §4.1 | A new setting key `bank_market_id`, seeded with the bank's id. |
| §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, 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.3 | `Overføring ut` gets `Sendt: Antall, Valuta (sats/kr)` and `Til`, required for sats and may be empty for kroner. `Forvaltningskostnad` keeps `Kostnad: Antall, Valuta (kr)`, with no account and no fee; the account is the bank and is set by the server. |
| §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.4 | A `transfer_out` with an empty `Til` generates no `transfer_in`, and a kroner transfer mirrors `leg_in_ore`. |
| §7.6 | No new column: `Inn` and `Ut` already carry the unit. | | §7.6 | No new column; `Inn` and `Ut` carry the unit. `Konto` shows `Bank` for a cost. |
| §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`. | | §8 | `POST`/`PATCH` accept `leg_out_ore` on a `transfer_out` and an absent `to_market_id` for kroner only; `admin_cost` is sent as `leg_out_ore` and the server fills the rest. `GET /api/markets` carries `kroner_ore` and leaves the bank out. |
## C. The proposed plan steps (Phase B4) ## C. The proposed plan steps (Phase B4)
Lettered, so that Phase C stays 56–71 and Phase D stays 72. 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 **B4.1 `docs/spec.md`, `docs/TODO.md`.** Fold this in. **Verify:** the spec reads consistently and
this phase. **Verify:** the spec reads consistently, and Phase C and Phase D still carry their Phase C and Phase D keep their numbers.
numbers.
**B4.2 `database.py`.** Seed the `Bank` account next to the settings and the rates, with **B4.2 `database.py`.** Seed the `Bank` row and the `bank_market_id` setting next to the rates,
`INSERT OR IGNORE`. **Verify:** a fresh database has exactly one `Bank` row, and a second run with `INSERT OR IGNORE`, idempotently. **Verify:** a fresh database has one `Bank` row and a
does not add another. `bank_market_id`; a second run adds nothing.
**B4.3 `validation.py`.** A `transfer_out` carries exactly one of `leg_out_sats` / `leg_out_ore`; **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`. `Til` is required for sats and may be empty for kroner; `admin_cost` is sent as `leg_out_ore`, gets
**Verify:** six payloads, clean and rejected, each with a Nynorsk message. its `market_id` and its second leg from the server, and defaults to ticked. **Verify:** eight
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 **B4.4 `ledger.py`.** `kroner_in_market(market_id, date)`, and a refusal in `rebuild()` naming the
the kroner shortfall; a kroner-only transfer consumes no lots. **Verify:** the unit tests, plus a kroner shortfall; a kroner-only transfer consumes no lots. **Verify:** the suite, plus a hand check
hand check of a filled account, an over-drawn one, and one that sold sats first. 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 **B4.5 `app.py`.** `_sync_transfer_pair()` mirrors `leg_out_ore` and writes no pair when `Til` is
empty, and writes the `Bank` pair for an `admin_cost` with an account; `GET /api/markets` carries empty; an `admin_cost` gets the bank and its second leg; `GET /api/markets` carries `kroner_ore`
`kroner_ore`. **Verify:** `curl` a kroner transfer in, a withdrawal, an over-drawn one, and a and leaves the bank out. **Verify:** `curl` a kroner transfer in, a withdrawal, an over-drawn one,
`Forvaltningskostnad`. and a `Forvaltningskostnad`.
**B4.6 `tax.py`, `export.py`.** Nothing taxable changes. **Verify:** the suite, and that a kroner **B4.6 `tax.py`, `export.py`.** Nothing taxable changes: the cost line stays `admin_cost_ore`, and
transfer and a `Forvaltningskostnad` move no figure in the report and no column in the CSV. the bank is in no figure. **Verify:** the suite, and that a kroner transfer moves no figure.
**B4.7 `static/transaction.html`, `static/transaction.js`.** The currency choice on `Sendt`, an **B4.7 `static/transaction.html`, `static/transaction.js`.** The currency choice on `Sendt` and an
empty `Til` allowed for kroner only, the optional `Marknad` on `Forvaltningskostnad`, and `Bank` empty `Til` for kroner. **Verify:** in the browser, a kroner transfer, a withdrawal, and the
kept out of the pickers. **Verify:** in the browser, a kroner transfer, a withdrawal, a refusal message.
`Forvaltningskostnad`, and the refusal message.
**B4.8 `static/markets.html`, `static/markets.js`.** A `Kroner` column. **Verify:** the balance **B4.8 `static/markets.html`, `static/markets.js`.** A `Kroner` column, for real accounts only.
is shown, it drops when a cost names the account, and it rises when a transfer arrives. **Verify:** the balance is shown, it drops when kroner are transferred out, and it rises when they
arrive.
**B4.9 `tests/test_ledger.py`, `tests/test_tax.py`.** The kroner balance, the refusals, the **B4.9 `tests/test_ledger.py`, `tests/test_tax.py`.** The kroner balance, the refusals, the bank's
generated `Bank` pair, and that no tax figure moves. **Verify:** `python3 -m unittest discover two legs leaving it at zero, and that no tax figure moves. **Verify:**
-s tests -v` — green. `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: kroner are derived from the legs, so nothing can drift.
- No conversion between kroner and sats anywhere, and no rate is ever invented. - 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 sats withdrawal: a `transfer_out` of sats always needs a `Til`.
- A buy is not refused when the kroner do not cover it; only transfers are.
- 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 as they do. - 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.