fix(facade): exact credits/microcredits conversion

[iamalwaysuncomfortable]

to_microcredits and from_microcredits both went through binary floating point and lost value. This makes both exact.

Stacked on #65 — base is docs/docstring-coverage-and-invite-minting-removal, because both PRs touch the docstrings of these same two facade methods. Merge #65 first; GitHub will retarget this to feat/shield-swap-update automatically.

The bugs

Inbound — silent underpayment. credits * 1_000_000 in float, then int() truncating toward zero:

>>> aleo.to_microcredits(1.005)   # before
1004999                            # 1.005 * 1e6 == 1004999.9999999999

One microcredit lost on a completely ordinary amount, with no error. Sub-microcredit input disappeared entirely — to_microcredits(0.9999999) returned 999999.

Outbound — not representable. from_microcredits returned a float, but microcredits are a u64 and past 2**53 a float cannot hold the integer:

>>> m = 2**64 - 1
>>> int(aleo.from_microcredits(m) * 1_000_000) - m   # before
1

2884 of the first 200_000 microcredit values failed micro -> credits -> micro identity — about 1.4%.

The fix

Both directions compute in Decimal.

Float input is routed through str(), which recovers the shortest representation that round-trips — the literal the caller actually wrote. That is what rescues 1.005, since Decimal(1.005) would faithfully preserve the float's real value of 1.00499999999999989... and stay wrong. str and Decimal input are exact already, so to_microcredits("1.005") is now the precise way to pass an amount that came from text or JSON.

Sub-microcredit precision raises ValueError naming the offending value, with allow_rounding=True to opt back into truncation. Losing value should be an error, not a default.

>>> aleo.to_microcredits(1.005)
1005000
>>> aleo.to_microcredits("1.005")
1005000
>>> aleo.to_microcredits(0.9999999)
ValueError: 0.9999999 credits is 999999.9000000 microcredits — finer than the
chain's smallest unit. Round it yourself, or pass allow_rounding=True to
truncate toward zero.
>>> aleo.to_microcredits(0.9999999, allow_rounding=True)
999999

Breaking change

from_microcredits returns Decimal, not float.

Equality and float() still work, so all three pre-existing assertions pass unchanged, including from_microcredits(1_500_000) == 1.5. What breaks is mixing the result into float arithmetic — from_microcredits(x) * 0.5 raises TypeError, as does json.dumps of the result. Call float(...) deliberately if you want that, accepting the loss. The docstring says so.

This is the deliberate trade for exactness: Decimal is the correct type for money, and a float simply cannot represent the full u64 range.

Scope

Contained, and checked rather than assumed: these are user-facing convenience helpers only. No internal fee or amount path consumes them — the SDK is integer microcredits end to end — and shield-swap never calls them, working in raw base units throughout. So no transaction the SDK builds today was affected; only callers who used the helpers to compute an amount.

Verification

Gate	Result
pytest python/tests -m "not slow" (sdk)	896 passed, 17 skipped (+6 new)
pyright strict (sdk)	0 errors, 0 warnings
pytest (shield-swap)	174 passed — unaffected

The 6 new tests pin exactly what was broken: the 1.005 class across float/str/Decimal, the ValueError and its escape hatch, NaN/inf/garbage rejection, exactness at 2**53 + 1 and u64 max, identity across a 5000-value sweep, and that float comparison still holds.