AidLedger

From donation to delivery, make every milestone accountable. AidLedger holds funds in escrow, requires verifier approval for payouts, and makes every release traceable on Polygon.

Comment

Inspiration

A donation receipt shows that money moved, but it rarely explains what happened next. What work was promised? What evidence supports a payment? Who reviewed it? I built AidLedger to connect those questions in one workflow: campaign funding, milestone evidence, verifier decisions, and staged releases. The goal is to make aid disbursement easier to inspect while being honest about what blockchain can and cannot prove.

What it does

AidLedger lets an organizer create a campaign with three milestone budgets, a fixed recipient, and a designated verifier. Donors contribute funds to smart-contract escrow. For each milestone, the organizer submits evidence. The verifier reviews the current evidence revision and approves or rejects it. Only after approval can the organizer release that milestone’s budget to the designated recipient. Milestones progress in order. The verifier’s wallet must differ from both the organizers and recipient’s wallets. This enforces separate permissions, although it does not establish that different people control those accounts. The dashboard shows campaign balances, evidence, review notes, and transaction history. Exact evidence and review content are stored in PostgreSQL, while their cryptographic fingerprints are recorded on chain. AidLedger also includes transaction recovery. Saved request IDs and transaction hashes help users check interrupted operations, and the contract prevents a successfully processed request ID from executing again.

How I built it

The smart contracts are written in Solidity, with automated tests using Hardhat and Node.js covering campaign validation, permissions, contributions, milestone transitions, and request-ID protection. The deployed contract runs on Polygon Amoy. A Node.js API using ethers.js runs on Northflank, alongside PostgreSQL for evidence, review content, and the persistent request journal. The frontend uses Next.js, React, TypeScript, and Tailwind CSS and is deployed on Vercel. MetaMask signs and broadcasts user transactions; the backend prepares transaction data and reconciles results without receiving users’ private keys.

Challenges I ran into

The hardest problems appeared at the boundaries between the wallet, browser, API, database, and blockchain. An interrupted response does not necessarily mean a transaction failed. Treating it as a failure and immediately retrying can create confusion or duplicate actions. I added persistent request tracking, status checks, and recovery controls to help distinguish confirmed outcomes from unresolved requests. Deployment also required troubleshooting RPC connection failures, gas estimation, frontend configuration, and wallet account permissions. Switching accounts inside MetaMask did not always switch the account connected to the application, which made clear wallet identity checks especially important.

Accomplishments that I’m proud of

AidLedger completed a live testnet workflow: campaign creation, funding, evidence submission, verifier approval, and milestone release. The fictional “Clean Water for Ekosodin — Demo” campaign received its full 0.004 test POL funding goal. Its first milestone released 0.001 test POL, leaving 0.003 test POL in escrow for the remaining milestones. The dashboard displayed the released milestone, matching evidence fingerprint, verifier note, and confirmed transaction history. This demonstrated the integration of the deployed frontend, API, database, wallet, and smart contract.

I am also proud of building recovery into the user experience, so an uncertain transaction result can be investigated rather than hidden or blindly retried.

What I learned

A Web3 application’s reliability depends on much more than its smart contract. Wallet permissions, persistent storage, frontend state, RPC availability, and deployment configuration all affect whether users can complete a workflow confidently. I also learned to distinguish record integrity from real-world truth. A matching fingerprint shows that evidence matches the committed record; it does not prove that a borehole was drilled or supplies were delivered. The verifier’s judgment and accountability remain essential.

What’s next for AidLedger

Next steps include richer evidence attachments, stronger verifier identity and accountability, multiple-reviewer approval options, dispute and refund workflows, and improved wallet onboarding. Before considering real funds or mainnet deployment, the project needs an independent security review, stronger operational safeguards, and evaluation with potential aid-sector users.

AidLedger is currently a testnet prototype. The demonstration campaign and evidence are fictional, and Polygon Amoy test POL has no real monetary value.

Built With

Share this project:

Updates

Submission history