Skip to content

PR_DESCRIPTION_MULTI_ASSET.md

Latest commit

 

History

History
98 lines (79 loc) · 4.37 KB

PR_DESCRIPTION_MULTI_ASSET.md

File metadata and controls

98 lines (79 loc) · 4.37 KB

Pull Request: Support for Multi-Asset Payouts (Issue #46)

Summary

This PR implements path payment support for the Utility Drip Contracts, allowing utility providers to accept payment in USDC but receive the final payout in XLM via Stellar's path payment functionality.

Features Implemented

Core Functionality

  • withdraw_earnings_path_payment(): New function that enables providers to withdraw earnings in a different token than the payment token
  • Token Conversion Support: Automatic conversion from USD cents to destination tokens using the price oracle
  • Supported Token Management: Functions to add/remove supported withdrawal tokens

New Functions Added

  1. withdraw_earnings_path_payment(env, meter_id, amount_usd_cents, destination_token) - Main path payment function
  2. add_supported_withdrawal_token(env, token) - Add token to supported withdrawal list
  3. remove_supported_withdrawal_token(env, token) - Remove token from supported withdrawal list
  4. get_supported_withdrawal_tokens(env) - Get list of supported withdrawal tokens
  5. is_withdrawal_token_supported(env, token) - Check if token is supported for withdrawal
  6. convert_usd_to_token_if_needed(env, usd_cents, destination_token) - Helper for USD to token conversion

Data Structure Updates

  • Added SupportedWithdrawalToken(Address) to DataKey enum for tracking supported withdrawal tokens

Use Case Scenario

  1. User pays: Customer tops up their meter using USDC
  2. Provider withdraws: Utility provider can choose to receive earnings in XLM instead of USDC
  3. Automatic conversion: Contract handles the conversion using the price oracle
  4. Seamless experience: Provider receives XLM even though original payment was in USDC

Technical Implementation

Path Payment Flow

USDC Payment → Contract (USD cents) → Oracle Conversion → XLM Withdrawal

Key Features

  • Oracle Integration: Uses existing price oracle for accurate conversions
  • Security: Validates destination tokens are supported before processing
  • Fallback: If destination token equals meter token, uses regular withdrawal
  • Event Emission: Emits PathPayment events for tracking and monitoring
  • Balance Management: Properly updates meter balances and provider pools

Error Handling

  • Validates withdrawal amounts are positive and available
  • Checks destination token is supported
  • Ensures contract has sufficient destination token balance
  • Proper error codes for all failure scenarios

Testing

Added comprehensive test coverage including:

  • test_path_payment_usdc_to_xlm() - Tests USDC to XLM conversion
  • test_path_payment_same_token() - Tests fallback to regular withdrawal
  • test_supported_withdrawal_tokens() - Tests token support functions
  • test_add_remove_withdrawal_tokens() - Tests token management

Security Considerations

  • All conversions use the trusted price oracle
  • Providers must authenticate to withdraw
  • Supported tokens must be explicitly whitelisted
  • Contract balance checks prevent insufficient funds errors
  • Proper authorization checks on all functions

Backward Compatibility

  • All existing functionality remains unchanged
  • New functions are additive only
  • Existing withdrawal methods continue to work as before
  • No breaking changes to existing contracts

Files Modified

  • contracts/utility_contracts/src/lib.rs - Core implementation
  • contracts/utility_contracts/src/test.rs - Test coverage

Files Added

  • None (implementation integrated into existing files)

Testing Commands

cargo test --lib test_path_payment
cargo test --lib test_supported_withdrawal_tokens
cargo test --lib test_add_remove_withdrawal_tokens

Deployment Notes

  1. Deploy updated contract to testnet first
  2. Ensure price oracle is configured and functional
  3. Fund contract with XLM reserves for path payments
  4. Add supported withdrawal tokens as needed
  5. Monitor path payment events for debugging

Future Enhancements

  • Support for multiple destination tokens beyond XLM
  • Dynamic path optimization for best conversion rates
  • Liquidity pool integration for better token availability
  • Historical path payment tracking and analytics

Issue Resolution

This PR fully addresses issue #46: "Support for Multi-Asset Payouts" by implementing the requested path payment functionality that allows utility providers to accept payment in USDC but receive the final payout in XLM.