feat: Implement Cross-Contract Aggregation and Reporting

ARCHITECTURE.md

@@ -19,6 +19,15 @@ The Remitwise Contracts suite implements a comprehensive financial management sy
 │  Savings Goals  │    │    Insurance    │
 │                 │    │                 │
 └─────────────────┘    └─────────────────┘
+          │                     │
+          │                     │
+          └──────────┬──────────┘
+                     │
+                     v
+            ┌─────────────────┐
+            │    Reporting    │
+            │   (Aggregator)  │
+            └─────────────────┘
 ```
 
 ## Data Flow Architecture
@@ -149,6 +158,34 @@ Instance Storage:
 - **Provides:** Savings allocation management
 - **Consumes:** Allocation amounts from Remittance Split
 
+### 5. Reporting Contract
+
+**Purpose:** Cross-contract data aggregation and comprehensive financial reporting
+
+**Key Features:**
+
+- Cross-contract data queries
+- Financial health score calculation
+- Multiple report types (remittance, savings, bills, insurance)
+- Trend analysis and period comparisons
+- Report storage and retrieval
+- Category-wise breakdowns
+
+**Storage Structure:**
+
+```
+Instance Storage:
+├── ADMIN: Address
+├── ADDRS: ContractAddresses
+├── REPORTS: Map<(Address, u64), FinancialHealthReport>
+```
+
+**Relationships:**
+
+- **Provides:** Aggregated financial insights and reports
+- **Consumes:** Data from all other contracts via cross-contract calls
+- **Integrates:** With remittance_split, savings_goals, bill_payments, insurance, family_wallet
+
 ## Integration Patterns
 
 ### Automated Remittance Processing
@@ -187,6 +224,33 @@ fn get_financial_overview(env: Env, user: Address) -> FinancialOverview {
 }
 ```
 
+### Reporting Integration
+
+The Reporting contract aggregates data from all contracts:
+
+```rust
+fn generate_financial_health_report(env: Env, user: Address) -> FinancialHealthReport {
+    // Query remittance split configuration
+    let split_client = RemittanceSplitClient::new(&env, &split_address);
+    let split_config = split_client.get_split(&env);
+
+    // Query savings progress
+    let savings_client = SavingsGoalsClient::new(&env, &savings_address);
+    let goals = savings_client.get_all_goals(user.clone());
+
+    // Query bill compliance
+    let bill_client = BillPaymentsClient::new(&env, &bills_address);
+    let unpaid_bills = bill_client.get_unpaid_bills(user.clone());
+
+    // Query insurance coverage
+    let insurance_client = InsuranceClient::new(&env, &insurance_address);
+    let policies = insurance_client.get_active_policies(user);
+
+    // Calculate health score and generate report
+    calculate_health_score_and_report(split_config, goals, unpaid_bills, policies)
+}
+```
+
 ## Security Architecture
 
 ### Access Control
@@ -229,6 +293,11 @@ Savings Goals Events:
 ├── SavingsEvent::GoalCompleted
 ├── SavingsEvent::GoalLocked
 ├── SavingsEvent::GoalUnlocked
+
+Reporting Events:
+├── ReportEvent::ReportGenerated
+├── ReportEvent::ReportStored
+├── ReportEvent::AddressesConfigured
 ```
 
 ### Event Flow
@@ -309,9 +378,10 @@ Development → Testnet → Mainnet
 Remittance Split ← Bill Payments
 Remittance Split ← Insurance
 Remittance Split ← Savings Goals
+All Contracts ← Reporting (read-only queries)
 ```
 
-No circular dependencies ensure clean deployment order.
+No circular dependencies ensure clean deployment order. The Reporting contract should be deployed last after all other contracts are deployed and their addresses are known.
 
 ## Future Extensibility
 

Cargo.toml

@@ -12,6 +12,7 @@ members = [
     "insurance",
     "family_wallet",
     "data_migration",
+    "reporting",
 ]
 resolver = "2"
 

DEPLOYMENT.md

@@ -11,12 +11,13 @@ This guide covers the deployment of the Remitwise Contracts suite to the Stellar
 
 ## Contracts Overview
 
-The Remitwise Contracts suite consists of four main contracts:
+The Remitwise Contracts suite consists of five main contracts:
 
 1. **Remittance Split** - Manages fund allocation percentages
 2. **Bill Payments** - Handles bill creation and payment tracking
 3. **Insurance** - Manages insurance policies and premiums
 4. **Savings Goals** - Tracks savings goals and fund management
+5. **Reporting** - Cross-contract aggregation and financial reporting
 
 ## Deployment Steps
 
@@ -51,6 +52,9 @@ soroban contract build
 
 cd ../savings_goals
 soroban contract build
+
+cd ../reporting
+soroban contract build
 ```
 
 ### 3. Deploy to Testnet
@@ -114,6 +118,15 @@ SAVINGS_GOALS_ID=$(soroban contract deploy \
   --network testnet)
 
 echo "Savings Goals deployed: $SAVINGS_GOALS_ID"
+
+# Deploy Reporting contract (must be deployed last)
+cd ../reporting
+REPORTING_ID=$(soroban contract deploy \
+  --wasm target/wasm32-unknown-unknown/release/reporting.wasm \
+  --source deployer \
+  --network testnet)
+
+echo "Reporting deployed: $REPORTING_ID"
 ```
 
 ### 4. Initialize Contracts
