Files
skuld/docs/proposal-kroner.md
T

8.7 KiB
Raw Blame History

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. 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.

The answers this proposal is built on

  • 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:

  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.

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.

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 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), and Til is required.
  • transfer_out with leg_out_ore: the kroner leave the source account and arrive on the 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, 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, 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, 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 (Phase B4)

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 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 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 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.