FundChain: Programmable Welfare Distribution System

Description: Government welfare schemes often face massive inefficiencies, delays, and corruption in fund distribution due to manual processing, lack of transparency, and poor beneficiary verification.

Objective: To develop a blockchain-based programmable system that ensures transparent, automated, and corruption-free welfare distribution.

Expected Impact:

• Efficient Delivery: Ensures fast and corruption-free welfare delivery via automated escrow releases.
• Enhanced Trust: Builds absolute public trust through immutable financial transparency and public ledgers.
• Reduced Overhead: Reduces administrative bottlenecks and removes manual disbursement errors.

---

Problem Statement

Traditional welfare distribution systems are plagued by fund misappropriation, extensive bureaucratic delays, and a severe lack of transparency. When aid is distributed as raw cash, there is no programmatic guarantee that the funds are spent on their intended purpose, leading to massive inefficiencies and a loss of public trust in aid initiatives.

---

Technical Architecture Overview

FundChain relies on a highly modular Smart Contract infrastructure written in Solidity 0.8.28, operating on the Ethereum Virtual Machine (EVM). The logic is segregated into four primary smart contracts:

1. Treasury.sol

The core vault and escrow manager of the system.

• Functionality: Holds the native ETH funds deposited by the government or NGO.
• Execution: Contains the heavily secured processPaymentWithSignature function which is responsible for verifying EIP-712 signatures, validating IPFS CIDs, checking boundaries, and transferring native ETH directly to merchants.

2. SchemeManager.sol

Defines and enforces the programmatic rules for the welfare initiatives.

• Functionality: Creates isolated welfare programs (e.g., "Flood Relief").
• Constraints Supported: Sets hard expiry timestamps, categorizes allowable merchant industries (e.g., "Healthcare", "Food"), and limits the maximum allocable amount per beneficiary.

3. BeneficiaryRegistry.sol

Manages identity and eligibility mapping for citizens.

• Functionality: Maps wallet addresses to verified beneficiary off-chain identities. Tracks precisely how much of their allocation limit they have consumed to prevent double-spending.

4. MerchantRegistry.sol

Controls vendor onboarding and categorization.

• Functionality: A stringent whitelisting registry. Merchants represent their operational category. If a merchant's category does not match the active Scheme requirements, the transaction statically reverts.

---

Detailed Mechanism: The Escrow Workflow

Traditional distributions provide raw cash, which leaves room for fund misappropriation. FundChain resolves this through a mathematically verifiable Escrow mechanism combined with a decentralized proof-of-work (IPFS invoice).

Step 1: Scheme Instantiation & Funding

1. The Admin delegates ETH into the Treasury.sol contract.
2. The Admin defines a "Scheme" via SchemeManager.sol, locking in parameters (e.g., 0.1 ETH maximum limit per beneficiary, expires in 30 days, restricted to Category: "Food").
3. Approved citizens are mapped as eligible inside BeneficiaryRegistry.sol.
4. Relevant vendors are whitelisted via MerchantRegistry.sol.

Step 2: Off-chain Beneficiary Authorization (EIP-712)

1. The beneficiary needs to purchase goods from a whitelisted merchant.
2. Instead of generating a standard blockchain transaction (which would cost gas fees the citizen may not possess), the beneficiary's wallet generates an EIP-712 cryptographically typed signature.
3. This signature encodes the amount, merchant address, and a unique nonce. It serves as undeniable mathematical proof that the beneficiary authorized the spend, but costs zero ETH to generate.

Step 3: IPFS Proof of Service Submission

1. The merchant fulfills the physical requirement (e.g., provides groceries).
2. The merchant captures an invoice/bill for the service and uploads the asset to Pinata (IPFS).
3. Pinata returns a permanent Content Identifier (CID), an immutable hash verifying the physical proof's existence.

Step 4: Verification and Funds Disbursement

