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

🛒 Browse & pick: find something you want to buy.
🔒 Place order: connect your wallet and confirm. Your payment is locked in a secure escrow that nobody can tamper with.
📦 Receive & confirm: when the goods arrive, confirm receipt and the payment is released to the seller automatically.
⚖️ 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:

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 + React Native 0.86 + React 19
Routing	Expo Router (file-based, typed routes)
UI kit	HeroUI Native
Styling	Uniwind, 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

cd app
yarn install
npx expo start   # then press i (iOS), a (Android), or w (web)

Useful scripts (run from app/):

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.

Browse / product grid with availability states
Listing detail with resolver selection & trust signals
Wallet-connect → checkout flow (connect resumes checkout automatically)
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.

8.5 KiB Raw Blame History Unescape Escape