Tax Compliance: Add jurisdiction-specific tax rules

contracts/tax-compliance/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,217 @@
+# Jurisdiction-Specific Tax Rules Implementation Summary
+
+## Overview
+Successfully implemented jurisdiction-specific tax calculation logic for US, EU, and Asian markets with configurable tax rates, exemptions, surcharges, and compliance requirements.
+
+## Implementation Details
+
+### 1. New Data Structures Added
+
+#### JurisdictionProfile
+- `surcharge_basis_points`: Local/regional surcharge rate
+- `early_payment_discount_basis_points`: Discount for early payment
+- `late_payment_grace_period`: Grace period before penalties apply
+- `optimization_window`: Time window for early payment discounts
+- `requires_digital_stamp`: Digital compliance requirement flag
+- `authority_hash`: Hash of governing authority documentation
+
+#### TaxBreakdown
+- `taxable_value`: Value after exemptions
+- `base_tax`: Base tax calculation
+- `fixed_charge`: Fixed jurisdiction charges
+- `surcharge_amount`: Local/regional surcharges
+- `discount_amount`: Applied discounts
+- `penalty_amount`: Late payment penalties
+- `total_due`: Total tax obligation
+
+#### OptimizationPlan
+- `estimated_savings`: Potential savings through optimization
+- `recommended_installments`: Suggested payment schedule
+- `should_prepay`: Early payment recommendation
+- `review_exemption`: Exemption review suggestion
+- `supporting_reference`: Reference to supporting documentation
+
+#### PaymentReceipt
+- Payment tracking with jurisdiction context
+- Outstanding balance calculation
+- Settlement timestamp
+
+#### RegionType Enum
+- US, EU, Asia region identifiers
+
+### 2. Enhanced TaxRecord
+Added fields:
+- `penalty_amount`: Track late payment penalties
+- `discount_amount`: Track applied discounts
+
+### 3. New Storage
+- `jurisdiction_profiles: Mapping<u32, JurisdictionProfile>`: Stores jurisdiction-specific profiles
+
+### 4. New Functions
+
+#### configure_jurisdiction_profile()
+Allows admin to configure jurisdiction-specific tax profiles with surcharges, discounts, and compliance requirements.
+
+#### calculate_tax_breakdown()
+Returns detailed tax breakdown showing base tax, surcharges, discounts, and penalties for transparency.
+
+#### get_jurisdiction_profile()
+Query function to retrieve jurisdiction profile configuration.
+
+#### initialize_jurisdiction_presets()
+One-click initialization of preset tax rules and profiles for US, EU, or Asia regions.
+
+### 5. Enhanced calculate_tax()
+Now uses the advanced tax engine that:
+- Applies jurisdiction-specific surcharges
+- Calculates early payment discounts
+- Computes late payment penalties
+- Provides detailed tax breakdowns
+
+### 6. Jurisdiction Presets Module
+
+Created `jurisdiction_presets.rs` with pre-configured rules:
+
+#### US (Code: 1001)
+- Property tax: 3% (300 basis points)
+- Homestead exemption: $50,000
+- Payment window: 90 days
+- Local surcharge: 1%
+- Early payment discount: 1.5%
+- Grace period: 30 days
+- Penalty: 5%
+
+#### EU (Code: 2001)
+- Property tax: 2% (200 basis points)
+- Standard exemption: €30,000
+- Payment window: 60 days (stricter)
+- Municipal surcharge: 0.5%
+- Early payment discount: 2%
+- Grace period: 15 days (stricter)
+- Penalty: 4%
+- Digital stamp required (GDPR compliance)
+
+#### Asia (Code: 3001)
+- Property tax: 4% (400 basis points)
+- Standard exemption: $20,000
+- Payment window: 60 days
+- Local development charge: 1.5%
+- Early payment discount: 1%
+- Grace period: 20 days
+- Penalty: 6% (stricter enforcement)
+- Digital stamp required
+
+### 7. Country Code Mapping
+Helper function `jurisdiction_from_country()` maps country codes to jurisdiction configurations:
+- US → US jurisdiction (1001)
+- DE, FR, IT, ES, NL → EU jurisdiction (2001)
+- SG, MY, TH, JP, KR → Asia jurisdiction (3001)
+
+### 8. Comprehensive Tests
+
+Created `jurisdiction_tests.rs` with test cases for:
+- US property tax calculation with surcharges
+- EU property tax calculation with GDPR compliance
+- Asia property tax calculation with development charges
+
+Each test verifies:
+- Taxable value calculation (assessed value - exemptions)
+- Base tax calculation
+- Surcharge application
+- Total tax due
+
+## Files Modified
+
+1. **contracts/tax-compliance/src/lib.rs**
+   - Added data structures
+   - Enhanced TaxRecord
+   - Added storage mapping
+   - Implemented new functions
+   - Enhanced calculate_tax()
+   - Added module imports
+
+2. **contracts/tax-compliance/src/jurisdiction_presets.rs** (NEW)
+   - US, EU, Asia preset configurations
+   - Country code mapping function
+
+3. **tests/tax_compliance/jurisdiction_tests.rs** (NEW)
+   - US, EU, Asia test cases
+   - Verification of tax calculations
+
+## Architecture
+
+```
+TaxComplianceModule
+├── TaxRule (base rates, exemptions, frequencies)
+├── JurisdictionProfile (surcharges, discounts, compliance)
+├── TaxRecord (calculated tax with breakdown)
+└── Tax Engine
+    ├── Base tax calculation
+    ├── Surcharge application
+    ├── Discount calculation
+    └── Penalty computation
+```
+
+## Usage Example
+
+```rust
+// Initialize US presets
+contract.initialize_jurisdiction_presets(RegionType::US)?;
+
+// Or configure manually
+contract.configure_tax_rule(
+    Jurisdiction { code: 1001, country_code: *b"US", ... },
+    TaxRule { rate_basis_points: 300, ... }
+)?;
+
+contract.configure_jurisdiction_profile(
+    Jurisdiction { code: 1001, ... },
+    JurisdictionProfile { surcharge_basis_points: 100, ... }
+)?;
+
+// Calculate tax
+let record = contract.calculate_tax(property_id, jurisdiction)?;
+
+// Get detailed breakdown
+let breakdown = contract.calculate_tax_breakdown(
+    property_id, 
+    jurisdiction_code, 
+    record.reporting_period
+)?;
+```
+
+## Key Features
+
+1. **Flexible Configuration**: Admin can configure any jurisdiction's tax rules
+2. **Preset Support**: One-click initialization for major regions
+3. **Transparent Calculations**: Detailed breakdowns for auditability
+4. **Early Payment Incentives**: Configurable discount windows
+5. **Penalty Enforcement**: Automatic late payment penalty calculation
+6. **Multi-Jurisdiction Support**: Extensible to any country/region
+7. **Compliance Tracking**: Digital stamp requirements per jurisdiction
+8. **Precision**: All rates use basis points (0.01% precision)
+
+## Extensibility
+
+To add a new jurisdiction:
+1. Define jurisdiction code and country code
+2. Configure TaxRule (rates, exemptions, frequencies)
+3. Configure JurisdictionProfile (surcharges, discounts, compliance)
+4. Optionally add to jurisdiction_presets.rs for preset support
+
+## Testing
+
+Run tests with:
+```bash
+cargo test --package tax-compliance --features disabled_test
+```
+
+## Next Steps
+
+Potential enhancements:
+- Add more jurisdictions (UK, UAE, Singapore-specific, etc.)
+- Implement transfer/conveyance taxes
+- Add rental income tax calculations
+- Support capital gains tax
+- Create UI for jurisdiction configuration
+- Add tax treaty support for cross-border properties

