# 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 B3 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 refuses one | | D21 | A fee is entered in sats only; a kroner cost is folded into the amount the owner types | The owner asked for it, and it keeps every leg to one currency with no conversion the app would have to invent | | D22 | A transfer's fee is taken on top at the source, so what is sent is exactly what arrives | The owner requires `INN` on the `transfer_in` to equal `Sendt` on the `transfer_out`; subtracting the fee would also make the fee vanish from the destination's holdings instead of the source's | | D23 | The mirrored lots cover exactly the sent amount, and the cost share of the fee sats leaves the ledger with them | It keeps the destination's price per sat identical to the source's, which is what "inherits the price of the chosen lot" means. Skuld books no gain or loss for a fee | | D24 | A transfer's price comes from its consumed lots (out) and its mirrored lots (in) | Same unit as the price of a buy, both sides of the pair agree, and nothing extra is stored | | D25 | `admin_cost` is in kroner | The owner confirmed it. No account, no lots, and no conversion: the report shows the sum and subtracts it only when `deduct_admin_costs` is on | | D26 | `fee_ore` stays in the schema, always 0 | `CREATE TABLE IF NOT EXISTS` cannot drop a column, and a migration is not worth it for a dead field; no client ever sends it | | D27 | A field with a single currency shows the unit as plain text instead of a selector | The owner asked for it, and a select with one option claims a choice that does not exist | | D28 | A fictional `Bank` account pays the costs, and a `Forvaltningskostnad` is one row on it | The cost must not draw on a real account; one row keeps the list short. Superseded in part by D36 | | D29 | The kroner balance of an account is derived from its legs and never stored | It is a sum over rows that already exist, so nothing can drift | | D30 | A `transfer_out` carries either sats or kroner, never both | One currency per transfer keeps the mirroring rules and the form simple | | D31 | Only kroner can be withdrawn with an empty `Til` | The owner asked for it, and a sats transfer always needs a destination | | D32 | `deduct_admin_costs` stays off by default | The owner confirmed it; the deductibility of the cost is still open as Q2 | | D33 | Kroner move only between an account and the bank, never between two real accounts | The owner asked for it: kroner on an exchange are not a holding to move around, but fiat goes in and out through the bank | | D34 | `Til` is always required, and the bank may be chosen there or as the account of a kroner transfer | It replaces the empty-`Til` withdrawal: nothing leaves the ledger silently, and where the money went is visible as a stored pair | | D35 | A `trade` buy is refused when the kroner do not cover it | The owner asked whether a buy should draw on available kroner; buying with money the account does not hold is the same mistake as selling coins it does not hold, and the remedy is a deposit from the bank | | D36 | A `Forvaltningskostnad` is one `leg_out_ore` on the bank, and it must have the kroner there | The owner asked whether the two equal legs were wrong: they were, once the bank became a real account, because the cost never reduced it and the "in" leg was a movement that never happened | | D37 | No account, the bank included, may go negative | The owner's rule: every payment that would overdraw is refused, and the remedy is to record where the money came from | ## 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 — first round of corrections (steps 27-44) — DONE Sats everywhere, whole kroner in the display, the `Bitcoin pris` figure, `admin_cost` off the accounts, and no fee for `gift_received`. ## Phase B3 — second round of corrections (steps 45-55) Do these before Phase C. The owner has reviewed the app again. These steps change the fee to sats only, change the transfer pair so that what is sent is what arrives, make `Forvaltningskostnad` a kroner cost, and make the form match the owner's field list exactly. ### 45. `validation.py` A fee is sats only. `ORE_FIELDS` loses `fee_ore`, and `validate_transaction` still reads it but only to reject it: a non-blank `fee_ore` gives the error "Avgift må berre førast i sats." on `fee_sats`, and the stored value is always 0. Keep the rule that `gift_received` and `admin_cost` take no fee, and keep the check that a fee is smaller than the amount it belongs to. `admin_cost` is a kroner cost now: `_ALLOWED_LEGS["admin_cost"] = ("leg_out_ore",)`, `_REQUIRED["admin_cost"] = (("leg_out_ore", "Fyll ut kostnaden i kroner."),)`, and `_check_admin_cost` accepts exactly one `leg_out_ore` and rejects `leg_out_sats`. `loss` requires its price: add `("value_ore", "Fyll ut prisen i kroner.")` to `_REQUIRED["loss"]`. **Verify:** an `admin_cost` payload with `leg_out_ore` validates clean, the same payload with `leg_out_sats` gives a Nynorsk error on `leg_out_sats`, a payload with `fee_ore` gives the "berre sats" error, and a `loss` without `value_ore` is rejected. ### 46. `ledger.py` `FEE_ADDS_TO_CONSUMPTION` becomes `("trade", "spend", "transfer_out")` and its comment says that a transfer's fee is taken on top of what is sent. In `create_lots_for`, drop the `fee_ore` arithmetic: the cost of a buy is the kroner that left the account, and the cost of `income` and `gift_received` is `value_ore`. Rewrite `_mirror_transfer`: read `leg_out_sats` from the source `transfer_out` as well as its id, then mirror exactly that many sats across the consumed parts in order, using `_split_capped`. For each part the mirrored cost is the part's proportional share, `_cost_for(part cost, part sats, mirrored sats)`, so the cost per sat is unchanged. The `fee_sats` and `fee_ore` of the `transfer_in` are not read at all. Delete `_split_even`, which nothing else uses. **Verify:** `python3 -m unittest discover -s tests -v`; then, by hand, a transfer of 100 000 sats with a 1 000 sats fee leaves the source 101 000 sats lighter, the destination 100 000 sats richer, and both sides' lots at the same price per sat. ### 47. `tax.py` `btc_price_ore` learns the transfer case: for a `transfer_out` it uses `cost_ore` and `consumed_sats`, for a `transfer_in` it uses `lot_cost_ore` and `lot_sats`, and it still returns None for `gift_given` and `admin_cost`. Remove `fee_ore` from the income and proceeds arithmetic in `report`, since it is always 0 now. `admin_cost` is kroner: sum `leg_out_ore` of the year's taxable `admin_cost` rows into `admin_cost_ore`, drop `admin_cost_sats` from the totals, and subtract the sum from `netto_ore` only when `deduct_admin_costs` is on. Drop `fee_ore` from the `_year_rows` select. **Verify:** `python3 -m unittest discover -s tests -v`; a `transfer_out` and its `transfer_in` report the same `btc_price_ore`, and a transfer with a fee still reports the same price on both sides. ### 48. `app.py` In `_sync_transfer_pair`, `arrived` becomes the sent amount itself, `tx["leg_out_sats"]`, and the generated `transfer_in` is written with `fee_sats` and `fee_ore` of 0 on both the insert and the update path. In `_load_transaction` and `transactions_list`, add the three derived columns `btc_price_ore` needs for a transfer: `COALESCE(SUM(c.sats), 0) AS consumed_sats`, and `COALESCE((SELECT SUM(l.cost_ore_original) FROM lots l WHERE l.origin_tx_id = t.id), 0) AS lot_cost_ore` with the same for `l.sats_original` as `lot_sats`. **Verify:** save a transfer with a fee: `GET /api/transactions` shows the `transfer_out` with `leg_out_sats` 100000 and `fee_sats` 1000, and the `transfer_in` with `leg_in_sats` 100000 and `fee_sats` 0, and both with the same `btc_price_ore`. ### 49. `export.py` Drop the `Avgift (kr)` column and rename `Pris (kr)` to `Bitcoin pris (kr)`. In the report block keep one line, `Forvaltningskostnad (kr)` from `admin_cost_ore`. Add the same three derived columns as step 48 to the transaction query, so the transfer price is filled in. **Verify:** download a year with a transfer and an `admin_cost`; both sides of the transfer carry the same price, the `admin_cost` row is present with its kroner amount, and there is no `Avgift (kr)` column. ### 50. `tests/test_ledger.py` Update the fixtures for the sats-only fee and the new transfer rules, and add: a transfer with a fee leaves the destination with exactly the sent sats and the source with the sent sats plus the fee gone; the destination lots keep the source's cost per sat; the fee's cost share is not mirrored; `holdings_at` after a transfer is source − sent − fee and destination + sent. **Verify:** `python3 -m unittest discover -s tests -v` — green. ### 51. `tests/test_tax.py` Update the fixtures and add: `admin_cost` in kroner lands in `admin_cost_ore` and is subtracted only when the setting is on; a `loss` without a price is rejected by validation; `btc_price_ore` is the same for a `transfer_out` and its `transfer_in`, and is None for `gift_given` and `admin_cost`. **Verify:** `python3 -m unittest discover -s tests -v` — green. ### 52. `static/transaction.html` Give every currency slot a plain-text unit next to its amount: a ``, the same for `leg_out`, `value` and `fee`. Keep the two `