Skip to content

TAX_JURISDICTION_IMPLEMENTATION.md

Latest commit

 

History

History
245 lines (191 loc) · 8.07 KB

TAX_JURISDICTION_IMPLEMENTATION.md

File metadata and controls

245 lines (191 loc) · 8.07 KB

Multi-Regional Tax Jurisdiction Mapping Logic - Implementation Summary

Overview

This implementation addresses Issue #207 by creating a comprehensive tax jurisdiction mapping system that makes Grant-Stream a "Tax-Native" protocol capable of handling global tax compliance for developers worldwide.

Features Implemented

1. Jurisdiction Registry System

Location: contracts/grant_contracts/src/lib.rs (lines 387-395)

#[derive(Clone)]
#[contracttype]
pub struct JurisdictionInfo {
    pub code: String,           // Jurisdiction code (e.g., "US-CA", "GB-LDN")
    pub name: String,           // Human-readable name
    pub tax_withholding_rate: u32, // Tax rate in basis points (1/100 of percent)
    pub tax_treaty_eligible: bool, // Whether tax treaty benefits apply
    pub documentation_required: bool, // Whether additional documentation is required
    pub updated_at: u64,        // Last update timestamp
    pub updated_by: Address,    // Who updated this jurisdiction
}

Key Functions:

  • register_jurisdiction() - Register new tax jurisdiction
  • update_jurisdiction() - Update existing jurisdiction tax rates
  • get_jurisdiction() - Retrieve jurisdiction information
  • get_all_jurisdictions() - List all registered jurisdictions

2. Grantee Records with Jurisdiction

Location: contracts/grant_contracts/src/lib.rs (lines 399-408)

#[derive(Clone)]
#[contracttype]
pub struct GranteeRecord {
    pub address: Address,           // Grantee's wallet address
    pub jurisdiction_code: String,   // Tax jurisdiction code
    pub tax_id: Option<String>,      // Tax identifier (SSN, EIN, etc.)
    pub tax_treaty_claimed: bool,    // Whether tax treaty benefits are claimed
    pub verified: bool,              // Whether jurisdiction information is verified
    pub verification_documents: Option<[u8; 32]>, // Hash of verification documents
    pub created_at: u64,             // Record creation timestamp
    pub updated_at: u64,             // Last update timestamp
}

Key Functions:

  • register_grantee_jurisdiction() - Register grantee's tax jurisdiction
  • get_grantee_record() - Retrieve grantee's tax information

3. Tax Withholding Calculation Engine

Location: contracts/grant_contracts/src/lib.rs (lines 4242-4265)

pub fn calculate_tax_withholding(
    env: Env,
    grantee_address: Address,
    gross_amount: i128,
) -> Result<(i128, i128, u32), Error>

Features:

  • Automatic tax rate calculation based on jurisdiction
  • Tax treaty benefit application (50% reduction when eligible)
  • Precise basis-point calculations for accuracy
  • Returns tax withheld, net amount, and effective tax rate

4. Payment Processing with Tax Withholding

Location: contracts/grant_contracts/src/lib.rs (lines 4280-4328)

pub fn process_payment_with_tax(
    env: Env,
    grant_id: u64,
    grantee_address: Address,
    gross_amount: i128,
    token_address: Address,
) -> Result<u64, Error>

Features:

  • Automatic tax withholding from payments
  • Tax record creation for compliance tracking
  • Separate tax reserve account management
  • Event emission for transparency

5. Tax Withholding Records

Location: contracts/grant_contracts/src/lib.rs (lines 412-422)

#[derive(Clone)]
#[contracttype]
pub struct TaxWithholdingRecord {
    pub grant_id: u64,               // Associated grant ID
    pub grantee: Address,            // Grantee address
    pub gross_amount: i128,          // Gross payment amount
    pub tax_rate: u32,               // Tax withholding rate (basis points)
    pub tax_withheld: i128,          // Amount withheld for taxes
    pub net_amount: i128,            // Net amount paid to grantee
    pub jurisdiction_code: String,   // Jurisdiction used for calculation
    pub payment_date: u64,           // Payment timestamp
    pub tax_report_id: Option<u64>,  // Reference to tax report
}

