feat(store): Arbitrary-precision amounts — replace i64 stroops with NUMERIC(78,0)

[Emmyt24]

Depends on: #214. Blocks: #221, #223, #224, #225, #227.

Description

Amounts are i64 stroops everywhere — schema (amount_stroops BIGINT CHECK (amount_stroops > 0)),
models (crates/store/src/models.rs), the ingest amount parser
(crates/ingest/src/amount.rs), and API serialisation. This
encodes two Stellar-specific assumptions: 7 decimal places, and values that fit in 64 bits.

Both fail on EVM. ETH and most ERC-20s use 18 decimals; 1 ETH = 10^18 and i64::MAX ≈ 9.22 × 10^18,
so a balance of ~9.3 ETH overflows. Token amounts are uint256, up to ~1.16 × 10^77. An overflow
here does not throw — it silently credits the wrong amount, which is a fund-loss bug.

Introduce an arbitrary-precision Amount type and migrate storage and serialisation to it.

Requirements and context

• Storage: NUMERIC(78,0) — integer base units, no fractional component. Decimals live in the
  token registry (feat(store): ERC-20 token registry #223), never inferred from the value.
• Rust type: rust_decimal is not acceptable (96-bit mantissa). Use sqlx::types::BigDecimal
  (enable the bigdecimal feature) at the storage boundary and U256 in EVM-facing code. Justify
  your choice of the U256 implementation (alloy-primitives, ruint, primitive-types) against
  the MSRV constraint — coordinate with feat(evm-core): secp256k1 keys, BIP-44 derivation, and EIP-55 addresses #217.
• API representation: JSON strings, per AD-3. A uint256 in a JSON number silently loses
  precision in every JavaScript client. This is a breaking API change and must be versioned — see
  feat(api): Multi-chain API surface, OpenAPI, and webhooks #227.
• No floats, ever. Note that format_amount in
  crates/api/src/routes/submit.rs currently round-trips
  through f64. That is tolerable for 7-decimal stroops and not tolerable at 18 decimals.
  Replace it with integer/string formatting.
• The wallet-core and crypto lint walls already deny clippy::cast_possible_truncation and
  cast_sign_loss — extend that posture to any crate handling amounts.
• Security: an unchecked as i64 or a silent saturation is a credit-amount vulnerability.
  Conversions must be fallible and return an error, never truncate.

Suggested execution

Branch: feat/arbitrary-precision-amounts

Implement changes

• Add an Amount newtype in octo-chain wrapping an unsigned big integer, with a documented
  invariant that it is always a non-negative integer count of base units, plus fallible
  TryFrom<i64> / to_i64() conversions for the Stellar path.
• Migration 00NN_numeric_amounts.sql: add amount_base_units NUMERIC(78,0), backfill from
  amount_stroops, add the > 0 check, and keep the old column through one release for rollback.
• Implement Serialize/Deserialize as strings, with a deserializer that rejects JSON numbers
  outright rather than accepting and truncating them.
• Replace format_amount's f64 path with exact integer→decimal-string formatting parameterised
  by decimals.
• Update octo-store models and queries, and octo-ingest's amount parsing.

Test and commit

• Property tests (proptest is already a workspace dependency): round-trip
  Amount → NUMERIC → Amount and Amount → JSON string → Amount for the full uint256 range.
• Explicit boundary cases: 0, 1, i64::MAX, i64::MAX + 1, u64::MAX, 2^256 - 1.
• A regression test asserting that a JSON number amount is rejected, not coerced.
• A test that the exact value 10^18 (1 ETH) survives a full store→API→client round-trip
  bit-identically — this is the case the old i64 schema could not represent.
• Update docs/api.md and docs/openapi.yaml for the string
  representation.

Example commit message

feat(store): arbitrary-precision amounts for EVM compatibility

i64 stroops assume 7 decimals and 64-bit range; ETH is 18 decimals and
ERC-20 amounts are uint256, so ~9.3 ETH would silently overflow.

Amounts move to NUMERIC(78,0) with decimals owned by the token registry,
and cross the API as JSON strings — a uint256 in a JSON number loses
precision in every JS client.

BREAKING CHANGE: amount fields serialise as strings.

Refs #215

Guidelines

Breaking API change: coordinate with #227 on versioning before merge. Call out every remaining
as i64 in the diff and explain why each is safe.

---

[bobo-24]

Hi! I’m a full-stack developer with a strong blockchain background, and I’m confident I can resolve this issue quickly and effectively. I’ll deliver a clean, reliable solution with immediate attention to detail, ensuring it’s completed as soon as possible. Please assign it to me—I’m ready to get started right away.

[Nexha-dev]

Hi, I’d like to take up this issue.

I’ve reviewed the requirements and understand that this is a security-critical change: the current i64 amount representation is tied to Stellar’s 7-decimal model and cannot safely represent EVM values such as 18-decimal ETH or uint256 token amounts. I’d like to implement the arbitrary-precision amount model while preserving existing Stellar behavior and preventing any truncation or precision loss.

My proposed approach would be to:

• Introduce an Amount newtype in octo-chain representing a non-negative integer number of base units, with the invariant explicitly documented.
• Use an arbitrary-precision representation appropriate for the project’s MSRV, and coordinate the U256 implementation choice with the EVM work in feat(evm-core): secp256k1 keys, BIP-44 derivation, and EIP-55 addresses #217.
• Add fallible conversions such as TryFrom<i64> and to_i64() for Stellar-specific paths, ensuring conversions can never silently truncate or saturate.
• Add the amount_base_units NUMERIC(78,0) column through an additive migration, backfill existing amount_stroops, enforce the positive-value constraint, and retain the legacy column for the required rollback period.
• Update store models and queries to use the new representation.
• Update octo-ingest amount parsing so values are handled as integers rather than floating-point numbers.
• Replace the existing f64-based format_amount implementation with exact integer-to-decimal-string formatting parameterised by token decimals.
• Implement API serialization as JSON strings and ensure the deserializer explicitly rejects JSON numeric values rather than coercing them and risking precision loss.
• Extend the existing lint posture around numeric casts to amount-handling code and ensure potentially lossy conversions are always fallible.
• Add property tests covering Amount → NUMERIC → Amount and Amount → JSON string → Amount round trips across the full uint256 range.
• Add explicit boundary tests for 0, 1, i64::MAX, i64::MAX + 1, u64::MAX, and 2^256 - 1.
• Add a regression test confirming JSON numbers are rejected rather than silently coerced.
• Add an end-to-end test proving that 10^18 (1 ETH in wei) survives the store → API → client path bit-for-bit.
• Update docs/api.md and docs/openapi.yaml to document the string representation.
• Audit all remaining i64 amount usages and document why any that remain are safe.
• Coordinate the breaking API representation change with feat(api): Multi-chain API surface, OpenAPI, and webhooks #227 before merge and clearly document the versioning impact.

I’ll be particularly careful around the security invariant here: there should be no as i64, implicit narrowing conversion, floating-point conversion, or saturation that could result in an incorrect credit amount. Any conversion that cannot be represented safely will return an explicit error.

I’m ready to take this issue up.

[grantfox-oss]

🦊 GrantFox — @Nexha-dev has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #215)
2. Your PR will be reviewed by the Octo-Protocol-org maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Nexha-dev's PR #236 was approved and merged by @Emmyt24.

🏆 @Nexha-dev: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,345 total points). Track your full progress on GrantFox.

👏 Great work, @Nexha-dev! Keep contributing to Octo-Protocol-org.