134 lines
8.5 KiB
Markdown
134 lines
8.5 KiB
Markdown
# Volana
|
||
|
||
> **Trade freely. Pay finally.** A decentralized, censorship-resistant marketplace built on Solana.
|
||
|
||
Volana is what eBay would look like if it were rebuilt for the open web: a consumer marketplace where listings live on a public blockchain, payments settle through on-chain escrow, and no company, government, or payment processor can remove a listing, reverse a payment, or freeze funds. It feels like a modern shopping app. The blockchain stays invisible.
|
||
|
||
---
|
||
|
||
## 🌍 Vision
|
||
|
||
Online commerce today runs on platforms that can change the rules at any moment: listings get delisted, payments get charged back months after a sale, and 10–15% of every transaction disappears into platform and processor fees. Volana's premise is that a marketplace can be **a protocol instead of a platform**:
|
||
|
||
- 🛡️ **Censorship-resistant by design.** Listings and orders are Solana accounts governed entirely by open-source smart contracts. Even if the Volana frontend went offline, anyone could spin up a new one that reads the same on-chain data and trading would continue.
|
||
- ✅ **Final, predictable payments.** No chargebacks, no surprise reversals. Funds are locked in an on-chain escrow when the buyer orders and released when they confirm receipt. The entire payment flow is encoded in auditable contracts, so you can read exactly what will happen before you sign anything.
|
||
- 🪙 **Near-zero fees.** No percentage cut. The only costs are Solana network fees (< $0.001 per transaction) and an optional dispute-mediator fee (typically 0.5–2%, charged **only** if a dispute is actually adjudicated). Compare: eBay takes 10–13%, PayPal another 3–4%.
|
||
- ⚖️ **Permissionless dispute resolution.** If something goes wrong, a neutral resolver (chosen by the buyer at checkout from a list the seller accepts) rules on the case, and the ruling is enforced on-chain. Neither party can override it.
|
||
- 🔑 **No accounts, no KYC.** Your Solana wallet *is* your account. Connect Phantom, Solflare, or Backpack and start trading.
|
||
|
||
**The target user is not a crypto native.** Volana is designed for regular online shoppers who are used to eBay and Amazon. The UX hides lamports, PDAs, and signatures behind plain language like "Confirm your purchase" and "Secure payment hold".
|
||
|
||
## 💡 How It Works
|
||
|
||
1. 🛒 **Browse & pick**: find something you want to buy.
|
||
2. 🔒 **Place order**: connect your wallet and confirm. Your payment is locked in a secure escrow that nobody can tamper with.
|
||
3. 📦 **Receive & confirm**: when the goods arrive, confirm receipt and the payment is released to the seller automatically.
|
||
4. ⚖️ **Protected throughout**: if something goes wrong, your chosen dispute mediator steps in; their ruling is final and enforced on-chain.
|
||
|
||
Under the hood, every order drives an escrow state machine:
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> AwaitingSellerConfirm : buyer locks funds
|
||
AwaitingSellerConfirm --> Active : seller confirms
|
||
AwaitingSellerConfirm --> Cancelled : buyer cancels (full refund)
|
||
Active --> Complete : buyer confirms receipt → seller paid
|
||
Active --> Disputed : buyer raises dispute
|
||
Disputed --> Complete : resolver rules for seller
|
||
Disputed --> Cancelled : resolver rules for buyer (refund)
|
||
Complete --> [*]
|
||
Cancelled --> [*]
|
||
```
|
||
|
||
## 🏗️ Architecture
|
||
|
||
Volana is split into an on-chain protocol layer and a consumer frontend:
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Volana App (this repo) │
|
||
│ Expo / React Native — iOS · Android · Web │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ Wallet adapter · RPC data fetching │
|
||
├──────────────────────────┬──────────────────────────┤
|
||
│ solisting program │ descro program │
|
||
│ listings & orders │ escrow state machine │
|
||
│ (ListingAccount, │ (EscrowAccount, │
|
||
│ OrderAccount, │ dispute resolution) │
|
||
│ ResolverEntry) │ │
|
||
├──────────────────────────┴──────────────────────────┤
|
||
│ Solana · Pyth price oracle │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- **`solisting`** is the marketplace program: listings (name, price, canonical + alternative currencies, stock, accepted resolvers), orders, and the resolver registry. Multi-currency prices are converted at order time via the Pyth oracle with buyer-set slippage protection.
|
||
- **`descro`** is the escrow program: one escrow account per order, implementing the state machine above. Funds move from the buyer's wallet into an escrow vault atomically when the order is created.
|
||
- **The frontend** is a universal Expo app (one codebase for iOS, Android, and web) that reads both programs and renders them as a familiar shopping experience.
|
||
|
||
### 📱 Frontend Stack
|
||
|
||
| Layer | Technology |
|
||
|---|---|
|
||
| Framework | [Expo SDK 57](https://expo.dev) + React Native 0.86 + React 19 |
|
||
| Routing | [Expo Router](https://docs.expo.dev/router/introduction/) (file-based, typed routes) |
|
||
| UI kit | [HeroUI Native](https://heroui.com) |
|
||
| Styling | [Uniwind](https://docs.uniwind.dev), Tailwind CSS for React Native |
|
||
| Animation | React Native Reanimated 4 |
|
||
| Language | TypeScript (strict mode) |
|
||
|
||
The app is **responsive by design**: a bottom tab bar on mobile that hands off to a persistent top navigation on desktop-class widths, and checkout that renders as a bottom sheet on mobile.
|
||
|
||
### 📂 Repository Layout
|
||
|
||
```
|
||
├── app/ # The consumer app (Expo / React Native)
|
||
│ └── src/
|
||
│ ├── app/ # File-based routes: browse, listing/[id], orders/[id]
|
||
│ ├── components/ # ListingCard, CheckoutSheet, WalletConnectSheet, …
|
||
│ ├── state/ # Wallet & modal-flow contexts
|
||
│ ├── data/ # Typed data layer (currently mocked)
|
||
│ └── lib/ # Status → visual mappings, typography
|
||
├── prototype/ # Static HTML/JS design prototype the app is built from
|
||
└── docs/ # Product & design brief (data model, UX spec, copy rules)
|
||
```
|
||
|
||
## 🎨 Design Principles
|
||
|
||
- 🫥 **Hide the blockchain.** Wallet addresses are abbreviated, prices are human-readable ("1.5 SOL", never lamports), and escrow states are explained in plain English. The only visible blockchain interaction is the wallet's confirm popup.
|
||
- 🔍 **Transparency for those who want it.** Optional "view on explorer" links and technical detail sections expose the on-chain reality without foregrounding it.
|
||
- ⚡ **Conversion-first UX.** One-step checkout, sticky Buy Now CTA, urgency signals ("Only 2 left!"), and skeleton loading states so RPC latency never shows a blank screen.
|
||
- ♿ **Accessible.** Status indicators never rely on color alone, full keyboard navigability, WCAG AA contrast.
|
||
|
||
## 🚀 Getting Started
|
||
|
||
```bash
|
||
cd app
|
||
yarn install
|
||
npx expo start # then press i (iOS), a (Android), or w (web)
|
||
```
|
||
|
||
Useful scripts (run from `app/`):
|
||
|
||
```bash
|
||
npm run typecheck # tsc --noEmit
|
||
npm run lint # eslint
|
||
npm run format:check # prettier
|
||
```
|
||
|
||
## 🗺️ Status & Roadmap
|
||
|
||
The consumer frontend is in active development, built screen-by-screen from the design prototype. On-chain data (listings, orders, resolvers, wallet connection) is currently **mocked** behind a typed data layer, so the real Solana integration can be swapped in at a single seam.
|
||
|
||
- [x] Browse / product grid with availability states
|
||
- [x] Listing detail with resolver selection & trust signals
|
||
- [x] Wallet-connect → checkout flow (connect resumes checkout automatically)
|
||
- [x] My Orders + order detail with escrow progress
|
||
- [ ] Real wallet adapter integration
|
||
- [ ] Live RPC data via the on-chain programs
|
||
- [ ] SPL token payments (USDC, …), which the contract layer already supports
|
||
- [ ] Seller dashboard & dispute resolution UI
|
||
|
||
---
|
||
|
||
📖 For the full product specification (data model, page-by-page UX intent, and copy guidelines) see [docs/volana-design-brief.md](docs/volana-design-brief.md).
|