feat: add multi-provider FX infrastructure and contract stability improvements

[yours-anjikon]

Summary

This PR strengthens PayD's financial infrastructure by improving exchange-rate reliability in the backend and enhancing long-term maintainability of the Soroban contract layer.

The work combines:

• Multi-provider real-time FX rate support
• Improved provider failover and error handling
• Contract maintenance and stability updates
• Additional testing and documentation improvements

Closes #695

Closes #773

---

Issue #695 — Real-Time FX Rate APIs (Multiple Providers)

Background

PayD relies on exchange rates for payroll calculations, cross-border settlements, and conversion estimates.

Previously, FX rate retrieval depended on a limited provider strategy, increasing the risk of:

• Provider outages
• Stale conversion data
• Failed payroll calculations
• Reduced platform reliability

Solution

Implemented a modular multi-provider FX infrastructure.

Features

• Support for multiple FX providers
• Automatic provider fallback
• Consistent service abstraction layer
• Improved error handling
• Structured logging
• Provider health monitoring hooks
• Cached responses to reduce API load

Backend Improvements

Added:

• Provider interface abstraction
• Primary/secondary provider strategy
• Unified FX service
• Graceful degradation when providers fail
• Standardized response formatting

Error Handling

Implemented:

• Proper 4xx responses for invalid requests
• Proper 5xx responses for provider failures
• Timeout protection
• Retry logic where applicable
• Structured logging for troubleshooting

Testing

Added integration tests covering:

• Successful provider responses
• Provider fallback scenarios
• Invalid currency requests
• Timeout handling
• Service failure paths

Result

The FX subsystem is now significantly more resilient and production-ready.

---

Issue #773 — Contract Legacy Maintenance & Stability

Background

The Soroban contract layer required maintenance-focused improvements to ensure long-term reliability and consistency with the current architecture.

Solution

Applied stability and maintainability updates to the legacy contract implementation.

Improvements

• Reviewed public contract interfaces
• Improved defensive validation logic
• Strengthened error handling paths
• Reduced potential edge-case failures
• Improved internal consistency
• Updated documentation for public functions

Security Considerations

• Preserved asset-handling protections
• Maintained compatibility with existing contract architecture
• Ensured no unintended behavioral regressions

Testing

Added and updated unit tests covering:

• Expected execution paths
• Failure conditions
• Boundary scenarios
• Legacy compatibility checks

Validation

Executed:

cargo test
cargo clippy --all-targets --all-features
cargo fmt --check

All checks pass successfully.

---

Files Updated

Backend

backend/
 ├── services/
 ├── routes/
 ├── providers/
 ├── tests/
 └── prisma/

Contracts

contracts/
 ├── src/
 ├── tests/
 └── README.md

---

Testing Performed

Backend

npm run test
npm run lint
npm run build

Contract

cargo fmt --check
cargo clippy --all-targets --all-features
cargo test

---

Impact

This PR improves:

• FX conversion reliability
• Payroll processing resilience
• External API fault tolerance
• Contract maintainability
• Contract stability
• Platform readiness for production workloads

No breaking API changes were introduced.