# Skuld — work plan Read `docs/spec.md` first. It is the contract; this file is the order of work. If this plan and the spec disagree, the spec wins and the disagreement is a bug in this file. ## Goal A StartOS service package named **Skuld**: a self-hosted web app that keeps a Bitcoin ledger and computes the Norwegian tax figures for a tax year (formue, gevinst, tap, inntekt). Python standard library, SQLite on the `main` volume, admin-password protected, UI in Norwegian Nynorsk. After the last step the package builds, installs on StartOS, and produces the same figures as the owner's spreadsheet. ## Not in this plan Everything in `docs/spec.md` §11. Specifically: no other assets than BTC, no price feeds or exchange import, no multi-user, no database encryption, no charts, no NOSTR, no PHP version. Do not add abstraction, configuration or dependencies for any of them. The PHP version (§12) is a later project; the only concession to it is that the DDL lives in `schema.sql`. ## Rules for every step - Code, identifiers, comments and commit messages in English. User-facing text in Nynorsk. - One step, then the repository is consistent: it imports, the tests pass, and nothing is left half-written. Never leave a page without its script or a module without its caller. - Commit at the end of each step, message in English, one line about what changed. - Run the step's verification before moving on. If it fails, fix it in the same step. - Do not reorder. Phase B2 must be finished before Phase C starts. - When the spec is silent, choose the smaller option and record the choice in the commit message. Ask the owner only for the four open questions in the spec (§13). ## Decisions and why | # | Decision | Reason | | --- | --- | --- | | D1 | Python standard library + SQLite, same shape as the owner's VardKey app | No dependencies to install or patch, one file to back up, and the logic stays plain SQL and arithmetic so the PHP port is mechanical | | D2 | Dates as `TEXT 'YYYY-MM-DD'` | Sorts and compares correctly in SQLite, no timezone handling anywhere | | D3 | Money as integer øre, BTC as integer sats | No floating point in the ledger, so no rounding drift in cost bases | | D4 | Lot-based ledger, explicit lot picking plus FIFO/LIFO/HIFO | The owner asked for UTXO-like picking; Norway has no FIFO requirement, so both must exist | | D5 | `ledger.rebuild()` recomputes lots and auto consumptions on every write | Simplest model that cannot be corrupted by an edit or a delete, and fast enough for thousands of transactions | | D6 | `schema.sql` at the repository root is the only DDL source, applied by `database.py` | One place to change, and phase 2 can apply the same file | | D7 | Server returns JSON only; every page is a static file under `static/`; no JS framework, no build step | Same pattern as VardKey, and it is the pattern that ports to PHP unchanged | | D8 | Prices entered by hand, seeded with Skatteetaten's published year-end BTC rates | A StartOS service should not need an external price API, and the owner already enters values by hand | | D9 | GPL-3.0 | The auth pattern and the packaging shape are adapted from VardKey, which is GPL-3.0 | | D10 | Wealth tax off by default, threshold and rate configurable | Thresholds change every year; a hardcoded number would be wrong within a year | | D11 | A transfer consumes lots at the source and mirrors them at the destination, and generates the `transfer_in` row | The owner's spec requires the auto-generated row; mirroring is what carries the acquisition date and the cost basis | | D12 | Non-taxable accounts are real accounts with `taxable = 0`, plus `custody_market_id` for the `TOT` rows | Reproduces the spreadsheet's main sheet, including the reconciliation rows | | D13 | No secret-scanning module, unlike VardKey | Skuld has no field where a seed phrase or a key would belong; a guard would be decoration | | D14 | The 22 % rate is a setting, not a constant | Rates change; the report shows which rate produced the figures | | D15 | BTC is shown in sats everywhere, in the UI and in the CSV; the only `10^8` conversion is inside the price and formue arithmetic | The owner reads sats; a BTC amount with eight decimals is unreadable in a sheet | | D16 | NOK is displayed in whole kroner, stored and computed in øre; decimals are accepted only in input fields | The owner does not want to see decimals, but rounding in the ledger would lose øre and let sums drift | | D17 | `admin_cost` has no account (`market_id` null), takes no fee, and consumes no lots | The owner wants it to stand on its own; it changes no holdings, so nothing else can be derived from it | | D18 | The transaction price is derived on the fly and never stored, and is called `btc_price_ore` in the API on both transactions and lots | It is a function of legs the owner already entered, so storing it would let it drift; the owner's word for it is "bitcoin pris", so the API uses one name for one unit | | D19 | The stored rate column keeps its name `prices.nok_per_btc_ore`, and the settings table keeps the heading `NOK per BTC` | It is Skatteetaten's year-end rate, not a transaction price; renaming a stored column buys a migration and nothing else | | D20 | The Avgift section is hidden for `gift_received` and `admin_cost` | The owner's field list gives those two no fee, and the schema now refuses one | ## Phase A — application core (steps 1-16) — DONE Implemented and committed: `LICENSE`, `.gitignore`, `schema.sql`, `database.py`, `rates.py`, `auth.py`, `validation.py`, `ledger.py`, `tax.py`, `export.py`, `maintenance.py`, `app.py` (in three steps) and `tests/test_ledger.py`, `tests/test_tax.py`. `python3 -m unittest discover -s tests -v` is green. ## Phase B — user interface (steps 17-26) — DONE Implemented and committed: `static/style.css`, `static/session.js`, `static/app.js`, and the page pairs `login.*`, `index.*`, `transactions.*`, `transaction.*`, `markets.*`, `report.*` and `settings.*`. ## Phase B2 — corrections the owner asked for (steps 27-44) Do these before Phase C. They change the ledger schema, the field set of one transaction type, the way amounts are shown, and add one derived figure. Nothing here is optional, and nothing here may spill into Phase C. ### 27. `schema.sql` Change `transactions.market_id` from `INTEGER NOT NULL REFERENCES markets(id)` to `INTEGER REFERENCES markets(id)`, with a comment that it is null only for `admin_cost`. Add the two CHECK constraints of `docs/spec.md` §4: `(type = 'admin_cost' OR market_id IS NOT NULL)` and `(type NOT IN ('gift_received', 'admin_cost') OR (fee_sats = 0 AND fee_ore = 0))`. `lots` keeps its `NOT NULL`. **Verify:** on a fresh database, an `INSERT` of an `admin_cost` row without a market succeeds, the same insert for a `trade` fails, and an `admin_cost` with a fee fails. ### 28. `rates.py` Replace `parse_btc_to_sats(text)` with `parse_sats(text)`: whole sats only, space, narrow space and non-breaking space allowed as thousands separators, a decimal separator rejected with `ValueError`. Replace `ore_to_nok(ore)` with `kroner_whole(ore)`: whole kroner, halves rounded up, grouped with spaces, no unit and no decimals. Delete `sats_to_btc()`. Keep `nok_to_ore`, `group_int`, `SATS_PER_BTC`, `ORE_PER_NOK` and the rate functions untouched. **Verify:** `parse_sats("1 500 000") == 1500000`, `parse_sats("1500000") == 1500000`, `parse_sats("0,5")` raises, `kroner_whole(106037489) == "1 060 375"`. ### 29. `validation.py` `validate_sats` uses `rates.parse_sats` and its messages talk about sats: "Antal må fyllast ut.", "Antal må vere eit heiltal i sats.", "Antal må vere større enn null." `_ALLOWED_LEGS` for `admin_cost` becomes `("leg_out_sats",)` and `_REQUIRED["admin_cost"]` becomes `(("leg_out_sats", "Fyll ut kostnaden i sats."),)`. `_check_admin_cost` requires exactly one `leg_out_sats` and rejects `leg_out_ore`. `validate_transaction` must not require an account for `admin_cost` (store `market_id` as `None`), must still require one for every other type, must reject a fee for `admin_cost` and `gift_received`, and must default the taxable flag to 1 for `admin_cost` since there is no account to take it from. **Verify:** a manual check that an `admin_cost` payload without `market_id` validates clean, and that the same payload with `leg_out_ore` gives a Nynorsk error on `leg_out_sats`. ### 30. `ledger.py` Remove `admin_cost` from `CONSUMING_TYPES`. Rename the derived field of `_lot_view` from `nok_per_btc_ore` to `btc_price_ore` (`docs/spec.md` §8), keeping the arithmetic identical. **Verify:** `python3 -m unittest discover -s tests -v`; an `admin_cost` row leaves every lot untouched after `ledger.rebuild()`. ### 31. `tax.py` Add `btc_price_ore(tx)`: the bitcoin price of `docs/spec.md` §7.3 as øre per whole BTC, or `None`. The kroner amount is `leg_out_ore` or `leg_in_ore`; the sats amount is the sats leg; for `income` and `gift_received` the kroner amount is `value_ore` with the incoming sats; for `spend` and `loss` it is `value_ore` with the outgoing sats; `transfer_out`, `transfer_in`, `gift_given` and `admin_cost` give `None`. Round halves up. Handle `admin_cost` with no account: it is no longer looked up among the accounts, it is counted when its own `taxable` flag is set, its sats are summed into a new totals field `admin_cost_sats`, and `admin_cost_ore` becomes `admin_cost_sats × the year-end rate ÷ 10^8` when `deduct_admin_costs` is on and `0` otherwise. Keep every other figure as it is. **Verify:** the golden price case — a buy of 1 000 sats for 10 kr gives `btc_price_ore == 100000000` (1 000 000 kr) — and `report(2024)` still returns every field of §6. ### 32. `export.py` `JOIN markets m ON m.id = t.market_id` becomes `LEFT JOIN` in `transactions_csv`. Rename `_btc()` to `_sats()` and use `rates.group_int`; make `_amount()` use `rates.kroner_whole`. Headings become `Antall inn (sats)`, `Antall ut (sats)`, `Avgift (sats)`, `Antall (sats)` and `Antall (sats)` for the TOT block. Add a `Pris (kr)` column to the transaction block, after `Til konto`, carrying `tax.btc_price_ore(row)`. Change the report line `Forvaltningskostnad (kr)` into `Forvaltningskostnad (sats)` from `admin_cost_sats`, and keep a `Forvaltningskostnad (kr)` line from `admin_cost_ore`. **Verify:** download the CSV for a year with an `admin_cost` row and open it; the row is present, the price column is filled for the trades, and no cell carries a decimal. ### 33. `app.py` Make the account join a `LEFT JOIN markets m ON m.id = t.market_id` in `_load_transaction` and in `transactions_list`, so a row with no account is not dropped. Add `btc_price_ore` to both payloads by calling `tax.btc_price_ore`. Confirm that `transactions_get` builds no candidate lots for `admin_cost`, which step 30 should already have settled. **Verify:** `GET /api/transactions` returns the `admin_cost` row with `market_id: null`, `market_name: null` and `btc_price_ore: null`, and a buy returns the golden price. ### 34. `tests/test_ledger.py` Update the fixtures to whole sats and the renamed lot field. Add: an `admin_cost` transaction consumes nothing and leaves `holdings_at` unchanged; a rebuild after it still produces the same lots. **Verify:** `python3 -m unittest discover -s tests -v` — green. ### 35. `tests/test_tax.py` Update the fixtures and add: an `admin_cost` with `market_id` null and `taxable = 1` lands in `admin_cost_sats` and leaves every account row untouched; `admin_cost_ore` is 0 with the setting off, and the sats converted at the year-end rate with it on; `btc_price_ore` for the golden case (1 000 sats for 10 kr → 1 000 000 kr) and for a sale (sats out, kroner in); `btc_price_ore` is None for `transfer_out` and `admin_cost`. **Verify:** `python3 -m unittest discover -s tests -v` — green. ### 36. `static/app.js` `formatSats(sats)` returns the grouped whole number of sats and nothing else, and its doc comment says so. `formatKroner(ore)` returns whole kroner with spaces and the unit, rounding halves up, with no decimals. `formatOre(ore)` stays exactly as it is and stays exported: it is what fills a form from a stored value. `parseSats(text)` parses whole sats with spaces allowed and returns null for anything carrying a decimal separator. **Verify:** in the browser console, `Skuld.formatSats(1500000)` is `"1 500 000"`, `Skuld.formatKroner(106037489)` is `"1 060 375 kr"`, `Skuld.formatOre(123450)` is `"1 234,50"`, and `Skuld.parseSats("1 500 000")` is `1500000`. ### 37. `static/transactions.html` Add `