🎗️ Charity Donation Tracking System — Powered by Blockchain

The Charity Donation Tracking System is a decentralized smart contract module designed to ensure transparency, accountability, and traceability in charitable giving. Built on the SUI blockchain, this system allows donors, recipients, and authorities to participate in secure, verifiable donation flows — from contribution to validation and final delivery.

---

🧱 Overview

This module enables:

• Transparent donation tracking
• Validation of funds by trusted authorities
• Secure fund transfers to recipients
• Smart contract-enforced rules for cancellations, updates, and auditing

---

📦 Core Structures

Donation

Field	Description
id	Unique donation identifier
donor_address	Address of the donor
purpose_id	Identifier for the donation's intended purpose
amount	Total donation amount
balance	SUI token balance representing available funds
recipient_is_pending	true if the recipient hasn't yet claimed the donation
authority_validation	true if the donation is validated by an authority

---

AdminCap

Administrative capability token for managing core module functions.

---

Receipt

Field	Description
id	Unique identifier for the donation receipt
donation	ID of the associated donation
amount_donated	Amount recorded in the receipt

---

🛠️ Public Entry Functions

🔹 new

Creates a new donation with a specified purpose and amount. Returns a capability for managing the donation.

🔹 deposit

Allows the donor to deposit additional SUI into the donation, generating a receipt.

🔹 new_id

Updates the purpose_id of a pending donation. Restricted to the donor.

🔹 withdraw

Withdraws the balance of a donation. Only permitted for the donation's owner.

🔹 cancel_donation

Cancels a donation (if not yet received), returning the balance to the donor.

---

✅ Additional Functions

• validate_donation — Authorities can validate a donation
• mark_donation_received — Recipient confirms donation receipt
• get_donation_details — Fetch complete donation metadata
• update_donation_amount — Adjust the donation amount
• update_donation_purpose_id — Modify donation purpose ID
• is_donation_pending — Check if donation is awaiting recipient
• is_donation_validated — Check if validated by an authority
• update_receipt_amount_donated — Update donation amount in a receipt
• is_cap_owner_of_donation — Verify if capability owns the donation
• is_cap_owner_of_receipt — Verify receipt ownership
• get_donation_purpose_id — Retrieve donation's purpose
• get_receipt_donation_id — Get associated donation ID from receipt
• get_receipt_amount_donated — Fetch recorded amount from receipt
• get_donation_donor_address — Get donor address
• get_donation_recipient_pending_status — Check recipient pending status
• get_donation_authority_validation_status — Check validation status

---

🧪 Development Setup

🔧 Prerequisites

• Rust and Cargo
• SUI Blockchain — Set up a local SUI node for development

---

🏗️ Build & Deploy

1. Clone the repository:

   git clone <your-repo-url>
   cd charity-donation-tracking

2. Build the smart contracts:

   cargo build --release

3. Deploy to SUI blockchain (using CLI or deployment scripts):

   • Note the deployed contract address and any relevant object IDs for interaction

---

🚀 Usage Guide

💸 Making a Donation

• Call new with desired purpose_id and amount
• Fund the donation using deposit

🛡️ Validating Donations

• Authorities call validate_donation to approve donations

🎯 Receiving Donations

• Recipients use mark_donation_received after authority validation

❌ Canceling Donations

• Donors may cancel unclaimed donations with cancel_donation

🔄 Managing Purposes & Amounts

• Use update_donation_purpose_id or update_donation_amount before validation

---

🧪 Interacting with the Smart Contract

🧰 Using SUI CLI

• Use the SUI command-line interface to call contract functions
• Monitor transaction hashes and event logs for status updates

🖥️ Web Interface (Optional)

• Integrate with web apps using JavaScript libraries like Web3.js, Ethers.js, or SUI-compatible libraries
• Build UIs for donation tracking, validation dashboards, or NGO portals

---

✅ Key Benefits

• End-to-End Transparency
• Donor Control & Receipts
• Immutable Audit Trails
• Authority-Based Validation
• Decentralized & Trustless Infrastructure

---

📌 Conclusion

The Charity Donation Tracking Smart Contract enables a verifiable, decentralized donation process that protects donors, empowers recipients, and ensures compliance through transparent validation. Built on the SUI blockchain, it serves as a model for trust-based charitable systems in the web3 era.