askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
object_money.py · 15.4 KB · 374 lines
| 1 | """Money representation: an amount is an integer in its denomination's |
| 2 | smallest unit, and the denomination declares what that unit is. |
| 3 | |
| 4 | This is the generalization of the "money is integer cents" rule that has |
| 5 | governed this codebase from the start (plan/vocabulary/00-doctrine-and- |
| 6 | contract.md): cents were always *USD minor units*. A business does not hold |
| 7 | only dollars -- it holds bank balances, bitcoin, stablecoins, a box of |
| 8 | physical cash, gift cards, maybe a weight of metal -- and those are |
| 9 | denominated differently, divided differently, and custodied differently |
| 10 | (plan/value-accounts-and-denominations-spec.md). |
| 11 | |
| 12 | USD scale 2 150000 minor = 1,500.00 |
| 13 | JPY scale 0 1500 minor = 1,500 (no minor unit at all) |
| 14 | BTC scale 8 5000000 minor = 0.05 (satoshis) |
| 15 | ETH scale 18 (Python ints are unbounded) |
| 16 | |
| 17 | **Why integer-minor rather than a fixed-scale decimal.** The predecessor |
| 18 | system (private q9 audit, not part of this repo) declared a per-currency |
| 19 | `decimal_places` -- "2 for USD, 0 for JPY, 8 for BTC, 4 for gold" -- while |
| 20 | storing every amount in one fixed Decimal(28,8) column. A schema that lets |
| 21 | a denomination declare 18 decimals but can only hold 8 will silently |
| 22 | truncate the first asset that needs them, and meanwhile it carries six |
| 23 | meaningless digits on every dollar, which is how rounding dust gets into a |
| 24 | ledger. Storing the integer count of the smallest unit has neither problem: |
| 25 | exact by construction, no scale to disagree about, no ceiling. |
| 26 | |
| 27 | Floats never appear here. Decimal is used only at the edges, to convert |
| 28 | human text to and from integers. |
| 29 | """ |
| 30 | |
| 31 | from __future__ import annotations |
| 32 | |
| 33 | from decimal import Decimal, InvalidOperation, ROUND_HALF_UP |
| 34 | from pathlib import Path |
| 35 | from typing import Any |
| 36 | |
| 37 | import object_records |
| 38 | from object_versions import DEFAULT_DATA_DIR |
| 39 | |
| 40 | DENOMINATIONS_COLLECTION = "denominations" |
| 41 | |
| 42 | DEFAULT_CODE = "USD" |
| 43 | DEFAULT_SCALE = 2 |
| 44 | MAX_SCALE = 30 # ETH needs 18; the cap only rejects nonsense |
| 45 | |
| 46 | # Fallbacks for the common denominations so formatting still works before |
| 47 | # the collection is installed or seeded. The COLLECTION is authoritative -- |
| 48 | # these exist so a fresh install renders sanely, not as a price table. |
| 49 | _FALLBACK_SCALES = { |
| 50 | "USD": 2, "EUR": 2, "GBP": 2, "CAD": 2, "AUD": 2, "CHF": 2, |
| 51 | "JPY": 0, "KRW": 0, |
| 52 | "BTC": 8, "ETH": 18, "USDC": 6, "USDT": 6, |
| 53 | "XAU": 4, "XAG": 4, |
| 54 | } |
| 55 | |
| 56 | |
| 57 | class MoneyError(ValueError): |
| 58 | """An amount that cannot be represented exactly in its denomination.""" |
| 59 | |
| 60 | |
| 61 | def denomination(code: str, *, base_dir: Path | str = DEFAULT_DATA_DIR) -> dict | None: |
| 62 | """The denomination record for a code, or None.""" |
| 63 | wanted = str(code or "").strip().upper() |
| 64 | if not wanted: |
| 65 | return None |
| 66 | try: |
| 67 | rows = object_records.read_collection_records( |
| 68 | DENOMINATIONS_COLLECTION, base_dir=base_dir) |
| 69 | except Exception: |
| 70 | return None |
| 71 | for row in rows: |
| 72 | if str(row.get("code") or "").strip().upper() == wanted: |
| 73 | return row |
| 74 | return None |
| 75 | |
| 76 | |
| 77 | def scale_for(code: str, *, base_dir: Path | str = DEFAULT_DATA_DIR) -> int: |
| 78 | """How many decimal places this denomination divides into. |
| 79 | |
| 80 | Reads the denominations collection, falls back to the well-known table, |
| 81 | and finally to 2. Never raises: formatting an unknown code as if it were |
| 82 | dollars is a display inconvenience, while an exception here would take |
| 83 | down any page that shows an amount. |
| 84 | """ |
| 85 | row = denomination(code, base_dir=base_dir) |
| 86 | if row is not None: |
| 87 | try: |
| 88 | value = int(str(row.get("scale")).strip()) |
| 89 | if 0 <= value <= MAX_SCALE: |
| 90 | return value |
| 91 | except (TypeError, ValueError): |
| 92 | pass |
| 93 | return _FALLBACK_SCALES.get(str(code or "").strip().upper(), DEFAULT_SCALE) |
| 94 | |
| 95 | |
| 96 | def to_minor(amount: Any, scale: int) -> int: |
| 97 | """Human amount ("1,500.00", Decimal("0.05")) -> integer minor units. |
| 98 | |
| 99 | Refuses to round: 0.005 USD is not two decimal places, and quietly |
| 100 | turning it into a cent is how a half-cent-per-row error becomes a real |
| 101 | number at scale. Callers that genuinely want rounding must say so with |
| 102 | quantize_minor(). |
| 103 | """ |
| 104 | text = str(amount if amount is not None else "").strip().replace(",", "") |
| 105 | if not text: |
| 106 | return 0 |
| 107 | try: |
| 108 | value = Decimal(text) |
| 109 | except InvalidOperation as exc: |
| 110 | raise MoneyError(f"Not a number: {amount!r}") from exc |
| 111 | shifted = value.scaleb(int(scale)) |
| 112 | if shifted != shifted.to_integral_value(): |
| 113 | raise MoneyError( |
| 114 | f"{amount} has more precision than a {scale}-decimal denomination can hold") |
| 115 | return int(shifted) |
| 116 | |
| 117 | |
| 118 | def quantize_minor(amount: Any, scale: int, *, rounding=ROUND_HALF_UP) -> int: |
| 119 | """Like to_minor, but rounds deliberately (a rate calculation, a split). |
| 120 | |
| 121 | Separate from to_minor on purpose: rounding money should be a decision |
| 122 | someone made in the code, not something the parser does behind them. |
| 123 | """ |
| 124 | text = str(amount if amount is not None else "").strip().replace(",", "") |
| 125 | if not text: |
| 126 | return 0 |
| 127 | try: |
| 128 | value = Decimal(text) |
| 129 | except InvalidOperation as exc: |
| 130 | raise MoneyError(f"Not a number: {amount!r}") from exc |
| 131 | return int(value.scaleb(int(scale)).to_integral_value(rounding=rounding)) |
| 132 | |
| 133 | |
| 134 | def from_minor(amount_minor: Any, scale: int) -> Decimal: |
| 135 | """Integer minor units -> exact Decimal in whole units.""" |
| 136 | try: |
| 137 | value = int(str(amount_minor).strip() or 0) |
| 138 | except (TypeError, ValueError): |
| 139 | return Decimal(0) |
| 140 | return Decimal(value).scaleb(-int(scale)) |
| 141 | |
| 142 | |
| 143 | def format_amount(amount_minor: Any, code: str = DEFAULT_CODE, *, |
| 144 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 145 | with_code: bool = True, group: bool = True) -> str: |
| 146 | """Render minor units for a human: 150000 USD -> "1,500.00 USD". |
| 147 | |
| 148 | Trailing zeros are kept to the denomination's full scale, because an |
| 149 | amount displayed as "0.05" when the unit divides into eight places |
| 150 | hides whether the rest is zero or merely unshown -- and for assets where |
| 151 | the small digits are real money, that ambiguity matters. |
| 152 | """ |
| 153 | scale = scale_for(code, base_dir=base_dir) |
| 154 | value = from_minor(amount_minor, scale) |
| 155 | text = f"{value:,.{scale}f}" if group else f"{value:.{scale}f}" |
| 156 | row = denomination(code, base_dir=base_dir) |
| 157 | symbol = str((row or {}).get("symbol") or "").strip() |
| 158 | if symbol: |
| 159 | text = f"{symbol}{text}" |
| 160 | if with_code and str(code or "").strip(): |
| 161 | text = f"{text} {str(code).strip().upper()}" |
| 162 | return text |
| 163 | |
| 164 | |
| 165 | def parse_amount(text: Any, code: str = DEFAULT_CODE, *, |
| 166 | base_dir: Path | str = DEFAULT_DATA_DIR) -> int: |
| 167 | """Human text -> integer minor units, using the denomination's scale.""" |
| 168 | cleaned = str(text if text is not None else "").strip() |
| 169 | for token in (str(code or "").strip().upper(), str(code or "").strip()): |
| 170 | if token and cleaned.upper().endswith(token.upper()): |
| 171 | cleaned = cleaned[: -len(token)].strip() |
| 172 | break |
| 173 | row = denomination(code, base_dir=base_dir) |
| 174 | symbol = str((row or {}).get("symbol") or "").strip() |
| 175 | if symbol and cleaned.startswith(symbol): |
| 176 | cleaned = cleaned[len(symbol):].strip() |
| 177 | return to_minor(cleaned, scale_for(code, base_dir=base_dir)) |
| 178 | |
| 179 | |
| 180 | # --- conversion ------------------------------------------------------------- |
| 181 | # |
| 182 | # Two rules govern everything below, and both are the kind that only look |
| 183 | # pedantic until an auditor asks: |
| 184 | # |
| 185 | # 1. **Never look forward.** A rate dated after the moment being valued may |
| 186 | # never be used. Valuing yesterday's transaction with today's price is |
| 187 | # time travel; it silently restates history and is a classic audit |
| 188 | # finding. A lookup returns the newest rate at-or-before the moment, or |
| 189 | # nothing at all. |
| 190 | # 2. **The rate is an input; the result is money.** Rates are measurements |
| 191 | # with significant figures, so they are stored as exact decimal strings. |
| 192 | # The converted amount is a count of minor units, so it is an integer, |
| 193 | # and the rounding that produces it is stated rather than inherited. |
| 194 | |
| 195 | RATES_COLLECTION = "rates" |
| 196 | |
| 197 | KIND_SPOT = "spot" |
| 198 | KIND_CLOSE = "close" |
| 199 | KIND_AVERAGE = "average" |
| 200 | |
| 201 | |
| 202 | class RateNotFound(LookupError): |
| 203 | """No usable rate at or before the moment asked about.""" |
| 204 | |
| 205 | |
| 206 | def _norm(code: str) -> str: |
| 207 | return str(code or "").strip().upper() |
| 208 | |
| 209 | |
| 210 | def rate_records(base_code: str, quote_code: str, *, |
| 211 | base_dir: Path | str = DEFAULT_DATA_DIR) -> list[dict]: |
| 212 | """Every stored rate for a pair, newest `as_of` first.""" |
| 213 | want_base, want_quote = _norm(base_code), _norm(quote_code) |
| 214 | try: |
| 215 | rows = object_records.read_collection_records(RATES_COLLECTION, base_dir=base_dir) |
| 216 | except Exception: |
| 217 | return [] |
| 218 | matches = [r for r in rows |
| 219 | if _norm(r.get("base_code")) == want_base |
| 220 | and _norm(r.get("quote_code")) == want_quote] |
| 221 | matches.sort(key=lambda r: (str(r.get("as_of") or ""), str(r.get("fetched_at") or "")), |
| 222 | reverse=True) |
| 223 | return matches |
| 224 | |
| 225 | |
| 226 | def find_rate(base_code: str, quote_code: str, *, |
| 227 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 228 | as_of: str = "", kind: str = "", source: str = "", |
| 229 | allow_inverse: bool = True) -> dict | None: |
| 230 | """The rate to use for a pair at a moment, or None. |
| 231 | |
| 232 | Returns the newest rate dated at or before `as_of` (all of them when |
| 233 | `as_of` is blank), optionally narrowed to a kind or a source. When the |
| 234 | pair is only stored the other way round, the inverse is derived and |
| 235 | marked `inverted` so a caller can see that the number was computed |
| 236 | rather than quoted -- inversion loses precision at the far end of a |
| 237 | ratio, and pretending otherwise would hide it. |
| 238 | """ |
| 239 | if _norm(base_code) == _norm(quote_code): |
| 240 | return {"base_code": _norm(base_code), "quote_code": _norm(quote_code), |
| 241 | "rate": "1", "as_of": as_of, "kind": kind or KIND_SPOT, |
| 242 | "source": "identity", "inverted": False} |
| 243 | |
| 244 | def _pick(rows): |
| 245 | for row in rows: |
| 246 | if kind and str(row.get("kind") or KIND_SPOT).strip().lower() != kind: |
| 247 | continue |
| 248 | if source and str(row.get("source") or "").strip().lower() != source.lower(): |
| 249 | continue |
| 250 | if as_of and str(row.get("as_of") or "") > as_of: |
| 251 | continue # never look forward |
| 252 | try: |
| 253 | if Decimal(str(row.get("rate") or "0")) <= 0: |
| 254 | continue # a non-positive rate is data corruption |
| 255 | except InvalidOperation: |
| 256 | continue |
| 257 | return row |
| 258 | return None |
| 259 | |
| 260 | direct = _pick(rate_records(base_code, quote_code, base_dir=base_dir)) |
| 261 | if direct is not None: |
| 262 | return {**direct, "inverted": False} |
| 263 | if not allow_inverse: |
| 264 | return None |
| 265 | reverse = _pick(rate_records(quote_code, base_code, base_dir=base_dir)) |
| 266 | if reverse is None: |
| 267 | return None |
| 268 | inverse = Decimal(1) / Decimal(str(reverse["rate"])) |
| 269 | return {**reverse, "base_code": _norm(base_code), "quote_code": _norm(quote_code), |
| 270 | "rate": str(inverse), "inverted": True} |
| 271 | |
| 272 | |
| 273 | def convert(amount_minor: Any, from_code: str, to_code: str, rate: Any, *, |
| 274 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 275 | rounding=ROUND_HALF_UP) -> int: |
| 276 | """Convert minor units of one denomination into minor units of another. |
| 277 | |
| 278 | `rate` is how many `to_code` units one `from_code` unit is worth. The |
| 279 | caller passes the rate explicitly — usually the one it is about to STAMP |
| 280 | onto the record (docs/logic-decisions.md #1) — because a conversion that |
| 281 | silently looked up its own rate would be re-derivable later, and a |
| 282 | re-derivable conversion is one that can change after the fact. |
| 283 | |
| 284 | Rounding happens once, at the end, at the target's scale: converting |
| 285 | then rounding per line is how a total stops matching the sum of its |
| 286 | parts. |
| 287 | """ |
| 288 | from_scale = scale_for(from_code, base_dir=base_dir) |
| 289 | to_scale = scale_for(to_code, base_dir=base_dir) |
| 290 | try: |
| 291 | multiplier = Decimal(str(rate)) |
| 292 | except InvalidOperation as exc: |
| 293 | raise MoneyError(f"Not a rate: {rate!r}") from exc |
| 294 | if multiplier <= 0: |
| 295 | raise MoneyError(f"A conversion rate must be positive, got {rate!r}") |
| 296 | whole = from_minor(amount_minor, from_scale) |
| 297 | return int((whole * multiplier).scaleb(to_scale).to_integral_value(rounding=rounding)) |
| 298 | |
| 299 | |
| 300 | def convert_at(amount_minor: Any, from_code: str, to_code: str, *, |
| 301 | base_dir: Path | str = DEFAULT_DATA_DIR, as_of: str = "", |
| 302 | kind: str = "", source: str = "") -> dict: |
| 303 | """Convert using the stored rate that applies at `as_of`. |
| 304 | |
| 305 | Returns {"amount_minor", "rate", "rate_id", "as_of", "source", |
| 306 | "inverted"} — the rate comes back with the result precisely so the |
| 307 | caller can stamp it onto whatever it writes. Raises RateNotFound rather |
| 308 | than guessing: a conversion with no rate behind it is a number nobody |
| 309 | can defend later. |
| 310 | """ |
| 311 | found = find_rate(from_code, to_code, base_dir=base_dir, as_of=as_of, |
| 312 | kind=kind, source=source) |
| 313 | if found is None: |
| 314 | raise RateNotFound( |
| 315 | f"No {from_code}/{to_code} rate on or before {as_of or 'now'}" |
| 316 | + (f" from {source}" if source else "")) |
| 317 | return { |
| 318 | "amount_minor": convert(amount_minor, from_code, to_code, found["rate"], |
| 319 | base_dir=base_dir), |
| 320 | "rate": str(found["rate"]), |
| 321 | "rate_id": found.get("id", ""), |
| 322 | "as_of": found.get("as_of", ""), |
| 323 | "source": found.get("source", ""), |
| 324 | "inverted": bool(found.get("inverted")), |
| 325 | } |
| 326 | |
| 327 | |
| 328 | # --- assurance -------------------------------------------------------------- |
| 329 | |
| 330 | # How much a reconciliation of an account is actually worth, by the class of |
| 331 | # evidence behind it. Doctrine #8 says the control is that evidence was |
| 332 | # authored by someone with no stake in our numbers -- which means these are |
| 333 | # NOT equivalent, and a system that renders them identically is quietly |
| 334 | # telling its operator a comfortable lie. |
| 335 | ASSURANCE_BY_VERIFICATION = { |
| 336 | # Anyone can verify it, no institution need be trusted, history is |
| 337 | # cryptographically ordered. Stronger evidence than a bank statement. |
| 338 | "chain_query": "strong", |
| 339 | # An independent third party attests -- but you trust their copy, and |
| 340 | # they can restate it. |
| 341 | "statement_import": "strong", |
| 342 | # The issuer states a number, usually with no line-item history to tie |
| 343 | # out against. |
| 344 | "issuer_balance": "medium", |
| 345 | # Self-certification: the person counting the till is usually the person |
| 346 | # who could take from it. Witnessed counts are why this can be lifted. |
| 347 | "physical_count": "weak", |
| 348 | "none": "none", |
| 349 | } |
| 350 | |
| 351 | |
| 352 | def assurance_for(verification: str, *, witnessed: bool = False) -> str: |
| 353 | """The evidence class a verification method actually provides. |
| 354 | |
| 355 | `witnessed` lifts a physical count out of self-certification: a second |
| 356 | person attesting is the oldest control there is against the count and |
| 357 | the custody being the same pair of hands. |
| 358 | """ |
| 359 | level = ASSURANCE_BY_VERIFICATION.get(str(verification or "").strip(), "none") |
| 360 | if level == "weak" and witnessed: |
| 361 | return "medium" |
| 362 | return level |
| 363 | |
| 364 | |
| 365 | def same_denomination(*codes: str) -> bool: |
| 366 | """True when every code given is the same denomination. |
| 367 | |
| 368 | Amounts in different denominations must never be added -- a sum of |
| 369 | dollars and satoshis is not a number, it is a bug. Callers that need to |
| 370 | combine them convert through a stamped rate first (the rate at the |
| 371 | moment of the transaction, never today's -- docs/logic-decisions.md #1). |
| 372 | """ |
| 373 | seen = {str(c or "").strip().upper() for c in codes if str(c or "").strip()} |
| 374 | return len(seen) <= 1 |