Implement cross-border remittance fee splitting router (#792)

[Oluwasuyi-Oluwatimilehin-Daniel]

#closes #792

Summary

Implemented a cross-border remittance fee splitting router that dynamically distributes protocol fees between liquidity providers, anchor relayers, and protocol treasury based on configurable percentage allocations stored in contract storage. The system emits structured RemittanceFeesRouted events on every payout for transparency and auditability.

Features Implemented

1. Configurable Fee Percentage Splits

• Storage Schema: Fee split configurations are stored per-asset to support different fee structures for different currency corridors
• Default Configuration: 60% to liquidity providers, 30% to anchor relayers, 10% to protocol treasury
• Admin Control: Only contract administrators can modify fee split configurations
• Validation: Ensures percentages sum to exactly 100% and individual allocations are within bounds

2. Dynamic Fee Distribution Logic

• High-Precision Arithmetic: Uses interior scaling to maintain precision during division and avoid rounding errors
• Remainder Handling: Treasury receives the remainder to ensure exact total allocation (prevents dust loss)
• Zero Fee Handling: Gracefully handles zero-fee scenarios without errors
• Overflow Protection: Comprehensive checked arithmetic to prevent math overflows

3. Structured Event Emission

• Event Name: remittance_fee_routed (symbol: rem_fee_r)
• Event Data: Includes transfer ID, asset, total fee, individual allocations, percentage splits, and timestamp
• Audit Trail: Every fee distribution emits a structured event for transparency and monitoring

4. Analytics and Tracking

• Total Fees Routed: Per-asset tracking of total fees distributed through the system
• Transfer Correlation: Events include transfer IDs for correlation with on-chain activity

Implementation Details

New Files Created

src/router/remittance_fee_splitter.rs

• Module: Cross-border remittance fee splitting router
• Key Types:
  • FeeSplitConfig: Stores percentage allocations for LPs, relayers, and treasury
  • FeeDistributionResult: Result of fee distribution with allocated amounts
  • RemittanceFeesRoutedEvent: Structured event data for transparency
• Key Functions:
  • set_fee_split_config(): Admin function to configure fee splits per asset
  • get_fee_split_config(): Retrieve configuration (returns default if not set)
  • distribute_fees(): Main entry point for fee routing and distribution
  • calculate_fee_share(): High-precision fee share calculation
  • update_total_fees_routed(): Analytics tracking
  • get_total_fees_routed(): Retrieve total fees routed for an asset

Modified Files

src/router/mod.rs

• Added remittance_fee_splitter module export

src/lib.rs

• Added new error variants:
  • InvalidFeeSplitConfig = 60: Invalid fee split configuration
  • FeeDistributionMismatch = 61: Distribution doesn't match total fee

src/events/events.rs

• Added new event constant:
  • EV_REMITTANCE_FEES_ROUTED: Symbol for remittance fee routing events

Architecture

Fee Distribution Flow

1. Cross-border transfer generates protocol fees
   ↓
2. Fees are routed through remittance_fee_splitter::distribute_fees()
   ↓
3. Retrieve fee split configuration for the asset
   - Uses configured split if available
   - Falls back to default (60/30/10) if not configured
   ↓
4. Calculate allocations using high-precision arithmetic
   - LP share = (total_fee * liquidity_provider_bps) / 10000
   - Relayer share = (total_fee * anchor_relayer_bps) / 10000
   - Treasury share = total_fee - LP_share - Relayer_share (remainder)
   ↓
5. Validate distribution matches total exactly
   ↓
6. Update total fees routed tracking
   ↓
7. Emit RemittanceFeesRouted event with full breakdown
   ↓
8. Return FeeDistributionResult

Storage Schema

// Per-asset fee split configuration
RemittanceFeeStorageKey::FeeSplitConfig(AssetId) -> FeeSplitConfig

// Per-asset total fees routed (analytics)
RemittanceFeeStorageKey::TotalFeesRouted(AssetId) -> u64

Testing

Unit Tests

Comprehensive unit tests covering:

• ✅ Fee split configuration validation (percentage sums, individual bounds)
• ✅ Default configuration values
• ✅ Fee share calculation with basis points
• ✅ Fee distribution result validation
• ✅ Custom vs default split usage
• ✅ Zero fee handling
• ✅ Total fees routed tracking
• ✅ Event emission
• ✅ Remainder allocation handling

Logic Verification

Standalone logic tests verified:

• ✅ Valid fee split configurations (60/30/10)
• ✅ Invalid configurations rejected (non-100% sums)
• ✅ Fee share calculations (60%, 30%, 10%)
• ✅ Remainder allocation (handles integer division)
• ✅ Zero fee handling

Integration Points

Usage Example

// Set custom fee split for NGN corridor
let config = set_fee_split_config(
    env,
    admin,
    3897123275, // NGN asset ID
    5000,       // 50% to liquidity providers
    4000,       // 40% to anchor relayers
    1000,       // 10% to treasury
)?;

// Distribute fees from a cross-border transfer
let transfer_id = Bytes::from_slice(&env, &[1u8; 32]);
let result = distribute_fees(
    env,
    transfer_id,
    3897123275, // NGN asset ID
    1000,       // 1000 stroop fee
)?;

// Result contains:
// - total_fee: 1000
// - liquidity_provider_amount: 500
// - anchor_relayer_amount: 400
// - treasury_amount: 100

Event Structure

RemittanceFeesRoutedEvent {
    transfer_id: Bytes<32>,           // Transfer correlation ID
    asset: AssetId,                   // Asset identifier
    total_fee: u64,                   // Total fee amount
    liquidity_provider_amount: u64,    // LP allocation
    liquidity_provider_bps: u32,       // LP percentage
    anchor_relayer_amount: u64,       // Relayer allocation
    anchor_relayer_bps: u32,          // Relayer percentage
    treasury_amount: u64,             // Treasury allocation
    treasury_bps: u32,               // Treasury percentage
    timestamp: u64,                   // Ledger timestamp
}

Security Considerations

Access Control

• Admin-Only Configuration: Only contract administrators can modify fee split configurations
• Authorization Checks: All admin functions require proper authentication

Mathematical Safety

• Overflow Protection: All arithmetic operations use checked math
• Division Safety: Division operations check for zero denominators
• Precision Preservation: Interior scaling prevents truncation errors

Validation

• Percentage Sum Validation: Ensures splits sum to exactly 100%
• Bound Checking: Individual percentages cannot exceed 100%
• Distribution Validation: Final distribution must match total fee exactly

Future Enhancements

Potential Improvements

1. Time-Weighted Splits: Dynamic splits based on time of day or volume
2. Corridor-Specific Logic: Different split rules for high-volume vs low-volume corridors
3. Multi-Sig Configuration: Require multi-sig approval for split changes
4. Historical Tracking: Track split configuration changes over time
5. Revenue Sharing: Enable revenue sharing with specific addresses or contracts

Gas Optimization

The implementation is gas-optimized through:

• Efficient Storage: Uses instance storage for frequently accessed configs
• Basis Point Arithmetic: Avoids floating-point operations
• Minimal Event Data: Structured events with essential data only
• Checked Arithmetic: Prevents expensive rollback scenarios

Compatibility

• Soroban SDK: Compatible with Soroban SDK v20.0.0
• Existing Contracts: Integrates with existing StellarFlow contract architecture
• Asset System: Uses existing AssetId system for asset identification
• Event System: Follows established event emission patterns

Documentation

• Inline Documentation: Comprehensive Rust documentation for all public functions
• Type Documentation: Detailed documentation for all public types
• Error Documentation: Clear error descriptions for all error variants

Deployment Checklist

• Implementation completed
• Unit tests written and passing
• Logic verification completed
• Documentation updated
• Security considerations reviewed
• Gas optimization applied
• Integration testing with full contract suite
• Audit review
• Testnet deployment
• Mainnet deployment

Related Issues

• Resolves Build Cross-Border Remittance Fee Splitting Router #792: Cross-Border Remittance Fee Splitting Router
• Related to existing fee management in src/fees.rs
• Extends event system in src/events/events.rs

---

Generated: 2026-08-28
Branch: feature/792-cross-border-remittance-fee-splitting-router
Files Changed: 4 files added/modified
Lines Added: ~600 lines
Tests Added: 10 comprehensive unit tests
#closes

[drips-wave]

@Oluwasuyi-Oluwatimilehin-Daniel Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Sadeequ]

Resolve la conflict... @Oluwasuyi-Oluwatimilehin-Daniel