Solana POS System

A decentralized Point-of-Sale (POS) payment gateway built on Solana. This protocol enables merchants to accept simple, fast, and secure payments using the Solana Pay standard, with on-chain revenue tracking via an Anchor smart contract.

🌟 Features

• Solana Pay Standard: Fully compatible with Solana Pay QR codes.
• On-Chain Settlement: Instant settlement with direct SPL token transfers (USDC).
• Decentralized State: Merchant revenue and transaction counts are tracked on-chain via Anchor.
• Real-time Updates: Instant UI feedback using Helius Webhooks and Supabase.
• Non-Custodial: Funds go directly to the merchant's wallet.

🏗 Architecture

The system consists of two main components:

1. Protocol (Anchor Program): A smart contract that manages merchant state, tracks global revenue, and validates payment transactions.
2. Client (Web Dashboard): A Next.js application for merchants to generate invoices, view analytics, and for customers to scan payment QR codes.

System Architecture

graph TD
    subgraph Client
        UI[Merchant Dashboard / POS]
    end

    subgraph "Off-Chain Server (Next.js)"
        API[API Routes]
        DB[(Supabase DB)]
    end

    subgraph "Infrastructure"
        H[Helius RPC/Webhook]
    end

    subgraph "On-Chain (Solana)"
        PROG[Anchor Program]
        ACC[Merchant Account]
    end

    UI -- Create Invoice --> API
    API -- Read/Write --> DB
    UI -- Realtime Updates --> DB
    
    UI -- Build Transaction --> API
    API -- Fetch Program Data --> H
    
    H -- Notify Payment --> API
    PROG -- Emit Event --> H
    PROG -- Read/Write --> ACC

Loading

Payment Flow

sequenceDiagram
    participant M as Merchant
    participant UI as POS UI
    participant DB as Supabase
    participant C as Customer
    participant SOL as Solana Chain
    participant H as Helius

    M->>UI: Create Invoice
    UI->>DB: Save Invoice (Pending)
    UI->>M: Show QR Code
    M->>C: Present QR Code
    C->>UI: Scan QR (Solana Pay)
    UI-->>C: Transaction Request
    C->>SOL: Sign & Send Transaction
    SOL->>SOL: Verify & Update State
    SOL->>H: Emit PaymentEvent
    H->>UI: Webhook (POST /api/webhooks)
    UI->>DB: Update Invoice (Paid)
    DB-->>UI: Realtime Signal
    UI->>M: Payment Confirmed ✅

Loading

🚀 Getting Started

Prerequisites

• Node.js (v18+)
• Rust & Cargo
• Solana CLI
• Anchor CLI

Installation

1. Clone the repository

   git clone https://github.com/yourusername/solana-pos.git
   cd solana-pos

2. Install Dependencies

   # Install web dependencies
   cd web
   npm install

3. Anchor (Smart Contract) Setup

   cd ../anchor
   anchor build
   # Get your program ID
   anchor keys list

⚙️ Configuration

Create a .env.local file in the web directory:

# Solana
NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com

# Database (Supabase)
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_key

# Service Keys
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
HELIUS_API_KEY=your_helius_key

🏃 Usage

Start Local Validator

solana-test-validator

Deploy Program

cd anchor
anchor deploy --provider.cluster localnet

Run Frontend

cd web
npm run dev

Visit http://localhost:3000 to access the POS dashboard.

📚 Documentation

For detailed technical specifications, architecture diagrams, and development notes, please refer to the SPECIFICATION.md.

📄 License

MIT