Supermarket POS

A comprehensive blockchain-based Point of Sale system for supermarkets, built on Base Layer 2 blockchain. The system enables secure cryptocurrency payments (ETH and USDC) through smart contracts, with a modern React frontend featuring WalletConnect integration for seamless wallet connectivity.

Overview

Supermarket POS is a decentralized payment solution that revolutionizes retail transactions by leveraging blockchain technology. The system consists of:

Smart Contracts: Secure payment vault on Base Sepolia testnet handling ETH and USDC deposits/withdrawals
Frontend Application: Modern React-based interface with WalletConnect integration
Protocol Fees: 0.5% automatic fee collection for ecosystem development
Merchant Management: Authorized withdrawal system for registered merchants

Key Components

Component	Technology	Purpose
`SuperPOS.sol`	Solidity ^0.8.24	Main payment contract
`wagmi.ts`	TypeScript	Blockchain connection configuration
`App.tsx`	React 19.2.3	Main application interface
`ConnectKit`	WalletConnect	Wallet integration

Architecture

graph TB
    subgraph "Frontend Layer"
        A[React Application]
        B[WalletConnect Integration]
        C[ConnectKit UI]
    end

    subgraph "Smart Contract Layer"
        D[SuperPOS Contract]
        E[Payment Vault]
        F[Merchant Registry]
    end

    subgraph "Blockchain Layer"
        G[Base Sepolia]
        H[ETH/USDC Tokens]
        I[Event Logs]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    D --> F
    E --> G
    F --> G
    G --> H
    G --> I

Component Architecture

graph LR
    subgraph "User Interface"
        UI1[Payment Interface]
        UI2[Merchant Dashboard]
        UI3[Transaction History]
    end

    subgraph "Business Logic"
        BL1[Wallet Connection]
        BL2[Payment Processing]
        BL3[Merchant Authorization]
    end

    subgraph "Data Layer"
        DL1[Contract State]
        DL2[Transaction Events]
        DL3[Balance Tracking]
    end

    UI1 --> BL1
    UI2 --> BL2
    UI3 --> BL3
    BL1 --> DL1
    BL2 --> DL2
    BL3 --> DL3

System Flow

sequenceDiagram
    participant Customer
    participant Frontend
    participant Wallet
    participant Contract
    participant Merchant

    Customer->>Frontend: Select payment method (ETH/USDC)
    Frontend->>Wallet: Request connection
    Wallet->>Frontend: Connected wallet
    Frontend->>Contract: Initiate deposit transaction
    Contract->>Contract: Process payment + 0.5% fee
    Contract->>Frontend: Transaction confirmed
    Frontend->>Customer: Payment successful

    Note over Merchant: Later withdrawal
    Merchant->>Frontend: Request withdrawal
    Frontend->>Contract: Verify merchant authorization
    Contract->>Contract: Calculate fee deduction
    Contract->>Merchant: Transfer funds
    Contract->>Contract: Send fee to treasury

Payment Flow

flowchart TD
    A[Customer scans QR] --> B{Select Currency}
    B -->|ETH| C[Connect Wallet]
    B -->|USDC| C
    C --> D[Approve Transaction]
    D --> E[Execute Deposit]
    E --> F[Contract Processes]
    F --> G{Valid Payment?}
    G -->|Yes| H[Update Balance]
    G -->|No| I[Revert Transaction]
    H --> J[Merchant Can Withdraw]
    J --> K[Merchant Requests Withdrawal]
    K --> L[Contract Verifies Merchant]
    L --> M{Deduct 0.5% Fee}
    M --> N[Transfer to Merchant]
    M --> O[Send Fee to Treasury]

Contract Interaction

graph TD
    subgraph "Frontend Calls"
        A1[depositETH()]
        A2[depositUSDC()]
        A3[withdraw()]
        A4[getBalance()]
    end

    subgraph "Contract Functions"
        B1[Deposit Processing]
        B2[Fee Calculation]
        B3[Merchant Verification]
        B4[Balance Updates]
    end

    subgraph "Events Emitted"
        C1[Deposit Event]
        C2[Withdrawal Event]
        C3[MerchantAdded Event]
    end

    A1 --> B1
    A2 --> B1
    A3 --> B3
    A4 --> B4
    B1 --> C1
    B2 --> C2
    B3 --> C2

