Mar 2024Distributed Systems1 min read

Blockchain NGO Donation Tracking

Donors to a nonprofit had no way to check how their money was spent. I built Ethereum smart contracts that put each donation's lifecycle on-chain, with receipt hashes anyone can audit and payout attestations signed in MetaMask, without the platform ever holding donors' keys.

Donors could not see what happened to their money. Now every donation and payout is on a public ledger.

Solidity / Ethereum / Truffle / Web3.js / MetaMask

Ledger
Ethereum (on-chain state + event logs)
Custody model
Non-custodial (wallet-signed txs)

What it does

NGO fund flows are hard for donors to verify independently when the ledger is a private spreadsheet. This project modeled charitable allocations as Solidity contracts with explicit lifecycle states, stored receipt hashes on-chain, and left document bodies off-chain to keep gas costs down.

Constraints

  • Records must be tamper-evident on a public ledger
  • Platform must not hold private keys or donor funds
  • Gas cost of state writes needs to stay reasonable
  • Payout release needs multi-party attestation before disbursement

Decisions & tradeoffs

  1. State machine contracts: Ingested → Earmarked → Attested → Disbursed
  2. Hash-on-chain, documents off-chain: auditability without storing blobs in EVM storage
  3. Wallet integration (MetaMask / Web3.js): signing stays with participants
  4. Structured event logs: for external indexers / webhooks
Diagram
Sign and Send FundsState TransitionSubmit DisbursementProofSubmit Hash AttestationVerify AttestationVerify Log HashesDonor / GrantorSolidity auditcontractEthereumRecipientorganizationOff-Chain StoragePayout DisbursementPublic auditoror donor

Tradeoffs: on-chain writes buy public verifiability and cost gas. Non-custodial wallets remove platform key risk and add wallet UX friction versus card checkout.

What it demonstrates

  • Modeling real financial workflows as contract state machines
  • Separating what must be on-chain (attestation hashes) from what should not (documents)
  • Building a non-custodial client path with standard Web3 tooling