@@ -130,6 +143,35 @@ soroban contract invoke \
   init
 ```
 
+#### Initialize Reporting Contract
+
+```bash
+# Initialize with admin address
+ADMIN_ADDRESS="GA..."  # Your admin address
+
+soroban contract invoke \
+  --id $REPORTING_ID \
+  --source deployer \
+  --network testnet \
+  -- \
+  init \
+  --admin $ADMIN_ADDRESS
+
+# Configure contract addresses
+soroban contract invoke \
+  --id $REPORTING_ID \
+  --source deployer \
+  --network testnet \
+  -- \
+  configure_addresses \
+  --caller $ADMIN_ADDRESS \
+  --remittance_split $REMittance_SPLIT_ID \
+  --savings_goals $SAVINGS_GOALS_ID \
+  --bill_payments $BILL_PAYMENTS_ID \
+  --insurance $INSURANCE_ID \
+  --family_wallet "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"  # Family wallet address
+```
+
 ### 5. Configuration
 
 #### Set Up Remittance Split (Example)
@@ -177,6 +219,7 @@ REMittance_SPLIT_ID=$REMittance_SPLIT_ID
 BILL_PAYMENTS_ID=$BILL_PAYMENTS_ID
 INSURANCE_ID=$INSURANCE_ID
 SAVINGS_GOALS_ID=$SAVINGS_GOALS_ID
+REPORTING_ID=$REPORTING_ID
 EOF
 ```
 
@@ -204,6 +247,23 @@ Create a complete user workflow:
 3. Create insurance policies
 4. Create bills
 5. Simulate remittance processing
+6. Generate financial health report
+
+```bash
+# Generate a comprehensive financial health report
+USER_ADDRESS="GA..."
+
+soroban contract invoke \
+  --id $REPORTING_ID \
+  --source deployer \
+  --network testnet \
+  -- \
+  get_financial_health_report \
+  --user $USER_ADDRESS \
+  --total_remittance 10000000000 \
+  --period_start 1704067200 \
+  --period_end 1706745600
+```
 
 ## Troubleshooting
 

README.md

@@ -11,6 +11,7 @@ This workspace contains the core smart contracts that power RemitWise's post-rem
 - **bill_payments**: Automated bill payment tracking and scheduling
 - **insurance**: Micro-insurance policy management and premium payments
 - **family_wallet**: Family member management with spending limits and permissions
+- **reporting**: Cross-contract aggregation and comprehensive financial reporting
 
 ## Prerequisites
 
@@ -35,6 +36,7 @@ cargo build --release --target wasm32-unknown-unknown
 Handles automatic allocation of remittance funds into different categories.
 
 **Key Functions:**
+
 - `initialize_split`: Set percentage allocation (spending, savings, bills, insurance)
 - `get_split`: Get current split configuration
 - `calculate_split`: Calculate actual amounts from total remittance
@@ -44,6 +46,7 @@ Handles automatic allocation of remittance funds into different categories.
 Manages goal-based savings with target dates.
 
 **Key Functions:**
+
 - `create_goal`: Create a new savings goal (education, medical, etc.)
 - `add_to_goal`: Add funds to a goal
 - `get_goal`: Get goal details
@@ -54,6 +57,7 @@ Manages goal-based savings with target dates.
 Tracks and manages bill payments with recurring support.
 
 **Key Functions:**
+
 - `create_bill`: Create a new bill (electricity, school fees, etc.)
 - `pay_bill`: Mark a bill as paid and create next recurring bill if applicable
 - `get_unpaid_bills`: Get all unpaid bills
@@ -64,6 +68,7 @@ Tracks and manages bill payments with recurring support.
 Manages micro-insurance policies and premium payments.
 
 **Key Functions:**
+
 - `create_policy`: Create a new insurance policy
 - `pay_premium`: Pay monthly premium
 - `get_active_policies`: Get all active policies
@@ -74,11 +79,28 @@ Manages micro-insurance policies and premium payments.
 Manages family members, roles, and spending limits.
 
 **Key Functions:**
+
 - `add_member`: Add a family member with role and spending limit
 - `get_member`: Get member details
 - `update_spending_limit`: Update spending limit for a member
 - `check_spending_limit`: Verify if spending is within limit
 
+### Reporting
+
+Aggregates data from all contracts to generate comprehensive financial reports.
+
+**Key Functions:**
+
+- `get_financial_health_report`: Generate comprehensive financial health report
+- `get_remittance_summary`: Get remittance allocation breakdown
+- `get_savings_report`: Get savings progress report
+- `get_bill_compliance_report`: Get bill payment compliance report
+- `get_insurance_report`: Get insurance coverage report
+- `calculate_health_score`: Calculate financial health score (0-100)
+- `get_trend_analysis`: Compare period-over-period trends
+- `store_report`: Store report for future reference
+- `get_stored_report`: Retrieve previously stored report
+
 ## Testing
 
 Run tests for all contracts:
@@ -140,4 +162,3 @@ This is a basic MVP implementation. Future enhancements:
 ## License
 
 MIT
-

reporting/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "reporting"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+soroban-sdk = "21.0.0"
+
+[dev-dependencies]
+soroban-sdk = { version = "21.0.0", features = ["testutils"] }