Constants and Validation

Location: contracts/grant_contracts/src/lib.rs (lines 55-58)

const MAX_JURISDICTION_CODE_LENGTH: u32 = 10; // Maximum jurisdiction code length
const DEFAULT_TAX_WITHHOLDING_RATE: u32 = 0;   // 0% default withholding rate
const MAX_TAX_WITHHOLDING_RATE: u32 = 5000;    // 50% maximum withholding rate

Storage Keys

Location: contracts/grant_contracts/src/lib.rs (lines 716-721)

// Tax Jurisdiction keys
JurisdictionRegistry(String), // Maps jurisdiction code to tax rate
JurisdictionCodes,           // List of all jurisdiction codes
GranteeJurisdiction(Address), // Maps grantee address to jurisdiction code
TaxWithholdingReserve,       // Reserve for tax withholding funds
JurisdictionRegistryContract, // Address of jurisdiction registry contract

Error Handling

Location: contracts/grant_contracts/src/lib.rs (lines 811-818)

// Tax Jurisdiction errors
JurisdictionNotFound = 74,
JurisdictionAlreadyExists = 75,
InvalidJurisdictionCode = 76,
InvalidTaxRate = 77,
JurisdictionRegistryNotSet = 78,
TaxWithholdingFailed = 79,

DAO Governance Integration

The system includes DAO governance functions for updating the jurisdiction registry:

  1. Admin Authorization: Only authorized administrators can register/update jurisdictions
  2. Audit Trail: All changes track who made updates and when
  3. Validation: Strict validation of jurisdiction codes and tax rates
  4. Transparency: All jurisdiction information is publicly queryable

Tax Treaty Support

The implementation supports tax treaty benefits:

  1. Treaty Eligibility: Jurisdictions can be marked as treaty-eligible
  2. Treaty Claims: Grantees can claim treaty benefits
  3. Automatic Reduction: 50% tax rate reduction for treaty beneficiaries
  4. Documentation: Support for verification document hashes

Testing

Comprehensive test suite implemented in test_tax_jurisdiction.rs:

  1. Unit Tests: All core functions tested
  2. Integration Tests: End-to-end payment processing
  3. Error Scenarios: All error conditions tested
  4. Edge Cases: Boundary conditions and validation

Security Considerations

  1. Access Control: Admin-only functions for jurisdiction management
  2. Input Validation: Strict validation of all inputs
  3. Math Safety: Overflow protection in calculations
  4. Audit Trail: Complete audit trail for compliance

Usage Examples

Registering a New Jurisdiction

// Register US-CA jurisdiction with 30% tax rate
contract.register_jurisdiction(
    env,
    "US-CA".to_string(),
    "United States - California".to_string(),
    3000, // 30% in basis points
    true,  // treaty eligible
    true,  // documentation required
);

Registering a Grantee

// Register grantee with tax information
contract.register_grantee_jurisdiction(
    env,
    grantee_address,
    "US-CA".to_string(),
    Some("123-45-6789".to_string()),
    true, // treaty claimed
);

Processing Payment with Tax

// Process $1000 payment with automatic tax withholding
let tax_record_id = contract.process_payment_with_tax(
    env,
    grant_id,
    grantee_address,
    100000, // $1000 in smallest unit
    token_address,
);

Benefits

  1. Global Compliance: Supports tax compliance for global workforce
  2. Automated Withholding: Automatic tax calculation and withholding
  3. Treaty Support: Built-in support for tax treaty benefits
  4. DAO Governed: Jurisdiction registry managed by DAO
  5. Transparent: All tax information publicly queryable
  6. Auditable: Complete audit trail for tax authorities
  7. Flexible: Easy to add new jurisdictions and update rates

Future Enhancements

  1. Tax Reporting: Automated tax report generation
  2. Multi-Token Support: Tax withholding for multiple token types
  3. Advanced Treaties: Complex treaty benefit calculations
  4. Integration APIs: External tax service integrations
  5. Compliance Tools: Enhanced compliance monitoring tools

This implementation establishes Grant-Stream as a truly "Tax-Native" protocol capable of handling the complex tax requirements of a global developer workforce while maintaining perfect legal standing with international tax authorities.