Implement Multi-Currency Support for Donation Notifications, Summaries, and Analytics

[grantfox-oss]

Description

The Donation model already stores the donation currency, but several parts of the application still assume that every donation is made in XLM. This results in incorrect notification messages, inaccurate donation summaries, and analytics that do not properly represent multi-currency transactions.

This issue introduces full multi-currency support across the donation workflow, ensuring that the stored currency is respected everywhere donations are displayed, processed, or aggregated. Where values need to be compared or summarized across different currencies, conversion metadata should be stored and used instead of assuming a fixed currency.

Problem Statement

Current implementation issues include:

• Notification messages always display donation amounts as XLM regardless of the actual currency.
• Donation summaries aggregate values without considering different currencies.
• Analytics and reporting assume all donations share the same currency, producing misleading totals.
• No conversion metadata exists for generating normalized metrics or historical reports.

Expected Implementation

Business Logic

• Update donation processing logic to use the currency stored on each Donation record.
• Remove any hardcoded "XLM" references from services, helpers, and business logic.
• Ensure all amount formatting functions accept both amount and currency.

Conversion Metadata

• Introduce conversion metadata if required for reporting and analytics, such as:

  • baseCurrency
  • exchangeRate
  • convertedAmount
  • conversionTimestamp

• Store conversion values at the time of donation to ensure historical reports remain consistent even if exchange rates change.

Notifications

• Update all donation-related notifications to display the correct currency symbol or code.

• Examples:

  • ✅ "You received 50 USDC"
  • ✅ "Thank you for donating 25 EUR"
  • ❌ "You received 50 XLM" (when the donation was USDC)

Donation Summaries

• Ensure summary endpoints and dashboard widgets correctly handle multiple currencies.

• Either:

  • Group totals by currency, or
  • Display normalized totals using stored conversion metadata, depending on the existing analytics design.

• Prevent direct aggregation of different currencies without conversion.

Analytics

• Update analytics queries and reporting logic to:

  • Support filtering and grouping by currency.
  • Generate accurate totals for each currency.
  • Use conversion metadata when a unified total is required.
  • Preserve historical accuracy by relying on stored exchange rates rather than live conversions.

API Responses

• Verify that donation-related API responses expose the necessary currency information, including any conversion fields if implemented.
• Maintain backward compatibility where possible while extending existing response objects.

Acceptance Criteria

• All hardcoded XLM assumptions are removed from donation business logic.
• Notifications display the correct donation currency.
• Donation summaries correctly handle multiple currencies.
• Analytics support multi-currency reporting without mixing raw values.
• Conversion metadata is stored and used where normalized totals are required.
• Existing tests are updated and new tests cover multi-currency scenarios.
• No regression is introduced for existing XLM donation flows.

[ekwe7]

I would love to work on this issue. I have experience building production ready applications and collaborating through GitHub workflows. I'll carefully analyze the current implementation, propose a reliable solution, and submit a well-tested PR. My focus is on clean code, maintainability, and timely delivery

[Silver36-ship-it]

I would love to work on this professionally, please assign it to me

[GBOYEE]

I'd like to work on this issue. I have background in devops and will submit a PR ASAP.

[Queenode]

Hi Maintainers,

I would like to work on this issue.

I have experience building backend systems involving payments, financial reporting, and multi-currency transaction flows. I understand that assuming all donations are denominated in XLM can lead to inaccurate notifications, reporting, and analytics, especially as support for additional currencies grows.

Approach

• Review the donation workflow to identify all areas where currency assumptions are made.
• Remove hardcoded XLM references and ensure donation processing consistently uses the currency stored on each Donation record.
• Update notification templates and formatting helpers to display the correct currency code or symbol.
• Enhance donation summaries to properly handle multiple currencies without aggregating incompatible values.
• Implement and persist conversion metadata where required for normalized reporting, including exchange rates and converted values at the time of donation.
• Update analytics and reporting queries to support grouping, filtering, and aggregation by currency while preserving historical accuracy.
• Verify API responses expose the necessary currency and conversion information without breaking existing consumers.
• Add and update tests covering multi-currency donations, summaries, analytics, notifications, and existing XLM donation flows.

Why Me

• Experience working on payment and financial applications.
• Strong understanding of data integrity, reporting accuracy, and backward compatibility.
• Comfortable updating business logic, APIs, analytics, and test suites in a coordinated manner.

I will ensure the implementation fully supports multi-currency donations while maintaining accurate reporting and preserving compatibility with existing XLM workflows.

Thank you for your consideration.

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[jaynomyaro]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[gar-uda]

2 days

[GBOYEE]

I'm interested in tackling this! Strong frontend background, clean PR coming shortly.

[GBOYEE]

I'm interested in tackling this! Strong frontend background, clean PR coming shortly.

[GBOYEE]

I'm interested in tackling this! Strong frontend background, clean PR coming shortly.

[GBOYEE]

I'm interested in tackling this! Strong frontend background, clean PR coming shortly.