Fund-My-Cause

A decentralized crowdfunding platform built on the Stellar network using Soroban smart contracts. Fund-My-Cause lets anyone create a campaign on-chain, accept contributions in XLM or any Stellar token, and automatically release or refund funds based on whether the goal is met.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Next.js Frontend (TypeScript)               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │   Navbar     │  │ ProgressBar  │  │  PledgeModal         │  │
│  │ (Freighter)  │  │ (Campaign)   │  │  (Contribution)      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│         │                 │                      │              │
│         └─────────────────┴──────────────────────┘              │
│                           │                                     │
│                    WalletContext                                │
│                  (Freighter API)                                │
└─────────────────────────────────────────────────────────────────┘
                            │
                            │ (sign transactions)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Stellar RPC Endpoint                         │
│              (Testnet: https://soroban-testnet.stellar.org)     │
└─────────────────────────────────────────────────────────────────┘
                            │
                            │ (invoke contracts)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Soroban Smart Contracts                       │
│  ┌──────────────────────┐  ┌──────────────────────────────────┐ │
│  │  Crowdfund Contract  │  │  Registry Contract               │ │
│  │  - initialize()      │  │  - register(campaign_id)         │ │
│  │  - contribute()      │  │  - list_campaigns()              │ │
│  │  - withdraw()        │  │  - get_campaign_count()          │ │
│  │  - refund_single()   │  │                                  │ │
│  │  - get_stats()       │  │                                  │ │
│  └──────────────────────┘  └──────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                            │
                            │ (store state)
                            ▼
                    Stellar Ledger

How It Works

A creator deploys and initializes a campaign with a funding goal, deadline, and minimum contribution.
Contributors pledge tokens before the deadline.
If the goal is met by the deadline, the creator withdraws the funds (minus an optional platform fee).
If the goal is not met, each contributor individually claims their refund via a pull-based model.

Monorepo Structure

Fund-My-Cause/
├── apps/
│   └── interface/          # Next.js 16 frontend (TypeScript + Tailwind)
│       ├── src/
│       │   ├── app/        # Next.js App Router pages & layouts
│       │   ├── components/ # UI components (Navbar, ProgressBar, PledgeModal, etc.)
│       │   ├── context/    # WalletContext (Freighter wallet integration)
│       │   ├── lib/        # Soroban contract client helpers
│       │   └── types/      # Shared TypeScript types
│       └── package.json
├── contracts/
│   └── crowdfund/          # Soroban smart contract (Rust)
│       ├── src/
│       │   └── lib.rs      # Core contract logic
│       └── Cargo.toml
│   └── registry/           # Soroban registry contract for campaign discovery
│       ├── src/
│       │   └── lib.rs      # register/list campaign contract IDs
│       └── Cargo.toml
├── scripts/
│   └── deploy.sh           # Automated deploy + initialize script
├── .github/
│   └── workflows/
│       └── rust_ci.yml     # CI: build WASM + run tests
├── Cargo.toml              # Rust workspace config
├── package.json            # Node workspace config
└── README.md

Smart Contract

The Soroban contract lives in contracts/crowdfund/src/lib.rs and exposes the following interface:

Function	Description
`initialize(creator, token, goal, deadline, min_contribution, title, description, social_links, platform_config)`	Create a new campaign
`contribute(contributor, amount)`	Pledge tokens before the deadline
`update_metadata(title, description, social_links)`	Update campaign metadata if status is Active
`withdraw()`	Creator claims funds after a successful campaign
`refund_single(contributor)`	Contributor claims their own refund if goal not met
`get_stats()`	Returns `CampaignStats` (total raised, progress bps, contributor count, etc.)
`total_raised()`	Current total raised
`goal()`	Campaign funding goal
`deadline()`	Campaign deadline (ledger timestamp)
`contribution(contributor)`	Contribution amount for a specific address
`min_contribution()`	Minimum allowed contribution
`title()` / `description()`	Campaign metadata
`social_links()`	Campaign social URLs
`version()`	Contract version number

Pull-based Refund Model

Rather than a single transaction refunding all contributors (which would fail at scale), each contributor calls refund_single to claim their own refund. This is gas-efficient, scalable, and avoids a single point of failure.

Platform Fee

An optional PlatformConfig can be set at initialization with a fee in basis points (e.g. 250 = 2.5%). The fee is deducted from the creator's payout on withdrawal and sent to the platform address.

Frontend

The interface is a Next.js 16 app using the App Router, Tailwind CSS v4, and Freighter wallet integration.

Key components:

Navbar — wallet connect/disconnect via Freighter
ProgressBar — visual funding progress
CountdownTimer — live countdown to campaign deadline
PledgeModal — contribution flow with wallet auth

Wallet Integration

The app uses @stellar/freighter-api for wallet connectivity. The WalletContext provider wraps the app and exposes connect, disconnect, address, and signTx.

Prerequisites

Contracts

Requirement	Version	Installation
Rust	1.70+	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`
wasm32 target	-	`rustup target add wasm32-unknown-unknown`
Stellar CLI	21.0+	Installation Guide

Frontend

Requirement	Version	Installation
Node.js	18+	nodejs.org
npm	9+	Included with Node.js
Freighter	Latest	freighter.app

Optional

Docker (for containerized deployment)
GitHub CLI (for release automation)

Getting Started

1. Clone

git clone https://github.com/Fund-My-Cause/Fund-My-Cause.git
cd Fund-My-Cause

2. Build & test the contract

# Build WASM
cargo build --release --target wasm32-unknown-unknown

# Run tests
cargo test --workspace

3. Deploy to testnet

DEADLINE=$(date -d "+30 days" +%s)
./scripts/deploy.sh <CREATOR_ADDRESS> <TOKEN_ADDRESS> 1000 $DEADLINE 10 "My Campaign" "A great cause" null [REGISTRY_CONTRACT_ID]

If REGISTRY_CONTRACT_ID is omitted, the script deploys a new registry contract. After campaign initialization, the script calls registry.register(campaign_id) automatically.

Save the printed Contract ID and Registry ID — you'll need them in frontend config.

4. Configure frontend environment

Create apps/interface/.env.local:

NEXT_PUBLIC_CROWDFUND_CONTRACT_ID=<CONTRACT_ID>
NEXT_PUBLIC_REGISTRY_CONTRACT_ID=<REGISTRY_ID>
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

5. Run the frontend

cd apps/interface
npm install
npm run dev

Open http://localhost:3000.

Docker

Run with Docker Compose (recommended for local dev)

# Copy and fill in your env vars
cp apps/interface/.env.example apps/interface/.env.local

# Build and start
docker compose up --build

The app will be available at http://localhost:3000.

Build the image manually

docker build -f apps/interface/Dockerfile -t fund-my-cause .
docker run -p 3000:3000 --env-file apps/interface/.env.local fund-my-cause

The Dockerfile uses a multi-stage build:

builder — installs deps and builds Next.js with output: 'standalone'
runner — copies only the standalone output for a minimal production image

CI/CD

GitHub Actions workflows:

rust_ci.yml — builds WASM + runs Rust tests on push/PR to main
frontend_ci.yml — lints and typechecks the frontend on push/PR to main
playwright.yml — runs Playwright E2E tests on PRs targeting main
deploy-testnet.yml — deploys contracts to Stellar testnet on push to develop

Dependabot is configured to keep npm, Cargo, and GitHub Actions dependencies up to date weekly.

Code Coverage

The frontend enforces a minimum 80% coverage threshold across all metrics (statements, branches, functions, lines) via Jest. The build fails if any metric drops below this floor.

Run coverage locally:

cd apps/interface
npm run test:coverage

Thresholds are configured in apps/interface/jest.config.js under coverageThreshold.global.

Contributing

Fork the repo
Create a feature branch: git checkout -b feat/my-feature
Commit with conventional commits: git commit -m "feat: add X"
Open a pull request

License

MIT — see LICENSE.

Reproducible Builds & Cargo.lock

Cargo.lock is committed to this repository intentionally.

For application binaries and smart contracts, locking every transitive dependency to an exact version is a security requirement — not optional. Without it:

A cargo build on a different machine or at a later date may silently pull in a newer (potentially compromised or breaking) version of any dependency.
Audits and vulnerability scans target specific versions; a floating lock file makes those results meaningless.
Soroban WASM bytecode must be byte-for-byte reproducible so that on-chain contract hashes can be independently verified.

This follows the Cargo book's recommendation for binaries and aligns with Rust smart contract best practices.

Built on Stellar

Fund-My-Cause is powered by the Stellar network and Soroban smart contracts. Stellar provides fast, low-cost transactions with 5-second finality, making it ideal for crowdfunding at scale.

Name		Name	Last commit message	Last commit date
Latest commit History 196 Commits
.github		.github
.vscode		.vscode
apps/interface		apps/interface
contracts		contracts
docs		docs
e2e		e2e
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Fund-My-Cause

Architecture

How It Works

Monorepo Structure

Smart Contract

Pull-based Refund Model

Platform Fee

Frontend

Wallet Integration

Prerequisites

Contracts

Frontend

Optional

Getting Started

1. Clone

2. Build & test the contract

3. Deploy to testnet

4. Configure frontend environment

5. Run the frontend

Docker

Run with Docker Compose (recommended for local dev)

Build the image manually

CI/CD

Code Coverage

Contributing

License

Reproducible Builds & Cargo.lock

Built on Stellar

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Fund-My-Cause

Architecture

How It Works

Monorepo Structure

Smart Contract

Pull-based Refund Model

Platform Fee

Frontend

Wallet Integration

Prerequisites

Contracts

Frontend

Optional

Getting Started

1. Clone

2. Build & test the contract

3. Deploy to testnet

4. Configure frontend environment

5. Run the frontend

Docker

Run with Docker Compose (recommended for local dev)

Build the image manually

CI/CD

Code Coverage

Contributing

License

Reproducible Builds & Cargo.lock

Built on Stellar

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages