Feature/multi regional tax jurisdiction mapping

PR_LEGAL_ENTITY.md

@@ -0,0 +1,40 @@
+# PR: Legal Entity Dissolution Auto-Pause (#208)
+
+## Summary
+Implements automatic pausing of grant streams when recipient entities are reported as dissolved by an authorized Legal Oracle, protecting DAO treasury from sending funds to legal void entities.
+
+## Features
+- **Legal Oracle Integration** - Authorized oracle can report entity status changes
+- **Auto-Pause Mechanism** - All active grants to dissolved entities are automatically frozen
+- **Status Caching** - 24-hour cache optimizes performance
+- **Security Controls** - Authorization and audit trail for all operations
+- **Event System** - Comprehensive events for monitoring and compliance
+
+## Key Functions Added
+- `set_legal_oracle_contract()` - Admin configures authorized Legal Oracle
+- `report_entity_dissolution()` - Oracle reports entity dissolution
+- `update_entity_status()` - Oracle updates entity to any status
+- `get_entity_status()` - Public query for entity status
+- `get_dissolved_entities()` - List all dissolved entities
+- `is_entity_dissolved()` - Check if entity is dissolved
+
+## Security
+- Only admin can set Legal Oracle address
+- Only authorized oracle can report status changes
+- Duplicate dissolution reports rejected
+- Full audit trail with events
+
+## Testing
+Comprehensive test suite covering:
+- Oracle setup and authorization
+- Entity dissolution and auto-pause
+- Multiple grants handling
+- Error conditions and edge cases
+- Status caching and validation
+
+## Files Changed
+- `contracts/grant_contracts/src/lib.rs` - Core implementation
+- `contracts/grant_contracts/src/test_legal_entity_monitor.rs` - Test suite
+- `LEGAL_ENTITY_DISSOLUTION_FEATURE.md` - Feature documentation
+
+Resolves #208

PR_TAX_JURISDICTION_DESCRIPTION.md

@@ -0,0 +1,206 @@
+# Multi-Regional Tax Jurisdiction Mapping Logic - Issue #207
+
+## Summary
+
+This PR implements a comprehensive tax jurisdiction mapping system that transforms Grant-Stream into a "Tax-Native" protocol capable of handling global tax compliance for a distributed workforce of developers while maintaining legal standing with international tax authorities.
+
+## 🎯 Objectives Achieved
+
+- ✅ **GranteeRecord Enhancement**: Added `jurisdiction_code` field to track tax jurisdictions
+- ✅ **Jurisdiction Registry**: Implemented DAO-updatable registry for global tax rates
+- ✅ **Dynamic Tax Withholding**: Tax rates automatically adjust based on jurisdiction
+- ✅ **Tax Treaty Support**: Built-in support for tax treaty benefits
+- ✅ **Comprehensive Testing**: Full test suite covering all scenarios
+
+## 🏗️ Architecture Overview
+
+### Core Components
+
+1. **JurisdictionInfo Structure**
+   ```rust
+   pub struct JurisdictionInfo {
+       pub code: String,                    // e.g., "US-CA", "GB-LDN"
+       pub name: String,                    // Human-readable name
+       pub tax_withholding_rate: u32,       // Rate in basis points (1/100%)
+       pub tax_treaty_eligible: bool,       // Treaty benefits available
+       pub documentation_required: bool,    // Additional docs needed
+       pub updated_at: u64,                 // Last update timestamp
+       pub updated_by: Address,             // Who updated this
+   }
+   ```
+
+2. **GranteeRecord Structure**
+   ```rust
+   pub struct GranteeRecord {
+       pub address: Address,                // Wallet address
+       pub jurisdiction_code: String,       // Tax jurisdiction
+       pub tax_id: Option<String>,          // SSN, EIN, etc.
+       pub tax_treaty_claimed: bool,        // Treaty benefits claimed
+       pub verified: bool,                  // Verification status
+       pub verification_documents: Option<[u8; 32]>, // Document hash
+       pub created_at: u64,                 // Creation time
+       pub updated_at: u64,                 // Last update
+   }
+   ```
+
+3. **TaxWithholdingRecord Structure**
+   ```rust
+   pub struct TaxWithholdingRecord {
+       pub grant_id: u64,                   // Associated grant
+       pub grantee: Address,                // Grantee address
+       pub gross_amount: i128,             // Gross payment
+       pub tax_rate: u32,                   // Applied tax rate
+       pub tax_withheld: i128,              // Amount withheld
+       pub net_amount: i128,               // Net payment
+       pub jurisdiction_code: String,        // Jurisdiction used
+       pub payment_date: u64,               // Payment timestamp
+       pub tax_report_id: Option<u64>,      // Report reference
+   }
+   ```
+
+## 🔧 Key Functions
+
+### DAO Governance Functions
+
+- **`register_jurisdiction()`**: Admin-only jurisdiction registration
+- **`update_jurisdiction()`**: Dynamic jurisdiction updates by DAO
+- **`set_tax_withholding_reserve()`**: Configure tax reserve address
+
+### Grantee Functions
+
+- **`register_grantee_jurisdiction()`**: Self-service jurisdiction registration
+- **`get_grantee_record()`**: Retrieve grantee tax information
+
+### Tax Processing Functions
+
+- **`calculate_tax_withholding()`**: Real-time tax calculation
+- **`process_payment_with_tax()`**: Automated tax withholding
+
+### Query Functions
+
+- **`get_jurisdiction()`**: Retrieve jurisdiction details
+- **`get_all_jurisdictions()`**: List all registered jurisdictions
+
+## 🧮 Tax Calculation Logic
+
+The system implements sophisticated tax calculation:
+
+1. **Base Rate Application**: Applies jurisdiction-specific base rate
+2. **Treaty Benefits**: 50% reduction for eligible treaty claims
+3. **Validation**: Ensures rates stay within configured bounds
+4. **Transparency**: Full audit trail of all calculations
+
+Example calculation:
+- Gross Amount: $1,000
+- US-CA Base Rate: 30% (3000 basis points)
+- Treaty Benefits: Yes (50% reduction)
+- Effective Rate: 15% (1500 basis points)
+- Tax Withheld: $150
+- Net Payment: $850
+
+## 🛡️ Safety Features
+
+### Input Validation
+- Jurisdiction code length limits (max 10 chars)
+- Tax rate bounds (0-50% maximum)
+- Required field validation
+
+### Access Control
+- Admin-only jurisdiction registration/updates
+- Grantee self-service for own records
+- DAO governance for registry changes
+
+### Audit Trail
+- Timestamped updates
+- Updater address tracking
+- Complete payment history
+
+## 📊 Storage Architecture
+
+### Data Keys
+```rust
+// Tax Jurisdiction keys
+JurisdictionRegistry(String),     // Code → JurisdictionInfo
+JurisdictionCodes,                // List of all codes
+GranteeJurisdiction(Address),     // Address → GranteeRecord
+TaxWithholdingReserve,            // Reserve address
+```
+
+## 🧪 Test Coverage
+
+Comprehensive test suite includes:
+
+- ✅ Jurisdiction registration and updates
+- ✅ Grantee jurisdiction registration
+- ✅ Tax withholding calculations
+- ✅ Payment processing with tax
+- ✅ Tax treaty benefits
+- ✅ Input validation and error scenarios
+- ✅ Edge cases and boundary conditions
+
+## 🌍 Global Compliance
+
+This implementation enables Grant-Stream to:
+
+1. **Handle Multi-Jurisdictional Workforce**: Support developers from any country
+2. **Maintain Legal Compliance**: Automatic tax withholding per local laws
+3. **Adapt to Regulatory Changes**: DAO can update rates as laws evolve
+4. **Provide Tax Transparency**: Clear reporting for grantee and foundation
+5. **Support Tax Treaties**: Reduce withholding for treaty beneficiaries
+
+## 📈 Economic Impact
+
+### For Grantees
+- Predictable net payments regardless of location
+- Automatic tax treaty benefit application
+- Clear tax documentation for filing
+
+### For Foundation
+- Compliance with international tax laws
+- Automated tax withholding and reporting
+- Reduced legal and administrative overhead
+
+### For Protocol
+- "Tax-Native" positioning enhances adoption
+- DAO-governed tax policy ensures adaptability
+- Transparent operations build trust
+
+## 🔮 Future Enhancements
+
+Potential future improvements:
+- Tax reporting integration with accounting systems
+- Multi-currency tax withholding
+- Advanced tax treaty calculations
+- Automated tax filing assistance
+- Integration with tax oracle services
+
+## 📋 Implementation Checklist
+
+- [x] Data structures defined
+- [x] Core functions implemented
+- [x] Access controls configured
+- [x] Tax calculation logic
+- [x] Payment processing with tax
+- [x] DAO governance functions
+- [x] Comprehensive test suite
+- [x] Error handling and validation
+- [x] Event emissions for transparency
+- [x] Storage optimization
+
+## 🚀 Deployment Notes
+
+1. **Initialization**: Admin must set up initial jurisdictions
+2. **Reserve Configuration**: Tax withholding reserve address required
+3. **Grantee Onboarding**: Users register their jurisdiction
+4. **Monitoring**: DAO oversees jurisdiction registry updates
+
+## 📚 Documentation
+
+- Function documentation included in code
+- Test cases serve as usage examples
+- Constants clearly defined for easy modification
+- Error codes comprehensive for debugging
+
+---
+
+**This PR establishes Grant-Stream as a truly global, tax-compliant funding protocol ready for international deployment.**