State Management

stateDiagram-v2
    [*] --> Connected
    Connected --> Depositing : depositETH/USDC
    Depositing --> BalanceUpdated : Success
    Depositing --> Error : Failed
    BalanceUpdated --> Withdrawing : withdraw
    Withdrawing --> FundsTransferred : Success
    Withdrawing --> Error : Failed
    Error --> Connected
    FundsTransferred --> [*]

Features

Core Functionality

Multi-Currency Payments: Support for ETH and USDC transactions
Secure Vault: Smart contract-based payment storage
Merchant Authorization: Controlled withdrawal system
Protocol Fees: Automatic 0.5% fee collection
Real-time Balances: On-chain balance tracking

User Experience

Wallet Integration: Seamless WalletConnect connectivity
Responsive Design: Mobile-first React interface
Transaction History: Complete payment tracking
Error Handling: Comprehensive error management
Gas Optimization: Efficient contract interactions

Security Features

Access Control: Owner and merchant role management
Input Validation: Comprehensive parameter checking
Emergency Functions: Owner-only emergency withdrawals
Pause Mechanism: Circuit breaker functionality
Event Logging: Transparent transaction records

Technology Stack

Smart Contracts

Solidity: ^0.8.24 - Smart contract development
Foundry: Development framework and testing
OpenZeppelin: Security libraries and standards
Base Sepolia: Testnet deployment network

Frontend Application

React: 19.2.3 - UI framework
TypeScript: 5.0+ - Type-safe development
Vite: Build tool and dev server
Tailwind CSS: Utility-first styling
ConnectKit: WalletConnect UI components

Blockchain Integration

wagmi: React hooks for Ethereum
Ethers.js: Ethereum interaction library
WalletConnect: Cross-platform wallet connectivity
Base: Layer 2 scaling solution

Development Tools

ESLint: Code linting
Prettier: Code formatting
Husky: Git hooks
Commitlint: Commit message standards

Prerequisites

System Requirements

Node.js: v18.0.0 or higher
npm/pnpm/yarn: Latest stable version
Git: v2.30.0 or higher

Blockchain Requirements

Foundry: For smart contract development
MetaMask: Or compatible Web3 wallet
Base Network: Added to wallet (Mainnet/Sepolia)

API Keys

WalletConnect Project ID: From WalletConnect Cloud
Infura/Alchemy: Optional for enhanced RPC

Installation

1. Clone Repository

git clone https://github.com/your-username/supermarket-pos.git
cd supermarket-pos

2. Environment Setup

# Copy environment template
cp .env.example .env

# Add your WalletConnect Project ID
echo "VITE_WALLETCONNECT_PROJECT_ID=your_project_id_here" >> .env

3. Smart Contracts

cd contract-solidity

# Install dependencies
forge install

# Run tests
forge test

4. Frontend Application

# Install dependencies
npm install

# Start development server
npm run dev

Usage

For Customers

Connect Wallet: Use WalletConnect to connect your Web3 wallet
Select Payment: Choose ETH or USDC payment method
Scan QR: Scan the generated QR code at supermarket POS
Confirm Transaction: Approve the payment in your wallet
Receive Confirmation: Get instant transaction confirmation

For Merchants

Register: Get authorized by contract owner
Monitor Balances: View accumulated payments
Withdraw Funds: Request withdrawals (0.5% protocol fee applied)
Track Revenue: Monitor transaction history

Development

# Start frontend development
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Testing

Smart Contract Testing

cd contract-solidity

# Run all tests
forge test

# Run with gas reporting
forge test --gas-report

# Run specific test file
forge test --match-path test/SuperPOS.t.sol

# Run with coverage
forge coverage

Frontend Testing

# Run unit tests
npm test

# Run with coverage
npm test -- --coverage

# Run E2E tests (if configured)
npm run test:e2e

Integration Testing

# Test contract-frontend integration
npm run test:integration

Deployment

Smart Contract Deployment

Testnet (Base Sepolia)

cd contract-solidity

# Deploy using script
./deploy-superpos-testnet.sh

