feat: MISC-007 add per-merchant analytics and reporting

PR_DETAILS.md

@@ -0,0 +1,92 @@
+# Pull Request Details
+
+## Branch
+`misc-006-merchant-category-validation`
+
+## Title
+MISC-006: Merchant category validation and migration guide
+
+## Description
+
+### Overview
+This PR addresses issue #101 MISC-006 by implementing comprehensive documentation and migration guidance for merchant category management.
+
+### Changes
+
+#### 1. ADR-0004: Merchant Category Management Strategy
+- **File**: `docs/adr/0004-merchant-category-management.md`
+- Documents the current enum-based category system
+- Explains why categories require contract upgrades
+- Outlines a future Phase 2 approach with string-based categories and admin-managed allowlist
+- Provides migration path and backward compatibility notes
+
+#### 2. Category Migration Guide
+- **File**: `docs/CATEGORY_MIGRATION_GUIDE.md`
+- Step-by-step instructions for adding new merchant categories
+- Covers: enum updates, test coverage, build/test, deployment, and rollback procedures
+- Includes troubleshooting section for common issues
+- Best practices for category management
+
+#### 3. README Updates
+- Added new "Merchant Categories" section
+- Documents all five current categories (Retail, Food, Services, Digital, Other)
+- Links to migration guide and ADR-0004
+- Updated register_merchant documentation with category notes
+
+### Acceptance Criteria Met
+
+✅ **Document that category additions require a contract upgrade**
+- Clearly documented in ADR-0004 and migration guide
+- Explains the type-safety benefits of enum-based approach
+
+✅ **Add a migration guide template for category additions**
+- Comprehensive CATEGORY_MIGRATION_GUIDE.md with step-by-step instructions
+- Includes testing, deployment, and rollback procedures
+
+✅ **Consider a string-based category with admin-managed allowlist**
+- Documented as Phase 2 enhancement in ADR-0004
+- Provides rationale and implementation approach for future versions
+
+### Technical Details
+
+#### Current Implementation
+- MerchantCategory is a Soroban #[contracttype] enum with 5 variants
+- Type-safe, prevents invalid categories at serialization
+- Immutable per merchant (cannot be changed after registration)
+- No functional impact on contract behavior (metadata-only)
+
+#### Future Considerations
+- Phase 2: Implement string-based categories with admin-managed allowlist
+- Enable dynamic category additions without contract upgrades
+- Add category-based queries, filtering, and statistics
+- Implement category-based access control or restrictions
+
+### Testing
+
+All existing tests pass without modification. The changes are documentation-only and do not affect contract behavior or storage.
+
+### Related Issues
+
+Closes #101 MISC-006
+
+### Labels
+
+smart-contract, product, documentation
+
+---
+
+## How to Create the PR
+
+1. Go to: https://github.com/MooreTheAnalyst/pulsar-contracts/pull/new/misc-006-merchant-category-validation
+2. Copy the title and description above
+3. Click "Create pull request"
+
+Or use GitHub CLI:
+```bash
+gh pr create \
+  --repo MooreTheAnalyst/pulsar-contracts \
+  --base main \
+  --head misc-006-merchant-category-validation \
+  --title "MISC-006: Merchant category validation and migration guide" \
+  --body "$(cat PR_DETAILS.md | tail -n +3)"
+```

README.md