contracts/tax-compliance/src/jurisdiction_presets.rs

@@ -0,0 +1,137 @@
+use crate::{Jurisdiction, JurisdictionProfile, ReportingFrequency, TaxRule};
+
+/// US Federal tax rule configuration
+/// - Property tax rate: ~3% (varies by state)
+/// - Homestead exemption: $50,000
+/// - Annual reporting
+/// - 90-day payment window
+pub fn us_federal_rule() -> TaxRule {
+    TaxRule {
+        rate_basis_points: 300, // 3% property tax
+        fixed_charge: 500,
+        exemption_amount: 50_000, // Homestead exemption
+        payment_due_period: 90 * 24 * 60 * 60 * 1000, // 90 days
+        reporting_frequency: ReportingFrequency::Annual,
+        penalty_basis_points: 500, // 5% penalty
+        requires_reporting: true,
+        requires_legal_documents: true,
+        active: true,
+    }
+}
+
+/// US jurisdiction profile
+/// - Local surcharge: 1%
+/// - Early payment discount: 1.5%
+/// - 30-day grace period
+pub fn us_federal_profile() -> JurisdictionProfile {
+    JurisdictionProfile {
+        surcharge_basis_points: 100, // 1% local surcharge
+        early_payment_discount_basis_points: 150, // 1.5% early payment discount
+        late_payment_grace_period: 30 * 24 * 60 * 60 * 1000, // 30 days grace
+        optimization_window: 60 * 24 * 60 * 60 * 1000, // 60 days for early payment
+        requires_digital_stamp: false,
+        authority_hash: [0u8; 32],
+    }
+}
+
+/// EU Standard tax rule configuration
+/// - Property tax rate: ~2% (varies by country)
+/// - Standard exemption: €30,000
+/// - Annual reporting
+/// - 60-day payment window (stricter)
+pub fn eu_standard_rule() -> TaxRule {
+    TaxRule {
+        rate_basis_points: 200, // 2% property tax (varies by country)
+        fixed_charge: 200,
+        exemption_amount: 30_000,
+        payment_due_period: 60 * 24 * 60 * 60 * 1000, // 60 days
+        reporting_frequency: ReportingFrequency::Annual,
+        penalty_basis_points: 400, // 4% penalty
+        requires_reporting: true,
+        requires_legal_documents: true,
+        active: true,
+    }
+}
+
+/// EU jurisdiction profile
+/// - Municipal surcharge: 0.5%
+/// - Early payment discount: 2%
+/// - 15-day grace period (stricter)
+/// - Digital stamp required (GDPR compliance)
+pub fn eu_standard_profile() -> JurisdictionProfile {
+    JurisdictionProfile {
+        surcharge_basis_points: 50, // 0.5% municipal surcharge
+        early_payment_discount_basis_points: 200, // 2% GDPR-compliant early payment
+        late_payment_grace_period: 15 * 24 * 60 * 60 * 1000, // 15 days (stricter)
+        optimization_window: 45 * 24 * 60 * 60 * 1000,
+        requires_digital_stamp: true, // EU digital compliance
+        authority_hash: [0u8; 32],
+    }
+}
+
+/// Asia Standard tax rule configuration
+/// - Property tax rate: ~4% (varies: Singapore 0-4%, Malaysia 0.5-2%, etc.)
+/// - Standard exemption: $20,000
+/// - Annual reporting
+/// - 60-day payment window
+pub fn asia_standard_rule() -> TaxRule {
+    TaxRule {
+        rate_basis_points: 400, // 4% (varies by country)
+        fixed_charge: 300,
+        exemption_amount: 20_000,
+        payment_due_period: 60 * 24 * 60 * 60 * 1000,
+        reporting_frequency: ReportingFrequency::Annual,
+        penalty_basis_points: 600, // 6% penalty (stricter enforcement)
+        requires_reporting: true,
+        requires_legal_documents: true,
+        active: true,
+    }
+}
+
+/// Asia jurisdiction profile
+/// - Local development charge: 1.5%
+/// - Early payment discount: 1%
+/// - 20-day grace period
+/// - Digital stamp required
+pub fn asia_standard_profile() -> JurisdictionProfile {
+    JurisdictionProfile {
+        surcharge_basis_points: 150, // 1.5% local development charge
+        early_payment_discount_basis_points: 100, // 1% early payment
+        late_payment_grace_period: 20 * 24 * 60 * 60 * 1000,
+        optimization_window: 50 * 24 * 60 * 60 * 1000,
+        requires_digital_stamp: true,
+        authority_hash: [0u8; 32],
+    }
+}
+
+/// Helper function to get jurisdiction code from country code
+pub fn jurisdiction_from_country(country: &[u8; 2]) -> Jurisdiction {
+    match country {
+        b"US" => Jurisdiction {
+            code: 1001,
+            country_code: *b"US",
+            region_code: 0,
+            locality_code: 0,
+        },
+        b"DE" | b"FR" | b"IT" | b"ES" | b"NL" => Jurisdiction {
+            // EU countries
+            code: 2001,
+            country_code: *country,
+            region_code: 0,
+            locality_code: 0,
+        },
+        b"SG" | b"MY" | b"TH" | b"JP" | b"KR" => Jurisdiction {
+            // Asian countries
+            code: 3001,
+            country_code: *country,
+            region_code: 0,
+            locality_code: 0,
+        },
+        _ => Jurisdiction {
+            code: 9999,
+            country_code: *country,
+            region_code: 0,
+            locality_code: 0,
+        },
+    }
+}