[HARD][FX] Build a versioned exchange-rate quote and conversion integrity service

[Obiajulu-gif]

Overview

Implement a centralized exchange-rate service for any workflow that stores or displays originalCurrency, exchangeRate, converted NGN values, or future multi-currency funding and settlement data.

Problem

The transaction model already allows original currency and exchange-rate fields, but there is no authoritative quote lifecycle. Accepting raw client rates or recalculating later can create inconsistent investment values, misleading reports, stale conversions, and reconciliation differences.

Scope

• Define typed currency and money primitives with ISO currency validation.
• Create provider adapter interfaces plus deterministic mock/static adapters for contributors.
• Store immutable quote snapshots containing base/quote currency, rate, provider, provider timestamp, fetched time, expiry, markup/spread, and version.
• Add quote creation, validation, locking, consumption, and expiry rules.
• Reject client-supplied rates for balance-changing operations.
• Define maximum quote age, supported pairs, deviation thresholds, provider fallback, and circuit-breaker behavior.
• Ensure converted major/minor values use deterministic rounding.
• Link each converted transaction to the exact quote snapshot used.
• Add admin configuration with audit history; do not permit retroactive edits to consumed quotes.
• Add migration/check tooling for legacy transaction records with exchange-rate data.

Integrity requirements

• A quote can be consumed only for its intended pair, direction, amount policy, and validity window.
• Provider fallback cannot silently accept a materially deviating rate.
• Reports must distinguish booked historical values from current indicative values.
• Reconciliation must use the booked quote snapshot, not the latest rate.
• Unsupported/zero/negative/non-finite rates are rejected.

Test requirements

• fresh and expired quotes
• direct and inverse currency pairs
• provider timeout/fallback
• deviation threshold breach
• deterministic minor-unit rounding
• concurrent consumption
• duplicate idempotency key
• historical reporting after rates change
• migration of valid and ambiguous legacy data

Acceptance criteria

• All conversion logic uses one server-side quote service.
• Consumed quotes are immutable and linked to transactions.
• Stale or materially deviating rates are rejected safely.
• Historical booked values remain reproducible.
• Mock adapters allow offline tests.
• Configuration, migration, and operational behavior are documented.
• Lint, typecheck, tests, and build pass.

Difficulty

Hard

[BigDella]

i will love to work on this issue, i have gone through the requirement and i understood it

[grantfox-oss]

🦊 GrantFox — @BigDella has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #109)
2. Your PR will be reviewed by the Chainmove maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

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

@BigDella's PR #120 was approved and merged by @Obiajulu-gif.

🏆 @BigDella: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (118 total points). Track your full progress on GrantFox.

👏 Great work, @BigDella! Keep contributing to Chainmove.