# Or manual deployment
forge script script/DeploySuperPOS.s.sol \
  --rpc-url https://sepolia.base.org \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify

Mainnet (Base)

# Deploy to mainnet
./deploy-superpos-mainnet.sh

Frontend Deployment

# Build application
npm run build

# Deploy to hosting service (Vercel, Netlify, etc.)
# Follow your hosting provider's instructions

API Reference

Smart Contract Functions

Write Functions

depositETH() - Deposit ETH to vault
depositUSDC(uint256 amount) - Deposit USDC tokens
withdraw(string currency, address to, uint256 amount) - Withdraw funds (merchants only)
addMerchant(address merchant) - Add authorized merchant (owner only)
emergencyWithdraw(string currency, address to, uint256 amount) - Emergency withdrawal (owner only)

Read Functions

getBalance(string currency) - Get contract balance for currency
isMerchant(address account) - Check merchant authorization
owner() - Get contract owner
paused() - Check if contract is paused

Events

Deposit(address from, uint256 amount, string currency, uint256 timestamp)
Withdrawal(address merchant, uint256 amountReceived, uint256 feeTaken, string currency, uint256 timestamp)
MerchantAdded(address merchant, address owner)
MerchantRemoved(address merchant, address owner)

Frontend Components

Main Components

App - Main application component
ConnectKitButton - Wallet connection interface
PaymentInterface - Payment selection and processing
MerchantDashboard - Merchant management interface
TransactionHistory - Transaction display component

Contributing

We welcome contributions from the community. Please follow these guidelines:

Development Process

Fork the repository
Create a feature branch: git checkout -b feature/your-feature-name
Make your changes with proper tests
Ensure all tests pass: npm test && forge test
Commit with conventional format: git commit -m "feat: add new feature"
Push to your branch: git push origin feature/your-feature-name
Create a Pull Request

Code Standards

Solidity: Follow OpenZeppelin guidelines
TypeScript: Strict type checking enabled
React: Functional components with hooks
Styling: Tailwind CSS utility classes
Testing: 100% test coverage for contracts

Commit Convention

We use Conventional Commits:

feat: - New features
fix: - Bug fixes
docs: - Documentation updates
test: - Testing related changes
refactor: - Code refactoring

Security

Smart Contract Security

Audited Code: Contracts follow OpenZeppelin standards
Access Control: Owner and merchant role separation
Input Validation: Comprehensive parameter checking
Emergency Functions: Owner-only emergency mechanisms
Pause Functionality: Circuit breaker for critical situations

Frontend Security

Wallet Security: Secure wallet connection handling
Input Sanitization: Client-side input validation
HTTPS Only: Secure communication channels
Dependency Updates: Regular security updates

Reporting Security Issues

Please report security vulnerabilities to: security@supermarket-pos.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

Supermarket POS Team

Website: https://supermarket-pos.com
Documentation: https://docs.supermarket-pos.com
GitHub: https://github.com/your-username/supermarket-pos
Discord: Join our community
Twitter: @SupermarketPOS

Built for the future of retail payments

Back to top

Name		Name	Last commit message	Last commit date
Latest commit History 1,027 Commits
assets		assets
contract-solidity		contract-solidity
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
components.json		components.json
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Supermarket POS

Table of Contents

Overview

Key Components

Architecture

Component Architecture

System Flow

Payment Flow

Contract Interaction

State Management

Features

Core Functionality

User Experience

Security Features

Technology Stack

Smart Contracts

Frontend Application

Blockchain Integration

Development Tools

Prerequisites

System Requirements

Blockchain Requirements

API Keys

Installation

1. Clone Repository

2. Environment Setup

3. Smart Contracts

4. Frontend Application

Usage

For Customers

For Merchants

Development

Testing

Smart Contract Testing

Frontend Testing

Integration Testing

Deployment

Smart Contract Deployment

Testnet (Base Sepolia)

Mainnet (Base)

Frontend Deployment

API Reference

Smart Contract Functions

Write Functions

Read Functions

Events

Frontend Components

Main Components

Contributing

Development Process

Code Standards

Commit Convention

Security

Smart Contract Security

Frontend Security

Reporting Security Issues

License

Contact

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages