Files
skuld/docs/proposal-kroner.md
T

7.0 KiB
Raw Blame History

Proposal — kroner on an account (for review)

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, and say yes or no. On a yes I fold the accepted text into docs/spec.md and docs/TODO.md as a new phase, and only then write code.

It answers the owner's points 5 and 7 from the B3 review:

  • point 7: fill an exchange with kroner, move kroner (and sats) between accounts, and take kroner out, with the sums on Inn/Ut correct and no way to take out more than an account holds;
  • point 5: whether a Forvaltningskostnad should reduce an account's kroner.

Open points for the owner

Id Question My recommendation
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.
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

Ready to paste into docs/spec.md as §3.11, with §3.2, §3.10, §5.2, §7.3, §7.6 and §8 gaining the lines listed in section C.

3.11 Kroner on an account

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, a trade sell raises it by the kroner received, and income, spend, gift_received and gift_given do not move it at all. Nothing new has to be stored for this to be true.

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), with its generated transfer_in.
  • 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, no lots are involved, and nothing is realized: kroner are kroner.
  • An empty Til is a withdrawal. The amount leaves the ledger and no transfer_in is generated. Kroner change no figure at all; sats and their cost basis leave the ledger, with no 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 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 and consumes no lots, and may name the account the cost was paid from (P1). When it does, the kroner leave that account's balance; when it does not, it stands on its own exactly as today.

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; the rest of the section stands.
§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.4 A transfer_out with an empty Til generates no transfer_in; a kroner transfer mirrors leg_in_ore.
§7.6 Inn/Ut already carry the unit; the list needs no new column.
§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.

C. The proposed plan steps

Each step names its files and its verification, in the shape of the existing plan.

  1. docs/spec.md, docs/TODO.md — fold the approved text in: §3.11, the table above, and the new phase. Verify: the spec reads consistently and the plan's Phase C numbers are updated.
  2. validation.py — a transfer_out carries exactly one of leg_out_sats / leg_out_ore; an 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.
  3. 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 and an over-drawn account.
  4. app.py — _sync_transfer_pair() mirrors leg_out_ore and writes no pair when Til is empty; GET /api/markets carries kroner_ore. Verify: curl a kroner transfer in, a withdrawal, and an over-drawn one.
  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.
  6. static/transaction.html, static/transaction.js — the currency choice on Sendt, an empty Til allowed, the optional Marknad on Forvaltningskostnad. Verify: in the browser, a kroner transfer, a withdrawal, and the refusal message.
  7. static/markets.html, static/markets.js — a Kroner column. Verify: the account table shows the balance, and it drops when a cost names the account.
  8. tests/test_ledger.py — the kroner balance and the refusal. Verify: the suite.
  9. tests/test_tax.py — a kroner transfer moves no figure; a cost with an account does not change the tax figures either. Verify: the suite.

D. Deliberately not in this proposal

  • 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 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.
  • value_ore keeps its meaning (the NOK value of a BTC leg) and is not a balance movement.