8.7 KiB
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
Forvaltningskostnadthat automatically generates atransfer_inof the same kroner to Bank, so thatUtandInnare equal and the cost is not deducted from the netto. - P2 — answered by the owner: a withdrawal without
Tilapplies to kroner only, and only when the account actually holds the kroner (for instance after selling sats for kroner). Atransfer_outof sats therefore always needs aTil.
Two things follow from P1 that I want on the record, because they are consequences of the design and not extra features:
- The kroner land on Bank, they do not vanish. After a
Forvaltningskostnadof 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 makesUtandInnequal. If you would rather the kroner leave the ledger altogether, say so and I drop the generated row. admin_cost_oreis still its own line in the report, and it is subtracted fromnetto_oreonly whendeduct_admin_costsis 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) 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 and atradesell raises it by the kroner received.income,spend,gift_receivedandgift_givendo 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_outwithleg_out_sats: exactly as today (§3.3), andTilis required.transfer_outwithleg_out_ore: the kroner leave the source account and arrive on the destination account, whose generatedtransfer_ingetsleg_in_oreequal to the sent amount. No lot is involved and nothing is realized: kroner are kroner.- An empty
Tilis a withdrawal, and it is kroner only. The kroner leave the ledger and notransfer_inis 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_inof the same kroner is generated onBank, with the same date andtransfer_group.UtandInnare 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_outof sats always needs aTil(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_orekeeps 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.