7.0 KiB
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/Utcorrect and no way to take out more than an account holds; - point 5: whether a
Forvaltningskostnadshould 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) andleg_out_ore(out) of its transactions.value_oreis not a balance movement: it is the NOK value of a BTC leg, andfee_oreis always 0 (§3.2), so neither enters the balance. - A
tradebuy therefore lowers the balance by the kroner paid, atradesell raises it by the kroner received, andincome,spend,gift_receivedandgift_givendo 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_outwithleg_out_sats: exactly as today (§3.3), with its generatedtransfer_in.transfer_outwithleg_out_ore: the kroner leave the source account and arrive on the destination account. The generatedtransfer_ingetsleg_in_oreequal to the sent amount, no lots are involved, and nothing is realized: kroner are kroner.- An empty
Tilis a withdrawal. The amount leaves the ledger and notransfer_inis 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.
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.validation.py— atransfer_outcarries exactly one ofleg_out_sats/leg_out_ore; an emptyto_market_idis allowed and means a withdrawal;admin_costmay take amarket_id(P1). Verify: four payloads, clean and rejected, in Nynorsk.ledger.py—kroner_in_market(market_id, date), and a refusal inrebuild()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.app.py—_sync_transfer_pair()mirrorsleg_out_oreand writes no pair whenTilis empty;GET /api/marketscarrieskroner_ore. Verify:curla kroner transfer in, a withdrawal, and an over-drawn one.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.static/transaction.html,static/transaction.js— the currency choice onSendt, an emptyTilallowed, the optionalMarknadon Forvaltningskostnad. Verify: in the browser, a kroner transfer, a withdrawal, and the refusal message.static/markets.html,static/markets.js— aKronercolumn. Verify: the account table shows the balance, and it drops when a cost names the account.tests/test_ledger.py— the kroner balance and the refusal. Verify: the suite.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_orekeeps its meaning (the NOK value of a BTC leg) and is not a balance movement.