Transparent crowdfunding on Stellar Soroban...
- Contract name:
stellarGive(contracts/stellar-give) - Contract ID:
CB6HVHRQYILGNKW7RBB66BC6TDBIEWADOA2YUUV4I22RXRLA6DY6OAKT - Deployer alias:
copilot-deployer - WASM upload tx:
92a8a10978d2216de9f6e97bd2b4c522076eb1242a3d2d5c4738c4fb86a6dd2a - Deploy tx:
e3f88cee225bb5548e4640afe02c351373575469fb60dac6f5de670aa7687156 - Explorer (deploy tx):
https://stellar.expert/explorer/testnet/tx/e3f88cee225bb5548e4640afe02c351373575469fb60dac6f5de670aa7687156 - Lab contract link:
https://lab.stellar.org/r/testnet/contract/CB6HVHRQYILGNKW7RBB66BC6TDBIEWADOA2YUUV4I22RXRLA6DY6OAKT
Frontend (Next.js) -> Stellar SDK/Freighter -> Soroban RPC -> stellar-give Contract
^ |
|---------------------- event + state polling --------------|
Detailed architecture: docs/ARCHITECTURE.md
contracts/stellar-give Soroban smart contract (Rust)
frontend/ Next.js 14 web app
scripts/ Deployment and utility automation
docs/ Security, deployment, architecture, contributing docs
.github/workflows/ Contract + frontend CI pipelines
New Contributors: Please see our Detailed Setup Guide for comprehensive instructions on setting up your environment for macOS, Linux, and Windows (WSL2).
- Install dependencies and set env files
cp .env.example .env cp .env.example frontend/.env.local echo "NEXT_PUBLIC_CONTRACT_ADDRESS=CB6HVHRQYILGNKW7RBB66BC6TDBIEWADOA2YUUV4I22RXRLA6DY6OAKT" >> frontend/.env.local cd frontend && npm ci
- Run local checks
cd ../contracts/stellar-give && cargo test cd ../../frontend && npm run lint && npm run build
- Run the frontend with the deployed contract
npm run dev
Watch the 3-minute tutorial to create your first campaign.
Video covers wallet connection, campaign creation, donation flow, and transaction confirmation with captions for accessibility.
| Area | Command |
|---|---|
| Contract format | cd contracts/stellar-give && cargo fmt --check |
| Contract lint | cd contracts/stellar-give && cargo clippy -- -D warnings |
| Contract test | cd contracts/stellar-give && cargo test |
| Contract wasm build | cd contracts/stellar-give && cargo build --release --target wasm32-unknown-unknown |
| Frontend lint | cd frontend && npm run lint |
| Frontend build | cd frontend && npm run build |
| Frontend dev | cd frontend && npm run dev |
You can run the entire StellarGive stack locally using Docker and Docker Compose. This starts a standalone Stellar node (with Soroban support) and the frontend application, ensuring they boot up in the correct order.
-
Configure Environment Variables: Copy the example environment file:
cp .env.example .env
You can customize the ports and node environment in the
.envfile:STELLAR_PORT_RPC: Port for Soroban RPC / Horizon API (default:8000)STELLAR_PORT_FRIENDBOT: Port for Friendbot funder utility (default:8001)FRONTEND_PORT: Port where the Next.js frontend will be accessible (default:3000)
-
Start the Stack: Run the following command to start the containers:
docker compose up -d
Docker Compose will start the
stellarnode first. Thefrontendcontainer will wait until thestellarnode is healthy (using a built-in curl healthcheck) before executing its setup and boot command. -
Verify Service Health: You can monitor the health status of the services by running:
docker compose ps
Both the
stellarandfrontendservices will show ashealthyonce fully initialized.
| Service | Port | Endpoint |
|---|---|---|
| Frontend App | 3000 |
http://localhost:3000 |
| Soroban RPC / Horizon API | 8000 |
http://localhost:8000 |
| Friendbot Funder | 8001 |
http://localhost:8001 |
- Soroban Testnet RPC:
https://soroban-testnet.stellar.org - Friendbot:
https://friendbot.stellar.org/?addr=<PUBLIC_KEY> - Explorer base (testnet):
https://stellar.expert/explorer/testnet - Lab:
https://lab.stellar.org
- Smart contract: Rust,
soroban-sdk - Frontend: Next.js 14, React 18, TypeScript
- Blockchain: Stellar Soroban (testnet-first workflow)
- CI/CD: GitHub Actions
- Setup Guide:
docs/SETUP.md - Architecture:
docs/ARCHITECTURE.md - Contract API:
docs/CONTRACT_API.md - Security:
docs/SECURITY.md - Deployment:
docs/DEPLOYMENT.md - Contributing:
docs/CONTRIBUTING.md - Branch Protection:
docs/branch-protection.md - Video Transcript:
docs/VIDEO_TRANSCRIPT.md - Litepaper:
docs/WHITEPAPER.md
- Coverage reporting: Tests for Rust (
cargo tarpaulin) and Frontend (vitest --coverage) are run in CI. - Codecov dashboard: Test coverage metrics are automatically uploaded to Codecov for both frontend and contract.
- WASM optimization: Contract builds are strictly validated to ensure optimized
.wasmsize remains under 64KB. - Local Soroban node: We support local-first Soroban development using
stellar/quickstart:testing. Rundocker compose upto start a standalone node (RPC on port 8000, Horizon on port 8001). - Dependabot maintenance: Weekly dependency updates are enabled for both Cargo (contracts) and NPM (frontend) dependencies.
- Branch protection: The
mainbranch is protected by mandatory status checks (Contract CI,Lint & Format,CI,Dependency Audit). Admins/owners can bypass checks in emergencies. See Branch Protection Guide or runbash scripts/apply-branch-protection.shto apply.
- Multi-token donation support (#10)
- Campaign categories and search (#15, #37)
- Mobile-responsive UI (#46)
- Recurring donations (subscription model)
- DAO governance for platform upgrades
- Analytics dashboard for creators
- Mobile app (React Native)
- Cross-chain bridge for Ethereum donations
- Grant program for non-profit onboarding
Roadmap items are aspirational and may change based on community feedback and implementation feasibility.
Welcome! If you are new to the project, please start by reading our Detailed Setup Guide which will walk you through installing all necessary dependencies (Rust, Soroban CLI, Node.js) across macOS, Linux, and Windows. Once your environment is set up, check out CONTRIBUTING.md for our workflow guidelines.
 Mutmahinat Feyisara 💻 📖 |
 Nursca 💻 📖 🎨 🤔 |
This project follows the all-contributors specification. Contributions of any kind welcome as always!..