---

FairFund – Blockchain-based Community Funding Platform

FairFund is a blockchain-based platform for community-driven funding.
Users can deploy funding vaults, deposit funds, vote on proposals, and distribute funds in a decentralized manner.

---

📚 Table of Contents

1. Introduction
2. Technology Stack
3. Architecture
4. Run Locally
5. Usage Guide
6. Smart Contract Documentation
7. Deployment
8. Future Improvements
9. Contributing
10. Community

---

📝 Introduction

FairFund is a blockchain-based platform for community-driven funding.
Users can:

• Deploy funding vaults
• Deposit and lock funds
• Create proposals
• Vote and determine fund distribution
• Withdraw results transparently

The platform uses a decentralized voting mechanism to decide which proposals receive funding.

---

🛠 Technology Stack

• Frontend: Next.js, TailwindCSS, ShadCN UI
• Backend: Next.js API Routes, Prisma ORM, NextAuth, SIWE, Web3Modal
• Blockchain: Foundry, Solidity
• Database: PostgreSQL
• Tools: Wagmi, Viem, React Hook Form

---

🏗 Architecture

---

🧪 Run Locally

Prerequisites

1. Foundry Setup
   Install using: https://getfoundry.sh/

2. Node.js Setup
   Guide: https://nodejs.org/en/learn/getting-started/introduction-to-nodejs

3. Docker Setup
   Guide: https://docs.docker.com/get-started/introduction/

---

Smart Contracts

1. Navigate to the Blockchain Directory:

   cd app/blockchain

2. Install Dependencies:

   forge install

3. Run Tests:

   forge test

4. Run Local Anvil Chain:

   anvil

5. Deploy Mock Smart Contracts:

   make mock-all

   Note: This will automatically update relevant contract addresses and ABIs for smart contract in web-app folder.

6. Deploy to the Testnet: (Optional)

   • Ensure you have a .env file set up. You can use .env.example as a template.
   • Load the environment variables:

   source .env

   • Deploy the contract:

   make deploy-sepolia

Frontend

1. Navigate to the Web App Directory:

   cd app/web-app

2. Install Dependencies:

   npm install

3. Update the environment variables: Create a .env file in the web-app directory and add all the values. You can use .env.example as a template.

   PostgreSQL:

   • If using Docker (with the provided docker-compose.yml), the defaults provided for POSTGRES_PRISMA_URL and POSTGRES_URL_NON_POOLING provided in .env.example will work.
   • If using a local instance of PostgreSQL, update the POSTGRES_PRISMA_URL and POSTGRES_URL_NON_POOLING with the correct connection url for the local postgreSQL.

   NextAuth:

   • Generate a secure NEXTAUTH_SECRET by running the following command in the terminal

   openssl rand -base64 32

   • For local development NEXTAUTH_URL will be http://localhost:3000

4. To start local instance of postgreSQL database (with docker):

   1. Start docker desktop
   2. Run docker compose up

5. Run the Development Server:

   npm run dev

6. Access the Web App:

   • Open your browser and navigate to http://localhost:3000.

Usage Guide

Our platform supports three types of users: Vault Creators, Proposal Creators, and Voters/Community Members. Here's how each user type can navigate and use the application:

Vault Creators

Vault.Creator.mp4

1. Getting Started

   • On the landing page, click "Get Started" to access the dashboard
   • Connect your wallet and sign in with Ethereum

2. Creating a Vault

   • Click the "Create" button and select "Vault" from the dropdown
   • Choose a space for your vault (multiple vaults can exist in one space)
   • Enter the vault description, token configurations, and funding parameters
   • Review and submit the proposal (requires a wallet transaction)

3. Optional: Add Funds

   • After creation, you can immediately add funds to your vault

4. Vault Management

   • You'll be redirected to the vault page to view all details

Proposal Creators

Proposal.Creator.mp4

1. Getting Started

   • On the landing page, click "Get Started" to access the dashboard
   • Connect your wallet and sign in with Ethereum

2. Creating a Proposal

   • Click the "Create" button and select "Proposal" from the dropdown
   • Search and select the vault you want to create a proposal for
   • Enter the proposal description, minimum and maximum request amounts, and recipient address
   • Review the information and submit

3. Tracking Proposals

   • View your created proposals in the "My Activity" page or on the vault details page

Voters/Community Members

Community.Member.small.mp4

1. Accessing Vaults

   • On the landing page, click "Get Started" to access the dashboard
   • Click "Spaces" in the navbar to view available spaces
   • Select a space and then choose a vault within that space

2. Participating in a Vault

   • On the vault page, register to vote
   • Deposit tokens for distribution
   • Create new proposals (if desired)
   • After the tally date, withdraw remaining funds (if applicable)

3. Viewing Results

   • After the tally date, results page will be accessible to view the distribution statistics and other vault-related information

Smart Contract Documentation

Smart contract documentation can be found here.

Deployment

Test Deployed Instances

• Smart Contract:
  • Mainnets
    • Polygon Mainnet
  • Testnets
    • ETC Mordor
    • Polygon Amoy
• Frontend: FairFund

Future Improvements

• Add support for multiple blockchains
• Audit smart contracts
• Refactor smart contracts for better readability and extensibility. detailed issue
• Implement functionality to sponser gas for voting and proposal creation
• Optimize smart contracts further
• Add comments functionality on proposals page
• Enable editing of space, proposal, and vault descriptions
• Implement moderation functionality for spaces (control who can create vaults and proposals)
• Add ability to delegate moderation functionality to users other than creator of the space
• Implement various fund distribution mechanisms

We welcome additional suggestions! Join our Discord: Discord Link

Contributing

1. Create an issue on GitHub
2. Discuss your ideas on our project's Discord channel (#fairfund) in Stability Nexus Server (if required).
3. Wait for the issue to be assigned to you
4. Fork the repository
5. Set up the project locally using this Run Locally Guide
6. Create a new branch following this format: type/brief-description
   • Types: fix, feat, chore, perf, or refactor
   • Example: feat/add-space-moderation-functionality
7. Switch to the new branch
8. Make your changes
9. Commit your changes
10. Decide on the scope of the change:

• Small changes (minor fixes, documentation updates, small UI tweaks) → Make a pull request directly to main
• Big changes (new features, major refactors) → Make a pull request to develop branch

11. Provide a detailed description of your changes in the PR, including videos and images for visible UI changes.

Important Guidelines

Code Quality and Testing

• Take your time to create high-quality PRs - do not commit code hastily
• Ensure all changes are thoroughly tested before submission
• Avoid introducing code smells
• Do not submit untested code as it complicates the review process
• Only include code in the commit that is intentional. Avoid using git add . to prevent unintended changes from being committed.

Pull Request Rules

• Small frontend changes (< 20 lines) or documentation updates can be submitted without prior assignment
• Unassigned PRs will be closed without review
• Check existing issues and PRs to avoid duplicating efforts
• Tag the maintainer if your PR is unattended for:
  • 1 week for small contributions
  • 2 weeks for larger contributions

Timeline and Progress

• Issues should be completed within:
  • 5 days for small tasks
  • 15 days for complex tasks
• Provide regular progress updates in issue/PR comments if work extends beyond expected timeline
• Issues may be reassigned if not completed within the specified timeframe

Need Help?

If you have questions or need clarification, please ask on Discord.

Community

• Stability Nexus
• AOSSIE

© 2025 The Stable Order