From 7f14ae58caadf1721977b618508dd49e0f0cbbc2 Mon Sep 17 00:00:00 2001 From: sendi0011 Date: Sun, 29 Mar 2026 17:27:08 +0100 Subject: [PATCH] docs(spec-runner): document BigInt.parse() rationale for uint64 muxed IDs Stellar muxed IDs are uint64 (0..2^64-1). Dart's native int is signed 64-bit, so values above 2^63-1 overflow silently. JSON numbers lose precision above 2^53 (JS safe-integer boundary), which is why vectors encode IDs as strings. Added inline comments on both the encode and decode BigInt.parse() call sites explaining the integer limits and why BigInt is required for correct cross-platform interoperability. Closes #188 --- packages/core-dart/test/spec_runner_test.dart | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/packages/core-dart/test/spec_runner_test.dart b/packages/core-dart/test/spec_runner_test.dart index cc1831a8..99c615d6 100644 --- a/packages/core-dart/test/spec_runner_test.dart +++ b/packages/core-dart/test/spec_runner_test.dart @@ -29,6 +29,15 @@ void main() { switch (module) { case 'muxed_encode': final String baseG = input['base_g'].toString(); + // Muxed IDs on the Stellar Network are unsigned 64-bit integers + // (uint64), giving a valid range of 0 to 2^64-1 + // (18446744073709551615). Dart's native int is 64-bit signed, so + // values above 2^63-1 would overflow silently. JSON numbers also + // lose precision for values above 2^53 (JavaScript's safe-integer + // boundary), which is why the spec vectors encode IDs as strings. + // BigInt.parse() is the only correct way to ingest these values: + // it handles the full uint64 range without truncation or silent + // corruption, ensuring cross-platform interoperability. final BigInt id = BigInt.parse(input['id'].toString()); final String result = MuxedAddress.encode(baseG: baseG, id: id); expect(result, expected['mAddress']); @@ -43,6 +52,11 @@ void main() { StellarAddress.parse(input['mAddress'].toString()); expect(address.kind, AddressKind.m); expect(address.baseG, expected['base_g']); + // Same uint64 constraint applies on the decode side: the + // expected ID in the vector is a string to preserve full + // precision. BigInt.parse() guarantees an exact comparison + // against the decoded value, catching any truncation that a + // plain int or double comparison would silently miss. expect(address.muxedId, BigInt.parse(expected['id'].toString())); } break;