1. The merchant submits their claim to the administrative dashboard, providing the requested amount, the beneficiary's signature, and the CID.
2. An Administrative authority reviews the IPFS proof.
3. The Admin executes processPaymentWithSignature on the Treasury.sol contract.
4. The smart contract validates:
   • Signature Recovery: Does the EIP-712 signature resolve perfectly to the eligible beneficiary's wallet address?
   • Limit enforcement: Is (Amount Requested + Prior Consumed Amount) <= Total Allocated Limit?
   • Merchant Validity: Is the merchant whitelisted, and does their category match the scheme's restrictions?
   • Data Integrity: Has the exact CID been passed as string data?
5. Upon successful validation of all programmatic checks, the smart contract routes the funds directly from the Treasury Escrow to the Merchant. The beneficiary never holds raw ETH.

---

Technology Stack Specifications

Blockchain Backend Subsystem

• Ecosystem: Ethereum EVM (Local Hardhat Node & Sepolia Testnet).
• Infrastructure: Google Cloud Web3 Ethereum Sepolia Faucet utilized for testnet deployments.
• Language: Solidity 0.8.28.
• Compiler & Framework: Hardhat & Hardhat Ignition for deployment pipelines.
• Security Primitives: OpenZeppelin v5 Contracts (Utilized for RBAC, ReentrancyGuard, EIP-712 signature verification, and ECDSA arithmetic).
• Client Libraries: Ethers.js v6.

Frontend Client Subsystem

• Framework: Next.js 16 App Router (React 19).
• Styling: Tailwind CSS v4, Framer Motion for micro-animations, shadcn/ui.
• Web3 Connectivity: Wagmi, Viem, RainbowKit, and MetaMask (for provider injection and EIP-712 off-chain signing).
• Data Visualization: Recharts for dashboard analytics.
• Decentralized Storage: Pinata SDK for IPFS media pinning.

---

Roles & Access Control Matrix

Role	Access Level	Description
DEFAULT_ADMIN_ROLE	Highest	Master administrator, manages funds, schemes, registries, and invokes escrow disbursements.
MERCHANT	Restricted	Whitelisted external entity. Can only receive funds upon successful contract validation.
BENEFICIARY	Read/Sign	Eligible citizen. Cannot enact state changes directly; provides read-only EIP-712 intent signatures.

---

Project Structure

FundChain/
├── blockchain/                 # Hardhat smart contract environment
│   ├── contracts/              # Solidity logic (.sol)
│   │   ├── Treasury.sol        # Core escrow and payment dispatcher
│   │   ├── SchemeManager.sol   # Welfare scheme rule enforcement
│   │   ├── BeneficiaryRegistry.sol # Citizen eligibility
│   │   └── MerchantRegistry.sol    # Vendor whitelisting
│   ├── ignition/modules/       # Declarative deployment strategies
│   ├── scripts/                # Utility and verification scripts
│   └── test/                   # Extensive Chai/Mocha test suites
└── frontend/                   # Next.js web application
    ├── src/
    │   ├── app/                # Next.js App Router endpoints & SSR pages
    │   ├── components/         # Reusable React components (shadcn/ui + custom)
    │   ├── config/             # Wagmi provider and contract ABI exports
    │   └── lib/                # Standard utility functions
    ├── public/                 # Static assets (icons, SVGs)
    └── package.json            # Client-side dependencies and scripts

---

Getting Started: Installation & Deployment

Global Prerequisites

• Node.js (v20+ recommended)
• A Web3 Wallet (e.g., MetaMask, Rabby)

1. Smart Contract Backend Setup

1. Open a terminal and navigate to the repository root, then into the blockchain folder:

   cd blockchain
   npm install

2. Compile the Solidity contracts:

   npx hardhat compile

3. Run the automated test suite to ensure contract validity:

   npx hardhat test

4. Start a local Ethereum RPC node:

   npx hardhat node

5. In a separate terminal, deploy the infrastructure to your local node:

   npx hardhat run scripts/deploy.js --network localhost

   Ensure you document the four deployed contract addresses logged in the terminal.

