Files
skuld/docs/proposal-kroner.md
T

156 lines
9.4 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, and the bank (third revision)
This is a **proposal**, not the contract and not the plan. Nothing is implemented, and
`docs/spec.md` and `docs/TODO.md` are unchanged. On your yes I write B4.1 first — the spec and the
plan only — and show you that before any code.
## The model, as you described it
**The bank is a fictional account that pays the costs, and it can never go negative.**
- `Bank` is a real row in `markets`, seeded on first run: `kind = 'other'`, `taxable = 0`,
`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.
The rest of the proposal stands as before: kroner live on an account as a derived balance, and
kroner move between real accounts with a `transfer_out` that carries either sats or kroner.
## What I need from you
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
### 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**: 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). `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 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: it is a sum over rows that already exist.
**The bank.** One account is the bank: the row `Bank` in `markets`, `kind = 'other'`,
`taxable = 0`, `archived = 1`, seeded on first run and named by the setting `bank_market_id`. It
is the counterparty for the costs and it can never go negative:
- 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**:
- `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 and arrive on the destination,
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` of sats always needs a `Til`.
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. A buy that overdraws the kroner balance is not refused; it is shown as a negative balance.
## 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 | 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. |
| §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. |
| §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`, and a kroner transfer mirrors `leg_in_ore`. |
| §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` 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)
Lettered, so that Phase C stays 56–71 and Phase D stays 72.
**B4.1 `docs/spec.md`, `docs/TODO.md`.** Fold this in. **Verify:** the spec reads consistently and
Phase C and Phase D keep their numbers.
**B4.2 `database.py`.** Seed the `Bank` row and the `bank_market_id` setting next to the rates,
with `INSERT OR IGNORE`, idempotently. **Verify:** a fresh database has one `Bank` row and a
`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`;
`Til` is required for sats and may be empty for kroner; `admin_cost` is sent as `leg_out_ore`, gets
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 the
kroner shortfall; a kroner-only transfer consumes no lots. **Verify:** the suite, 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` and writes no pair when `Til` is
empty; an `admin_cost` gets the bank and its second leg; `GET /api/markets` carries `kroner_ore`
and leaves the bank out. **Verify:** `curl` a kroner transfer in, a withdrawal, an over-drawn one,
and a `Forvaltningskostnad`.
**B4.6 `tax.py`, `export.py`.** Nothing taxable changes: the cost line stays `admin_cost_ore`, and
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` and an
empty `Til` for kroner. **Verify:** in the browser, a kroner transfer, a withdrawal, and the
refusal message.
**B4.8 `static/markets.html`, `static/markets.js`.** A `Kroner` column, for real accounts only.
**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 bank's
two legs leaving it at zero, and that no tax figure moves. **Verify:**
`python3 -m unittest discover -s tests -v` — green.
## D. Deliberately not in this proposal
- 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 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 change to the sats ledger: lots, methods and the report keep working as they do.