Inspiration
A donation can cross the world in seconds. But can a local supplier afford to act on it?
When disaster strikes, raising funds is only part of the challenge. Local suppliers still need to commit inventory and arrange transportation, often before they know when they'll be paid. Donors also want to understand which orders their contributions support and what happens if a relief operation fails.
We started Stellar Relief to explore whether funds committed in advance could give local businesses more confidence to participate in relief procurement, without taking away donors' protection when plans change. This matters especially for smaller suppliers that cannot easily absorb payment uncertainty. Our prototype does not finance their upfront costs; it focuses on making the payment commitment more dependable. The hope is that a supplier can check the funding rules before deciding whether to take an order.
What it does
Stellar Relief is a donor-governed relief funding prototype built on Stellar. Donors contribute USDC to a Soroban smart contract and vote on proposed relief orders, with voting power proportional to their contributions. After the voting deadline, an order can be approved if it has more than half of the pool's voting weight.
Payment happens in two stages. The supplier declares dispatch, and the local shop confirms receipt. That gives the supplier the right to independently claim 70% of the order funds. After an authorized issuer attests full distribution, the shop can claim the remaining 30%.
The contract distinguishes funds committed to an order, payments already earned, and funds still refundable. For a 10 USDC order, that means 7 USDC can belong to the supplier after authorized receipt, while the shop's 3 USDC remains conditional on distribution. If distribution is not fully attested before the deadline, donors can recover the unearned portion while the supplier's earned payment remains protected. If no proposal wins, donors can recover their full contributions.
We also built a six-step Guided Demo with offline-capable vouchers so families could collect supplies without a crypto wallet. Voucher records currently stay in the browser; individual redemptions are not verified on-chain.
How we built it
We chose Stellar because this is a payment problem: we needed USDC transfers, publicly inspectable transactions, and rules that control when funds can move. We wrote the contract in Rust using Soroban and built the demo in React and TypeScript. The contract handles contributions, weighted voting, authorized declarations, separate payment claims, and refunds. The frontend explains the workflow but does not submit live blockchain transactions. It includes a Progressive Web App experience that can reopen offline on the same device after being cached.
We tested the revised contract in three separate Stellar Testnet campaigns using fictional orders and valueless test assets:
Scenario A — Successful payment. Two donors funded a 10 USDC pool and voted 6–4. After shop receipt, the supplier claimed 7 USDC. After full distribution attestation, the shop claimed 3 USDC. The pool ended at zero.
Scenario B — Distribution timeout. The shop confirmed receipt, but distribution was never fully attested. After the deadline, donors recovered 1.8 USDC and 1.2 USDC. Only after both refunds did the supplier claim its protected 7 USDC. The shop received nothing, and the pool again ended at zero. This was the result we most wanted to verify.
Scenario C — No winning proposal. Voting expired without an approved order, and the two donors recovered the full 10 USDC. View the Testnet contract.
We also ran Rust unit tests and read-only Testnet RPC simulations for premature payments, duplicate claims, and invalid operations. The rejected operations were simulations, not failed transactions submitted to the ledger.
Try the interactive demo: https://stellar-relief-v2.vercel.app/
Full evidence: Successful payment · Refund and failure scenarios
Challenges we ran into
Our first contract paid the supplier and shop together only after distribution. We realized that if the shop had already accepted the goods but the distribution deadline passed, refunds could consume funds the supplier had already earned. Instead of just changing the deadline, we split the two payments and rewrote the refund accounting. Scenario B was our test of whether that fix held up beyond local tests.
We also learned where on-chain verification stops. Soroban can check who authorized a receipt or distribution declaration, but it cannot tell whether the goods actually arrived or reached eligible families. The prototype uses demo accounts for these roles. Separate demo accounts do not establish independent real-world organizations. Real deployment would need independent verification, oversight, and a way to resolve disputes.
Accomplishments that we're proud of
We completed a Soroban contract with contribution-weighted voting, role-specific authorization, and independent payment claims, plus an interactive offline-capable demo. We published transaction records for three Testnet outcomes and tested invalid operations instead of demonstrating only a successful transfer.
The working frontend and the evidence reports give judges two ways to understand the project: explore the user journey, or inspect the contract's actual behavior.
What we learned
Building Stellar Relief taught us that locking funds is simpler than deciding when different people have earned their share. We also learned to separate technical correctness from real-world value.
Our 70/30 supplier/shop split is illustrative, not verified market pricing, and we have not tested whether these payment commitments would change suppliers' decisions. Payment certainty might make participation easier, but actual costs, delivery reliability, and business willingness need to be measured outside a hackathon.
What's next for Stellar Relief
We want to connect the frontend to wallet-signed transactions, make vouchers secure across devices, and improve delivery verification. Just as importantly, we want to speak with suppliers, shops, and relief organizations before attempting a field pilot.
The contract has passed the payment and refund scenarios we tested; whether it improves real relief procurement is still an open question.
Built With
- javascript
- pwa
- react
- rust
- soroban
- stellar
- testnet
- typescript
- usdc
- vite