2. Required Environment Variables

Navigate down to the frontend/ directory. Duplicate the .env.example file and rename it to .env. Fill in the parameters:

# IPFS Storage
NEXT_PUBLIC_PINATA_JWT="your_pinata_jwt_here"

# Blockchain RPC Configuration
NEXT_PUBLIC_TESTNET_URL="http://127.0.0.1:8545"

# Deployed Contract Addresses (from Step 1)
NEXT_PUBLIC_TREASURY_ADDRESS="0x..."
NEXT_PUBLIC_SCHEME_ADDRESS="0x..."
NEXT_PUBLIC_BENEFICIARY_REG_ADDRESS="0x..."
NEXT_PUBLIC_MERCHANT_REG_ADDRESS="0x..."

3. Frontend Web Application Setup

1. Inside the frontend directory, install all client dependencies:

   npm install

2. Initialize the Next.js development server:

   npm run dev

3. Access the dashboard via http://localhost:3000.
4. Ensure your Web3 wallet is connected to the Localhost network (Chain ID: 31337).

---

Frequently Asked Questions (FAQ)

Q1: How does FundChain prevent a beneficiary from trading their welfare funds for cash from a corrupted merchant? A1: FundChain restricts spending exclusively to verified, whitelisted merchants under specific scheme categories. Furthermore, the escrow system demands an IPFS-uploaded receipt which is verified by an administrative role before the release of funds. The smart contract validates all limits, permissions, and ensures a proper proof CID is present on-chain.

Q2: Why does the beneficiary use EIP-712 signatures instead of sending a standard blockchain transaction? A2: By utilizing EIP-712 off-chain signatures, the beneficiary does not have to pay Ethereum gas fees to authorize a payment. The merchant or admin ultimately submits the transaction to the network, which vastly improves the user experience for citizens who might not own native ETH for gas.

Q3: Can the government reclaim unspent funds? A3: Yes. Schemes can be configured with an expiration timestamp. Because funds are stored in an Escrow Treasury rather than the beneficiary's raw wallet, unspent allocations can be seamlessly reclaimed natively by the smart contract once the deadline passes.

Q4: Is the system totally decentralized? A4: It is a hybrid model. The rules (limits, allocations, expiration) and execution logic are enforced via fully decentralized Smart Contracts. The storage of proofs leverages decentralized IPFS. However, the system relies on a semi-decentralized verification layer (Admin approval) to bridge the real-world utility gap of manually verifying physical bills.

Q5: What happens if a merchant attempts to reuse a beneficiary's EIP-712 signature for a subsequent claim? A5: The smart contracts handle replay attacks by maintaining a strict on-chain ledger to track consumed allocations and signature usages via nonces. Once an EIP-712 signature has been consumed and the limit bounds are registered, subsequent attempts using the same signature parameters will revert the transaction heavily.

Q6: What happens if the Treasury Smart Contract runs out of funds? A6: The Admin must actively fund the Treasury before allocations can be processed. If a claim is submitted and the Treasury lacks sufficient ETH to fulfill it, the processPaymentWithSignature function will fail during the on-chain validation stage. This provides a clear, programmatic reversion preventing partial payouts or debt accrual in the contract.

Q7: Can a merchant be delisted or removed if fraudulent activity is suspected? A7: Yes. The Role-Based Access Control (RBAC) and whitelisting functionalities provided by OpenZeppelin contracts allow an administrator to revoke a merchant's whitelist status. Once revoked, any future transactions attempting to direct funds to that merchant will statically fail on-chain.

Q8: Are the IPFS invoice records compliant with data privacy regulations? A8: In a production environment, uploaded proofs should strictly limit personal identifiable information. The CID acts as an immutable pointer. Depending on the exact jurisdiction (such as GDPR obligations), it is vital that only compliant data directly relevant to verifying the transaction amount and category is published to the public IPFS nodes.