🌟 StellarAid

A blockchain-based crowdfunding platform built on the Stellar Network for transparent, borderless, and secure fundraising.

StellarAid enables project creators to raise funds in XLM or any Stellar-based asset (USDC, NGNT, custom tokens), while donors can contribute with full on-chain transparency.

� Workspace Layout

This project uses a Rust Cargo workspace with the following structure:

stellarAid-contract/
├── Cargo.toml                 # Workspace configuration
├── crates/
│   ├── contracts/
│   │   └── core/             # Core Soroban smart contract
│   │       ├── Cargo.toml
│   │       └── src/
│   │           └── lib.rs    # Contract implementation
│   └── tools/                # CLI utilities and deployment tools
│       ├── Cargo.toml
│       └── src/
│           └── main.rs       # CLI entry point
├── .gitignore
└── README.md

Crates Overview

• stellaraid-core: Main Soroban smart contract implementing the crowdfunding logic
• stellaraid-tools: CLI utilities for contract deployment, configuration, and management

🛠️ Development Setup

Quick Start (New Contributors)

1. Clone the repository

   git clone https://github.com/YOUR_USERNAME/stellaraid-contract.git
   cd stellaraid-contract

2. Install Rust toolchain (automatically configured by rust-toolchain.toml)

   # Install Rust if not already installed
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
   # The project will automatically use the correct Rust version and targets
   rustup show

3. Install Soroban CLI

   # Method 1: Install via cargo (recommended for development)
   cargo install soroban-cli
   
   # Method 2: Install via npm (alternative)
   npm install -g soroban-cli
   
   # Verify installation
   soroban --version

4. Build the project

   # Using Make (recommended)
   make build
   
   # Or using cargo directly
   cargo build -p stellaraid-core --target wasm32-unknown-unknown

Prerequisites

• Rust stable toolchain (automatically managed by rust-toolchain.toml)
• wasm32-unknown-unknown target (auto-installed by toolchain)
• Soroban CLI for contract deployment and testing

Toolchain Configuration

This project uses rust-toolchain.toml to ensure consistent development environments:

[toolchain]
channel = "stable"
targets = ["wasm32-unknown-unknown"]
components = ["rustfmt", "clippy"]

This ensures:

• Consistent Rust version across all contributors
• Required targets are automatically installed
• Essential components (rustfmt, clippy) are included

Development Commands

The project includes a Makefile for common development tasks:

# Build WASM contract
make build

# Run all tests
make test

# Format code
make fmt

# Run linter
make lint

# Clean build artifacts
make clean

# Show all available commands
make help

Building (Manual)

# Build the core contract for WASM
cargo build -p stellaraid-core --target wasm32-unknown-unknown --release

# Build the CLI tools
cargo build -p stellaraid-tools

# Build entire workspace
cargo build --workspace

Testing

# Run contract tests
cargo test -p stellaraid-core

# Run all tests
cargo test --workspace

CLI Usage

# Check configuration
cargo run -p stellaraid-tools -- config check

# Deploy contract (placeholder)
cargo run -p stellaraid-tools -- deploy --network testnet

📌 Features

🎯 For Donors

• Discover global fundraising campaigns
• Donate in XLM or Stellar assets
• Wallet integration (Freighter, Albedo, Lobstr)
• On-chain transparency: verify all transactions

🎯 For Creators

• Create social impact projects
• Accept multi-asset contributions
• Real-time donation tracking
• Withdraw funds directly on-chain

🎯 For Admins

• Campaign approval workflow
• User & KYC management
• Analytics dashboard

🏗️ Architecture Overview

StellarAid Blockchain Layer is built with:

• Stellar Testnet / Mainnet support
• Donation verification
• On-chain withdrawal system
• Asset‑agnostic design

📌 How to Contribute

1. Fork the Repository

Click the “Fork” button in the top‑right of the GitHub repo and clone your fork:

git clone https://github.com/YOUR_USERNAME/stellaraid-contract.git
cd stellaraid-contract

2. Create a Branch

git checkout -b feature/add-donation-flow

3. Commit Messages

Use conventional commits:

feat: add wallet connection modal
fix: resolve donation API error
docs: update project README
refactor: clean up project creation form

4. Submitting a Pull Request (PR)

Push your branch:

git push origin feature/add-donation-flow

Open a Pull Request from your fork back to the main branch.

Security Scans

This project uses cargo-audit and cargo-deny to maintain high security standards and license compliance.

Local Scans

You can run the security scans locally using the following commands:

• Check for vulnerabilities:

  make audit

• Check for license and ban policies:

  make deny

Resolving Failures

Vulnerabilities (cargo audit)

If a vulnerability is found, you should:

1. Update dependencies: Run cargo update to see if a newer version of the crate resolves the issue.
2. Ignore (Temporary): If a fix is not available and you have audited the vulnerability, you can temporarily ignore it by adding it to deny.toml under [advisories] -> ignore.

License/Ban Policy (cargo deny)

If a license or ban policy violation is found:

1. Check Licenses: Ensure all dependencies use approved licenses. If a new license needs to be allowed, update the allow list in deny.toml.
2. Banned Crates: If a crate is banned, you must find an alternative or justify its use and add it to the skip list in deny.toml.

Automated CI

Security scans are automatically run on every push and pull request. CI will fail if any known vulnerabilities or policy violations are detected.

📜 License

MIT License — free to use, modify, and distribute.

Soroban Configuration (networks)

This workspace includes a deterministic, strongly-typed Soroban network configuration system.

Add a network (example CLI stub):

soroban config network add <name> \
   --rpc-url <url> \
   --network-passphrase "<passphrase>"

List networks (profiles in soroban.toml):

soroban config network ls

Select a network (this sets the active profile name; loader reads SOROBAN_NETWORK):

soroban config network use <name>

Environment variable override behavior

• SOROBAN_NETWORK selects a profile (e.g. testnet, mainnet, sandbox).
• SOROBAN_RPC_URL and SOROBAN_NETWORK_PASSPHRASE override profile values when set.

Verify the resolved network with the included CLI tool:

cargo run -p stellaraid-tools -- network

See .env.example for a safe example of environment variables you can copy to .env.