Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/object_money.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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
2smallest unit, and the denomination declares what that unit is.
3
4This is the generalization of the "money is integer cents" rule that has
5governed this codebase from the start (plan/vocabulary/00-doctrine-and-
6contract.md): cents were always *USD minor units*. A business does not hold
7only dollars -- it holds bank balances, bitcoin, stablecoins, a box of
8physical cash, gift cards, maybe a weight of metal -- and those are
9denominated 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
18system (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
20storing every amount in one fixed Decimal(28,8) column. A schema that lets
21a denomination declare 18 decimals but can only hold 8 will silently
22truncate the first asset that needs them, and meanwhile it carries six
23meaningless digits on every dollar, which is how rounding dust gets into a
24ledger. Storing the integer count of the smallest unit has neither problem:
25exact by construction, no scale to disagree about, no ceiling.
26
27Floats never appear here. Decimal is used only at the edges, to convert
28human text to and from integers.
29"""
30
31from __future__ import annotations
32
33from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
34from pathlib import Path
35from typing import Any
36
37import object_records
38from object_versions import DEFAULT_DATA_DIR
39
40DENOMINATIONS_COLLECTION = "denominations"
41
42DEFAULT_CODE = "USD"
43DEFAULT_SCALE = 2
44MAX_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
57class MoneyError(ValueError):
58 """An amount that cannot be represented exactly in its denomination."""
59
60
61def 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
77def 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
96def 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
118def 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
134def 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
143def 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
165def 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
195RATES_COLLECTION = "rates"
196
197KIND_SPOT = "spot"
198KIND_CLOSE = "close"
199KIND_AVERAGE = "average"
200
201
202class RateNotFound(LookupError):
203 """No usable rate at or before the moment asked about."""
204
205
206def _norm(code: str) -> str:
207 return str(code or "").strip().upper()
208
209
210def 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
226def 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
273def 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
300def 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.
335ASSURANCE_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
352def 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
365def 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