@@ -27,6 +27,7 @@ Pulsar is a comprehensive payment-processing smart contract for the Stellar Soro
   - [Refunds](#refunds)
   - [Multi-Signature Payments](#multi-signature-payments)
   - [Admin Config](#admin-config)
+- [Analytics](#analytics)
 - [Events](#events)
 - [Error Codes](#error-codes)
 - [Roadmap](#roadmap)
@@ -45,6 +46,7 @@ Pulsar is a comprehensive payment-processing smart contract for the Stellar Soro
 | Multi-sig | Require N-of-N signers before executing a payment |
 | History queries | Cursor-based pagination with filtering and sorting |
 | Global stats | Admin-only aggregate payment and refund statistics |
+| Merchant stats | Per-merchant analytics with optional date filtering |
 
 ---
 
@@ -410,6 +412,26 @@ stellar contract invoke --id $CONTRACT_ID --source-account <ADMIN_KEY> --network
   --date_end null
 ```
 
+#### `get_merchant_stats`
+
+Returns per-merchant payment and refund statistics. Accessible by the merchant (own stats) or admin (any merchant).
+
+```bash
+stellar contract invoke --id $CONTRACT_ID --source-account <MERCHANT_KEY> --network local \
+  -- get_merchant_stats \
+  --merchant <ADDRESS> \
+  --date_start null \
+  --date_end null
+```
+
+**Returns**: `MerchantStats` with `total_payments`, `total_volume`, `total_refunds`, `total_refund_volume`
+
+**Query Modes**:
+- **Unfiltered** (no date range): Returns cached stats (O(1))
+- **Filtered** (with date range): Computes stats on-demand (O(n) where n = merchant's payment count)
+
+**See also**: [ANALYTICS_GUIDE.md](docs/ANALYTICS_GUIDE.md) for detailed usage and best practices.
+
 ---
 > **Known Limitation:** The `date_start` and `date_end` parameters for `get_global_payment_stats` are currently a no‑op due to SC‑003. They will be functional once the issue is resolved.
 
@@ -529,6 +551,78 @@ stellar contract invoke --id $CONTRACT_ID --source-account <ADMIN_KEY> --network
 
 ---
 
+## Analytics
+
+The contract provides on-chain analytics capabilities for monitoring payment activity and merchant performance.
+
+### Global Payment Stats
+
+Admin-only aggregate statistics across all merchants and payments.
+
+**Function**: `get_global_payment_stats(admins, date_start, date_end)`
+
+**Returns**: `GlobalStats` with `total_payments`, `total_volume`, `total_refunds`, `total_refund_volume`
+
+**Example**:
+```bash
+stellar contract invoke --id $CONTRACT_ID --source-account <ADMIN_KEY> --network local \
+  -- get_global_payment_stats \
+  --admins '["<ADMIN_ADDRESS>"]' \
+  --date_start null \
+  --date_end null
+```
+
+### Per-Merchant Stats
+
+Per-merchant payment and refund statistics with optional date filtering.
+
+**Function**: `get_merchant_stats(merchant, date_start, date_end)`
+
+**Access**: Merchant (own stats) or Admin (any merchant)
+
+**Returns**: `MerchantStats` with merchant address, payment count, volume, refund count, and refund volume
+
+**Example**:
+```bash
+# Merchant queries their own stats
+stellar contract invoke --id $CONTRACT_ID --source-account <MERCHANT_KEY> --network local \
+  -- get_merchant_stats \
+  --merchant <MERCHANT_ADDRESS> \
+  --date_start null \
+  --date_end null
+
+# Admin queries a merchant's stats with date filtering
+stellar contract invoke --id $CONTRACT_ID --source-account <ADMIN_KEY> --network local \
+  -- get_merchant_stats \
+  --merchant <MERCHANT_ADDRESS> \
+  --date_start 1704067200 \
+  --date_end 1704153600
+```
+
+**Query Modes**:
+- **Unfiltered** (no date range): Returns cached stats (O(1) performance)
+- **Filtered** (with date range): Computes stats on-demand (O(n) where n = merchant's payment count)
+
+### Analytics Strategy
+
+The contract implements a **hybrid analytics approach**:
+
+1. **On-Chain Analytics** (current):
+   - Per-merchant stats with date filtering
+   - Global aggregate stats
+   - Cached for performance
+   - Suitable for real-time queries and merchant dashboards
+
+2. **Off-Chain Analytics** (future - BE-001):
+   - Event-driven indexer service
+   - Per-token breakdown and time-series data
+   - Complex queries and historical analysis
+   - Reduces on-chain computation overhead
+
+**See also**: [ANALYTICS_GUIDE.md](docs/ANALYTICS_GUIDE.md) for detailed usage, best practices, and performance considerations.
+
+---
+
 ## Events
 
 | Event | Emitted by |

contracts/payment-processing-contract/src/lib.rs

@@ -327,6 +327,67 @@ impl PaymentContract {
         Ok(stats)
     }
 
+    pub fn get_merchant_stats(
+        env: Env,
+        merchant: Address,
+        date_start: Option<u64>,
+        date_end: Option<u64>,
+    ) -> Result<MerchantStats, PaymentError> {
+        // Merchant can query their own stats, or admin can query any merchant
+        let caller = env.invoker();
+        if caller != merchant {
+            helper::require_multi_admin(&env, vec![&env, caller])?;
+        }
+
+        // If no date filter, return cached stats
+        if date_start.is_none() && date_end.is_none() {
+            return Ok(storage::get_merchant_stats(&env, &merchant));
+        }
+
+        // Compute filtered stats by iterating merchant's payments
+        let mut stats = MerchantStats {
+            merchant_address: merchant.clone(),
+            total_payments: 0,
+            total_volume: 0,
+            total_refunds: 0,
+            total_refund_volume: 0,
+        };
+
+        let p_ids = storage::get_merchant_payment_ids(&env, &merchant);
+        for id in p_ids.iter() {
+            if let Some(record) = storage::get_payment(&env, &id) {
+                let mut matches = true;
+                if let Some(start) = date_start {
+                    if record.paid_at < start {
+                        matches = false;
+                    }
+                }
+                if let Some(end) = date_end {
+                    if record.paid_at > end {
+                        matches = false;
+                    }
+                }
+                if matches {
+                    stats.total_payments += 1;
+                    stats.total_volume = stats
+                        .total_volume
+                        .checked_add(record.amount)
+                        .ok_or(PaymentError::ArithmeticError)?;
+                    // Add refunded amount to refund stats
+                    if record.refunded_amount > 0 {
+                        stats.total_refunds += 1;
+                        stats.total_refund_volume = stats
+                            .total_refund_volume
+                            .checked_add(record.refunded_amount)
+                            .ok_or(PaymentError::ArithmeticError)?;
+                    }
+                }
+            }
+        }
+
+        Ok(stats)
+    }
+
     // ── Payment management ────────────────────────────────────────────────────
 
     pub fn update_payment_status(