Files
skuld/docs/proposal-kroner.md
T

9.4 KiB
Raw Blame History

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.