Instant, transparent, low-fee disaster relief donations powered by the Stellar blockchain.
During natural disasters and humanitarian crises, traditional donation channels (banks, wire transfers, payment processors) suffer from:
- High fees — intermediaries take a significant cut
- Slow transfers — cross-border payments can take days
- Lack of transparency — donors can't verify if funds reached the right place
- Limited accessibility — people in affected regions may lack banking access
AidSolve solves this by enabling instant, transparent, low-fee donations through a Soroban contract on Stellar testnet. Donors can connect Freighter or create a local demo wallet, see their balance, call the deployed contract from the frontend, and inspect live contract events on the blockchain.
- Public deployed contract address:
CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC - Public event contract address:
CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC - Verifiable event transaction hash and link:
6bf536e42acb15cfeb2652bb3a44f83ef29303dfcb9bafe19899cf45dcac54ab - Live demo: https://aid-solve.vercel.app/
| Feature | Description |
|---|---|
| 🔗 Wallet Connect | One-click connection via Freighter browser extension |
| 🧪 Demo Wallet | Local testnet wallet option for signing contract calls without Freighter |
| 🔌 Wallet Disconnect | Clean session-level disconnection with UI reset |
| 💰 Balance Display | Real-time XLM balance fetching with refresh capability |
| 💸 Contract Call | Build, sign, and submit a Soroban contract invocation from the frontend |
| ✅ Transaction Status | Live status updates while the contract call is built, signed, and confirmed |
| 📡 Event Feed | Real-time contract event polling from Soroban RPC |
| ❌ Failure Feedback | Red error card with detailed error descriptions |
| 🎯 Cause Selection | Pre-set disaster relief causes (Earthquake, Flood, Wildfire) |
| ⚡ Quick Amounts | One-click preset donation amounts (10, 50, 100, 500 XLM) |
| 🌙 Dark Theme | Premium dark UI with glassmorphism and micro-animations |
| 📱 Responsive | Mobile-first design that works on all screen sizes |
Before you begin, ensure you have the following:
Download from nodejs.org
node --version # Should be v18+
npm --version # Should be v9+Freighter is a Stellar wallet browser extension (like MetaMask for Stellar).
- Install from freighter.app or your browser's extension store
- Create a new wallet or import an existing one
- Switch to Testnet: Open Freighter → Settings → Network → Select TESTNET
Fund your testnet account using Stellar's Friendbot:
# Replace YOUR_PUBLIC_KEY with your Freighter testnet public key
curl "https://friendbot.stellar.org?addr=YOUR_PUBLIC_KEY"Or visit: https://laboratory.stellar.org/#account-creator?network=test
⚠️ Important: Make sure Freighter is set to TESTNET before connecting. This app uses testnet only — no real funds are involved.
git clone https://github.com/your-username/AidSolve.git
cd AidSolvenpm installnpm run devThe app will open at http://localhost:5173 in your browser.
npm run build
npm run preview- Click the "Connect Freighter" button
- Approve the connection in the Freighter popup
- Your wallet address and XLM balance will appear
Or click "Create Demo Wallet" to generate and fund a local testnet wallet that can also sign contract calls.
- Click one of the cause cards (Earthquake Relief, Flood Response, Wildfire Aid)
- The recipient address and memo will auto-fill
- Enter an optional memo for the contract call
- Click "Send Donation" to invoke the deployed testnet contract
- Approve the transaction in the Freighter signing popup, or let the demo wallet sign locally
- Success: Green card showing the transaction hash with a link to Stellar Expert explorer
- Failure: Red card with a clear error message (e.g., insufficient balance, invalid address)
- The live feed below the form shows contract events in near real time from Soroban RPC.
- Use it to verify that the contract call is producing observable on-chain activity.
- Click "Disconnect" to end your session
AidSolve/
├── index.html # Main HTML with semantic structure
├── package.json # Dependencies & scripts
├── vite.config.js # Vite configuration with node polyfills
├── README.md # This file
└── src/
├── main.js # App entry point — event binding & orchestration
├── wallet.js # Freighter wallet integration (connect/disconnect)
├── stellar.js # Stellar SDK operations (balance/transactions)
├── ui.js # DOM manipulation & visual state management
└── style.css # Complete design system (dark theme, animations)
| Module | Responsibility |
|---|---|
main.js |
Bootstraps the app, binds event listeners, coordinates modules |
wallet.js |
Wraps Freighter plus a locally generated demo wallet for connect, disconnect, and address management |
stellar.js |
Wraps @stellar/stellar-sdk for Soroban contract calls, balance queries, and event polling |
ui.js |
All DOM updates — wallet state, balance, contract status, feedback cards, event feed, toasts, loading |
style.css |
CSS design tokens, glassmorphism cards, animations, responsive breakpoints |
User Action → main.js (handler) → wallet.js / stellar.js → ui.js (render)
Example: Send Donation
1. User clicks "Send Donation"
2. main.js → handleSend() validates inputs
3. main.js → stellar.sendPayment() builds a Soroban invocation, signs it, and submits it to RPC
4. main.js → ui.showSuccessState() or ui.showFailureState() renders result
| Technology | Purpose |
|---|---|
| Vite | Fast build tool & dev server |
| @stellar/stellar-sdk | Stellar network interaction (Horizon API) |
| @stellar/freighter-api | Freighter browser wallet integration |
| Vanilla JS (ES Modules) | Application logic with clean module separation |
| Vanilla CSS | Custom design system with modern CSS features |
| Google Fonts | Outfit (headings) + Inter (body) typography |
The app is configured to use Stellar Testnet by default:
// src/config.js
export const NETWORK_PASSPHRASE = Networks.TESTNET;
export const SOROBAN_RPC_URL = 'https://soroban-testnet.stellar.org';- The frontend calls the public testnet increment contract for the donation action.
- Live events are fetched from a second testnet contract that emits transfer events.
Contributions are welcome! Here's how:
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-feature) - Commit your changes (
git commit -m 'Add my feature') - Push to the branch (
git push origin feature/my-feature) - Open a Pull Request
- Follow existing code patterns and module structure
- Keep functions small and well-documented with JSDoc
- Test with Freighter on Stellar Testnet before submitting
- Ensure responsive design works on mobile
This project is licensed under the MIT License — see the LICENSE file for details.
This is a testnet-only educational project. No real funds (mainnet XLM) are used or at risk. The cause addresses are testnet placeholders for demonstration purposes.
Built with ❤️ on the Stellar Network