🌟 Stellar Crowdfunding Platform (Lumina Fund)

A secure, milestone-based decentralized crowdfunding platform built on the Stellar network.

Features • Quick Start • User Guides • Documentation • Contributing • Roadmap

---

📑 Table of Contents

• Overview
• Features
• Architecture
• Tech Stack
• Getting Started
• Project Structure
• Smart Contracts
• Frontend Application
• Testing
• CI/CD
• Deployment
• Configuration
• Contributing
• Roadmap
• FAQ
• License

---

🎯 Overview

Lumina Fund is a decentralized application that enables entrepreneurs, creators, and NGOs to raise capital transparently on the Stellar blockchain. By leveraging smart contracts, Lumina ensures that funds are released based on predefined milestones, protecting backers and ensuring accountability.

Why Lumina Fund?

• 🔒 Milestone Escrow: Funds are locked in a smart contract and released only when backers approve milestones.
• 💸 Low Fees: Leverage Stellar's ultra-low transaction costs for micropayments and donations.
• 🌍 Global Reach: Borderless fundraising accessible to anyone with an internet connection.
• 🤝 Trustless: Non-custodial architecture means the platform never holds your funds.
• 📈 Real-time Tracking: On-chain transparency for all raised funds and expenditures.

---

✨ Features

Current Features (MVP)

🏦 Campaign Smart Contract

• ✅ Create funding campaigns with strict deadlines and funding goals.
• ✅ Support for XLM and custom Stellar assets (USDC, EURC).
• ✅ Milestone-based fund unlocking.
• ✅ Automated refunds if funding goals are not met.
• ✅ Backer voting power proportional to contribution size.

🎨 Frontend Application

• ✅ Wallet connection via Freighter & Albedo.
• ✅ Campaign discovery dashboard.
• ✅ Interactive campaign creation wizard.
• ✅ Mobile-first and responsive design.
• ✅ Real-time progress bars and funding metrics.

🖼️ Campaign Media

• ✅ Decentralized storage of campaign assets (images, pitch decks) via IPFS.
• ✅ On-chain metadata referencing IPFS CIDs.

🧪 Testing & Quality

• ✅ Comprehensive unit tests for Rust contracts.
• ✅ E2E testing for the React frontend.
• ✅ Property-based testing for voting mechanics.

---

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (React/TS)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Campaign   │  │   Backer     │  │  Milestone   │     │
│  │  Dashboard   │  │   Gateway    │  │   Voting     │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  Stellar Network (Soroban)                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │          Crowdfund Contract (Rust)                   │   │
│  │  - create_campaign()                                 │   │
│  │  - pledge_funds()                                    │   │
│  │  - vote_milestone()                                  │   │
│  │  - claim_funds() / refund()                          │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

🛠️ Tech Stack

Smart Contracts

Technology	Version	Purpose
Rust	2021	Smart contract programming
Soroban SDK	21.0.0	Stellar smart contract framework
proptest	1.4	Property-based testing

Frontend

Technology	Version	Purpose
React	19.2.0	UI framework
TypeScript	5.9.3	Type safety
Vite	8.0.0-beta	Build tool
Tailwind CSS	4.1.18	Styling framework

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• Rust 1.70+ with wasm32-unknown-unknown target
• Soroban CLI
• Freighter Wallet

Installation

1. Clone the repository

git clone https://github.com/Lumina-Network/lumina-fund.git
cd lumina-fund

2. Install frontend dependencies

cd frontend
npm install

3. Build the smart contract

cd ../contracts/crowdfund
cargo build --target wasm32-unknown-unknown --release

---

📁 Project Structure

lumina-fund/
├── contracts/                   # Smart contracts
│   ├── crowdfund/               # Campaign logic
│   │   ├── src/
│   │   │   ├── lib.rs           # Main contract logic
│   │   │   ├── storage.rs       # State management
│   │   │   └── types.rs         # Custom structs and enums
│   │   └── Cargo.toml
├── frontend/                    # React frontend
│   ├── src/
│   │   ├── components/          # UI Elements
│   │   ├── hooks/               # Custom Soroban hooks
│   │   └── services/            # API and Wallet integrations
├── scripts/                     # Deployment scripts
└── README.md

---

📜 Smart Contracts

Crowdfund Contract

Core Functions

create_campaign

Initializes a new campaign with a specific funding goal and deadline.

pub fn create_campaign(
    env: Env,
    creator: Address,
    title: String,
    target_amount: i128,
    deadline: u64,
    token: Address,
) -> Address

pledge_funds

Allows users to contribute tokens to an active campaign.

pub fn pledge_funds(
    env: Env,
    backer: Address,
    campaign_id: Address,
    amount: i128,
) -> Result<(), Error>

claim_funds

Callable by the creator if the funding goal is reached and deadlines/milestones are met.

pub fn claim_funds(
    env: Env,
    creator: Address,
    campaign_id: Address,
) -> Result<(), Error>

---

🤝 Contributing

Please see our Contributing Guidelines for details. We welcome PRs for new features, bug fixes, and documentation improvements!

🗺️ Roadmap

• Q2 2026: Mainnet MVP Launch & Code Audit
• Q3 2026: Integration with fiat on-ramps
• Q4 2026: Multi-signature campaign management
• Q1 2027: Lumina DAO for decentralized platform governance

📄 License

This project is licensed under the MIT License.