[olubukolatanko209-doc]

Summary

Closes #1512

Replaces all floating-point USDC arithmetic in settlement, invoicing and usage tracking with exact bigint contract units (1 USDC = 10,000,000 units). This guarantees that payout amount == Σ event amounts == Σ invoice line items, to the stroop, for any set of events.

---

Problem

RevenueSettlementService summed e.amountUsdc floats; convertUsdcToStroops used Math.round(... + Number.EPSILON); InvoiceService totalled with sum + Number(item.amount). With many micro-charges these sums drift, and amounts above 2^53 stroops lose precision entirely.

Regression proof: 10,000 charges of 0.0000001 USDC as floats gives 0.0010000000000000002 drift. As bigint units (1n each): exactly 10000n. Test plan row 1 covers this.

---

Changes

New shared library — src/lib/usdcUnits.ts

Function	Direction	Used in
parseUsdcToUnits(str)	decimal string → bigint	SQL read, priceUsdc ingest
formatUnitsToUsdc(units)	bigint → minimal decimal	SQL write
formatUnitsToUsdcFixed(units)	bigint → 7-decimal string	API / webhook

Domain types changed

• UsageEvent.amountUsdc: number → bigint
• Settlement.amount: number → bigint
• RevenueSummary fields: number → bigint
• new_api_call webhook amountUsdc: number → string (external boundary)

Service files

File	Change
usageStore.ts	bigint sums, parseUsdcToUnits on SQL read, formatUnitsToUsdc on write
settlementStore.ts	mapSettlementRow parses string→bigint; create writes decimal string
sorobanSettlement.ts	removed convertUsdcToStroops; distribute(bigint); i128 = String(units)
revenueSettlementService.ts	bigint reduce sum; minPayout via parseUsdcToUnits; emit formatUnitsToUsdcFixed
InvoiceService.ts	SUM::text cast + parseUsdcToUnits; insert formatUnitsToUsdc; webhook fixed
billing.ts	delegates helpers to usdcUnits

Boundary consumers

• proxyRoutes.ts / gatewayRoutes.ts: parseUsdcToUnits(priceUsdc.toFixed(7)) at ingest
• developerRoutes.ts: bigint sums; Number(units) / 10_000_000 for JSON (OpenAPI type: number unchanged)

Lint guard

eslint.config.js adds no-restricted-syntax banning parseFloat, Number( and .toFixed( in the five USDC-sensitive service files. Any reintroduction is a build-time error.

---

Test plan coverage

#	Scenario	Status
1	10,000 events of 0.0000001 → payout exactly 10000 units	✅ new test
2	fast-check property: Σ units == formatted total parsed back	✅ usdcUnits.test.ts
3	Payout amount passed to client is bigint == Σ claimed rows	✅ new test
4	minPayout boundary equal to total → payout fires	✅ new test
5	Invoice with 3 line items → total is exact sum	✅ InvoiceService.test.ts
6	Amount above 2^53 units → exact	✅ new test
7	settlement_completed webhook amount is decimal string	✅ new test
8	Lint guard flags reintroduced parseFloat	✅ eslint rule

---

Files changed

33 files changed, 879 insertions(+), 415 deletions(-)

[drips-wave]

@olubukolatanko209-doc Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits