BigInt micro-credit math in order-selector (audit C1)

[brawlaphant]

Closes part of audit C1-HIGH (the order-selector hot path). pool.ts and evm-wallet.ts have similar issues but wider blast radius — happy to take those as separate PRs.

Problem

Audit (AUDIT.md) flagged three concrete failure modes in the greedy fill loop:

Site	Issue
order-selector.ts:124	parseFloat(order.quantity) loses precision on strings with >15 significant digits
order-selector.ts:127	Math.min(remaining, available) then remaining -= take — float subtraction accumulates rounding error across iterations
order-selector.ts:131	BigInt(Math.ceil(take * 1_000_000)) — 0.1 * 1_000_000 = 100000.00000000001, then Math.ceil rounds the spurious digit UP and over-charges by 1 micro

"Over many orders, the greedy fill loop in order-selector accumulates rounding errors. For small quantities, users might overpay or underpay by fractions of a micro-unit."

What this PR does

Rewrites the loop to use bigint micro-credits (1 credit = 1_000_000 micro) end-to-end. The single float touch is numberToMicro at the public entry point, where a JS number from the caller is rounded to the nearest micro. That's the unavoidable cost of accepting quantity: number from MCP/REST callers; everywhere else is exact.

Three small pure helpers (exported under __orderSelectorInternals for direct testing):

• parseQuantityToMicro(decimal: string): bigint — string "10.5" → bigint 10_500_000n
• formatMicroToQuantity(micro: bigint): string — bigint → fixed-precision string
• numberToMicro(quantity: number): bigint — Math.round(quantity * 1_000_000), error-bounded

Cost rounding now uses ceiling division ((a + scale - 1) / scale) so any sub-micro fraction is charged to the buyer rather than absorbed by the seller — matches how on-chain MsgBuyDirect settles.

Tests

14 new cases. Highlight: a regression test that sums 10 × 0.1 credits and asserts it equals exactly 1.0 (with parseFloat / Math.ceil, the previous code drifted by 1 micro).

✓ src/__tests__/order-selector.test.ts (14 tests)
  ✓ quantity micro conversion (6)
    ✓ parses integer quantities
    ✓ parses fractional quantities exactly
    ✓ truncates beyond 6 decimal places (sub-micro is not representable)
    ✓ rejects malformed input
    ✓ formatMicroToQuantity round-trips
    ✓ numberToMicro rounds half to nearest
  ✓ selectBestOrders greedy fill (audit C1) (7)
    ✓ fills exactly when supply matches request
    ✓ walks across multiple orders cheapest-first
    ✓ flags insufficient supply when total available < request
    ✓ skips orders with malformed quantity rather than blowing up
    ✓ does not accumulate float error across the greedy fill (audit C1)
    ✓ computes exact cost with fractional take and high-precision price
    ✓ rounds cost UP so the buyer covers the sub-micro remainder

Full suite: 63/63 passing (49 prior + 14 new).

Test plan

• npm run typecheck — clean
• npm test — 63/63 passing
• npm run build — clean
• Reviewer: confirm ceiling-division on cost matches your accounting expectation. Audit said "users might overpay or underpay" — I picked overpay-by-at-most-1-micro because it matches on-chain settlement. Easy to flip to floor or banker's rounding if you prefer the seller absorb sub-micro.
• Reviewer: spot-check that no caller of selectBestOrders was relying on the old parseFloat-style total — all callers I traced (retirement.ts, retire-subscriber.ts) consume totalCostMicro as bigint and totalQuantity as a string, both of which keep working.

Out of scope (audit C1 follow-ups)

• pool.ts:324 parseFloat(finalSelection.totalQuantity) for display
• pool.ts:388 sub.amount_cents / totalRevenueCents for attribution fractions
• retirement.ts:169 parseFloat(selection.totalQuantity) for display
• evm-wallet.ts:110 Math.round(amountUsdc * 10 ** decimals)

Each of those can be a focused PR. The order-selector site was the one the audit flagged as highest-risk because of the multi-iteration accumulation.

Refs: AUDIT.md C1-HIGH

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request replaces floating-point arithmetic with BigInt micro-credits in the order selection logic to prevent rounding errors and ensure exact calculations. Key changes include the introduction of helper functions for parsing, formatting, and converting quantities to micro-credits, as well as updating the greedy fill loop to use these helpers. Feedback focuses on refining the insufficientSupply check to be more precise now that BigInt is used, improving the robustness of the decimal parsing regex to handle common input formats like leading or trailing dots, and addressing a behavioral inconsistency between string truncation and numeric rounding when handling sub-micro quantities.

[gemini-code-assist]

The condition remainingMicro > 1n allows the selection to be up to 1 micro-credit short without flagging insufficientSupply. While this might have been a workaround for floating-point inaccuracies in the previous implementation, it is no longer necessary with BigInt. If the requested quantity cannot be fully met (even by 1 micro), insufficientSupply should be true to ensure the caller is aware of the shortfall.

Suggested change

	if (remainingMicro > 1n) {
	insufficientSupply = true;
	}
	if (remainingMicro > 0n) {
	insufficientSupply = true;
	}

[gemini-code-assist]

The regex /^-?\d+(\.\d+)?$/ is more restrictive than standard decimal parsing as it rejects strings with leading dots (e.g., .5) or trailing dots (e.g., 1.). Consider using a more inclusive regex to match common user input formats. Note that if you update this, you should also handle empty whole parts in the BigInt conversion on line 35.

Suggested change

	if (!/^-?\d+(\.\d+)?$/.test(trimmed)) {
	if (!/^-?(\d+(\.\d*)?|\.\d+)$/.test(trimmed)) {

[gemini-code-assist]

There is a behavioral inconsistency between parseQuantityToMicro and numberToMicro. parseQuantityToMicro truncates digits beyond the 6th decimal place, while numberToMicro rounds to the nearest micro-credit using Math.round. For example, the string "0.0000006" parses to 0n, but the number 0.0000006 converts to 1n. It is recommended to use a consistent strategy for both to avoid unexpected discrepancies depending on the input type.

[gemini-code-assist]

If the regex on line 28 is updated to allow leading dots (like .5), the whole variable will be an empty string. BigInt("") throws a SyntaxError, so it is safer to provide a fallback to "0".

Suggested change

	const micro = BigInt(whole) * QUANTITY_SCALE + BigInt(fracPadded || "0");
	const micro = BigInt(whole || "0") * QUANTITY_SCALE + BigInt(fracPadded || "0");