Database Types for Exact Blockchain Quantities
Store large blockchain integers and decimal values without silent overflow or floating-point loss, and define typed boundaries for APIs and exports.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Blockchain quantities can exceed familiar machine integer ranges. A database column that works for a small fixture can overflow or round a real token amount.
Choose a representation deliberately
Options include sufficiently wide exact numeric columns, validated decimal strings or binary representations with explicit decoding. Token scale is metadata, not a reason to store an imprecise display float. Define maximum size, sign rules and canonical formatting. Database, application language and JSON boundaries must preserve the same value.
Worked example: a large raw integer
A raw amount larger than the JavaScript safe integer limit is stored exactly in a numeric column. Reading it through a driver that converts it to Number still loses precision. Configure or implement an exact representation through the full path, and test the returned JSON string rather than checking only the database value.
Test every conversion
Include zero, maximum supported values, leading formatting differences and invalid scientific notation where disallowed. Use compatible units before summing. Document export types and avoid downcasting during analytics. A rounded display is acceptable under a declared policy; overwriting the stored exact amount with that display is not.
A practical acceptance test
Round-trip an integer beyond 2^53 through database, driver, application JSON and export. Compare the final canonical value with the original. Test the maximum supported range and an invalid value just outside it. A database assertion alone is insufficient if a driver or serializer later converts the exact quantity into an imprecise Number.
Questions about the topic
Frequently asked questions
Does exact database storage guarantee exact JSON output?
No. Drivers and application conversions can still lose precision.
Should raw quantities use floating-point columns?
Prefer an exact representation appropriate to the supported range.
Standards & technical documentation
