███████╗ █████╗ ██╗  ██╗ █████╗ ████████╗
╚══███╔╝██╔══██╗██║ ██╔╝██╔══██╗╚══██╔══╝
  ███╔╝ ███████║█████╔╝ ███████║   ██║   
 ███╔╝  ██╔══██║██╔═██╗ ██╔══██║   ██║   
███████╗██║  ██║██║  ██╗██║  ██║   ██║   
╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   

Zakat: The Definitive Islamic Alms Calculation Library

Zakat is a production-grade, type-safe Rust library designed to bridge Classical Fiqh with Modern Finance. It provides mathematically precise calculations for essentially all major wealth types, including cryptocurrencies, stocks, livestock, and professional income, while handling currency precision flawlessly using rust_decimal.

Features

• Type-Safe Precision: Zero floating-point errors. All calculations use rust_decimal.
• Comprehensive Coverage:
  • Maal (Wealth): Gold, Silver, Business/Trade, Agriculture, Livestock (Camels, Cows, Sheep), Mining & Rikaz.
  • Modern Assets: Stocks, Mutual Funds, and Cryptocurrencies (treated as liquid assets).
  • Income: Professional Income calculation (Gross & Net support).
  • Fitrah: Per-capita food staple calculation.
• Fiqh Compliant & Flexible:
  • Built-in default Nisab thresholds (e.g., 85g Gold).
  • Fully Configurable: Override thresholds to match specific Fatwa or regional standards.
  • Debt Deduction: Flexible logic to deduct liabilities before or after Nisab checks as per config.
• Portfolio Management: Builder pattern to aggregate diverse assets and calculate total Zakat due in one go.

Installation

Add this to your Cargo.toml:

[dependencies]
zakat = "0.1.0"
rust_decimal = "1.39"
rust_decimal_macros = "1.39"

Quick Start

1. Simple Business Calculation

use zakat::{ZakatConfig, CalculateZakat};
use zakat::maal::business::{BusinessAssets, BusinessZakatCalculator};
use rust_decimal_macros::dec;

fn main() {
    // 1. Configure Prices (e.g., Gold = $65/gram)
    let config = ZakatConfig::new(dec!(65.0), dec!(1.0));

    // 2. Define Assets
    let assets = BusinessAssets::new(
        dec!(50000.0), // Cash on Hand
        dec!(20000.0), // Inventory Value
        dec!(5000.0),  // Receivables
        dec!(1000.0)   // Short Term Debt
    );

    // 3. Calculate
    let calculator = BusinessZakatCalculator::new(assets, &config).unwrap();
    let result = calculator.calculate_zakat(None).unwrap();

    if result.is_payable {
        println!("Zakat Due: ${}", result.zakat_due);
    } else {
        println!("Nisab not reached.");
    }
}

2. Portfolio Management (The "Enterprise" Way)

Handling a complex user scenario (e.g., "Mr. Ahmad") who has income, gold, investments, and debts.

use zakat::{ZakatConfig, ZakatPortfolio, WealthType};
use zakat::maal::precious_metals::PreciousMetal;
use zakat::maal::investments::{InvestmentAssets, InvestmentType};
use zakat::maal::income::{IncomeZakatCalculator, IncomeCalculationMethod};
use rust_decimal_macros::dec;

fn main() {
    // Global Config
    let config = ZakatConfig::new(dec!(65.0), dec!(1.0));

    // Initialize Portfolio
    let portfolio = ZakatPortfolio::new()
        // Add Monthly Income (Gross Method)
        .add_calculator(IncomeZakatCalculator::new(
            dec!(5000.0), 
            dec!(0.0), 
            IncomeCalculationMethod::Gross, 
            &config
        ).unwrap())
        // Add Gold Stash
        .add_calculator(PreciousMetal::new(
            dec!(100.0), // 100 grams
            WealthType::Gold, 
            &config
        ).unwrap())
        // Add Crypto Portfolio with Debt Deduction
        .add_calculator_with_debt(InvestmentAssets::new(
            dec!(20000.0), 
            InvestmentType::Crypto, 
            &config
        ).unwrap(), dec!(2000.0)); // Deduct $2k personal debt

    // Execute
    let result = portfolio.calculate_total().unwrap();

    println!("Total Zakat Due: ${}", result.total_zakat_due);
    // Output breakdown...
}

Advanced Configuration (Custom Nisab)

Different regions or scholar councils may have different standards for Nisab. You can override defaults easily:

use zakat::ZakatConfig;
use rust_decimal_macros::dec;

let mut config = ZakatConfig::new(dec!(65.0), dec!(1.0));

// Override Gold Nisab to 87g (some opinions) instead of default 85g
config.nisab_gold_grams = Some(dec!(87.0));

// Override Agriculture Nisab
config.nisab_agriculture_kg = Some(dec!(700.0));

Supported Modules

Contributing

Contributions are welcome! Please ensure you:

1. Add unit tests for any new logic.
2. Maintain rust_decimal usage for precision.
3. Run cargo test before submitting.

License

This project is licensed under the MIT License - see the LICENSE file for details.