Skip to content

docs(spec-runner): document BigInt.parse() rationale for uint64 muxed…#202

Merged
codeZe-us merged 1 commit intoBoxkit-Labs:mainfrom
Sendi0011:docs/spec-runner-bigint-logic-188
Mar 29, 2026
Merged

docs(spec-runner): document BigInt.parse() rationale for uint64 muxed…#202
codeZe-us merged 1 commit intoBoxkit-Labs:mainfrom
Sendi0011:docs/spec-runner-bigint-logic-188

Conversation

@Sendi0011
Copy link
Copy Markdown
Contributor


Title: docs(spec-runner): document BigInt.parse() rationale for uint64 muxed IDs

Body:

Closes #188

## What changed
Added inline comments in `packages/core-dart/test/spec_runner_test.dart`
at both BigInt.parse() call sites inside the spec vector loop (muxed_encode
and muxed_decode cases).

## Why
Stellar muxed IDs are unsigned 64-bit integers (uint64), valid range
0..2^64-1 (18446744073709551615). Two silent failure modes exist without BigInt:

- Dart's native `int` is signed 64-bit — values above 2^63-1 overflow silently.
- JSON number parsing loses precision 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 across the full
uint64 range without truncation or corruption, which is critical for
cross-platform interoperability.

## Testing
No logic changed — documentation only. Existing spec runner tests continue
to pass unchanged.

… 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 Boxkit-Labs#188
@drips-wave
Copy link
Copy Markdown

drips-wave bot commented Mar 29, 2026

@Sendi0011 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

@codeZe-us codeZe-us self-requested a review March 29, 2026 17:01
@codeZe-us codeZe-us merged commit c667960 into Boxkit-Labs:main Mar 29, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants