Revolutionizing Retail: A Blockchain-Powered Loyalty and Transaction System with FastAPI + Ethereum

Traditional retail systems, despite technological advancements, still grapple with key inefficiencies. Common issues include opaque data handling, siloed loyalty point systems, susceptibility to fraud due to centralized databases, and the inability to scale effectively due to costly and sluggish infrastructure. Recognizing these challenges, we set out to reimagine the retail experience by building a decentralized, secure, and transparent system powered by blockchain.

Enter the Retail Blockchain System – a platform that streamlines retail transactions and loyalty point management using smart contracts, ensuring transparency, immutability, and trust between retailers and consumers.

Why Blockchain? Why Now?

Blockchain solves many of the long-standing issues in retail:

• Immutability: Guarantees that transaction records cannot be altered or deleted.
• Transparency: Offers real-time visibility into loyalty points and transaction history.
• Security: Removes single points of failure by decentralizing control.
• Interoperability: Makes it easier to allow cross-brand loyalty programs.

Our Tech Stack: Building for Decentralization

We meticulously selected tools and frameworks that align with our goals of transparency, efficiency, and decentralization:

• Solidity: The go-to smart contract language for Ethereum-based applications.
• Ethereum/Ganache: Ethereum provides a decentralized ledger; Ganache allows for rapid local development.
• FastAPI: A modern Python framework with async support and auto-generated docs.
• Web3.py: Enables backend smart contract interaction.
• Pydantic: Ensures type-safe, validated data across APIs.
• python-dotenv: Manages sensitive credentials via environment variables.
• solcx: Compiles Solidity contracts on the fly.
• Docker: Containerization ensures consistent deployment across environments.

System Architecture

+--------------------+         +----------------------------+         +-----------------------+
| Frontend (Optional)|         |   FastAPI Backend (Python) |         | Ethereum Blockchain   |
| (e.g., React/Vue)  |         |                            |         | (Ganache for Dev)     |
+--------+-----------+         +------------+---------------+         +-----------+-----------+
         |                                  |                                      |
         |  HTTP Requests (API Calls)       | REST Endpoints                       | Smart Contract Calls
         |--------------------------------->+--(/transactions, /loyalty, /status)--|--------------------------->
         |                                  |                                      |  - RetailTransaction.sol
         |                                  |                                      |  - LoyaltyPoints.sol
         |<---------------------------------| API Responses                        |<---------------------------
         |                                  |                                      |

Backend Services:

• Contract Manager: Compiles and manages smart contracts.
• Currency Converter: Converts INR ↔ Wei for ETH-denominated transactions.
• Loyalty Manager: Automates point awards, redemptions, and queries.
• Transaction Manager: Maps real-world transaction IDs to on-chain entries.

Workflow Overview:

1. Startup: Smart contracts are compiled and deployed (or reused if already present).
2. Retail Transaction: Backend records purchase on-chain via RetailTransaction.sol and calculates loyalty rewards.
3. Loyalty Issuance: Points awarded and tracked through LoyaltyPoints.sol.
4. Redemption: Customers redeem points via authenticated API calls.
5. Data Storage: All records are immutable and publicly auditable.

Key Features

• Immutable Transactions: Tamper-proof logs of purchases.
• On-chain Loyalty Points: Transparent, secure reward tracking.
• API-Based Redemption & Inquiry: User-friendly endpoints.
• Currency Conversion: Seamless handling of INR and Wei.
• Smart Contract Utilities: Simplifies contract interaction.
• Swagger & ReDoc Docs: Auto-generated API reference.
• Dockerized Deployment: One-click reproducible setup.

API Endpoints

Base URL (local): http://localhost:8000

1. Check API Status

curl -X GET "http://localhost:8000/"

2. Record Transaction

curl -X POST "http://localhost:8000/transactions/record" 
  -H "Content-Type: application/json" 
  -d '{
    "customer_address": "0xCustomerEthAddress",
    "retailer_address": "0xRetailerEthAddress",
    "amount_INR": 1500.75,
    "product_id": "PROD123",
    "quantity": 2,
    "description": "Purchase of electronics"
  }'

3. Get Transaction Details

curl -X GET "http://localhost:8000/transactions/1"

4. Get Loyalty Balance

curl -X GET "http://localhost:8000/loyalty/balance/0xCustomerEthAddress"

5. Redeem Loyalty Points

curl -X POST "http://localhost:8000/loyalty/redeem" 
  -H "Content-Type: application/json" 
  -d '{
    "customer_address": "0xCustomerEthAddress",
    "points_amount": 100
  }'

Local Setup

Prerequisites:

• Python 3.8+
• Ganache CLI (via Node.js)
• Docker (optional)

Setup:

git clone https://github.com/yourname/retail-blockchain-system.git
cd retail-blockchain-system

# Create .env with sensitive info
cp .env.example .env

# Install dependencies
pip install -r requirements.txt

# Start Ganache in a separate terminal
npx ganache-cli -d

# Run FastAPI
uvicorn app.main:app --reload

Deployment

Deploying on platforms like Render involves:

• Switching to public Ethereum testnets (e.g., Sepolia) via Infura/Alchemy
• Storing contract addresses persistently
• Securing private keys and credentials

Lessons Learned & Best Practices

• Avoid Hardcoding: Use python-dotenv to manage sensitive data.
• Live Exchange Rates: Replace static currency conversion with real-time APIs.
• Gas Fees: Ensure wallets have test ETH to cover transactions.
• Contract Reuse: Store deployed contract addresses to prevent unnecessary redeployment.
• Security: Never expose private keys; prefer vault solutions for production.

Tangible Business Benefits

• 5–10% Boost in Retention: Due to increased transparency and trust in loyalty systems.
• Up to 95% Profit per Retained Customer: Leveraging loyalty to enhance repeat business.
• Cross-brand Opportunities: Unlock new forms of partnerships via interoperable loyalty points.

Future Enhancements

• Real-Time Currency APIs: Live rates from CoinGecko, etc.
• NFT Loyalty: Mint unique loyalty NFTs as rewards.
• Admin Dashboards: Retailer interfaces for analytics and program management.
• Event Listeners: React to blockchain events in real-time.
• Frontend Portal: Customer-friendly UI for loyalty and purchase history.
• Decentralized Identity (DID): Privacy-focused auth systems.
• Hybrid Storage: Use off-chain DBs for non-sensitive metadata.
• Multi-chain Support: Extend to Polygon, Avalanche, etc.

Final Thoughts

The Retail Blockchain System is more than just an experiment – it’s a glimpse into the future of commerce. Transparent, secure, interoperable, and consumer-focused, it redefines how retailers build loyalty and trust.

🔍 Explore the Project
🧪 Live Demo: BlockCart
💻 GitHub Repo: Blockchain_In_Retail

👉 Like this project? Drop a star on GitHub

Explore the project on GitHub and feel free to contribute, ask questions, or fork it to build your own decentralised loyalty ecosystem!

💬 Have questions or feedback? Let’s connect in the comments!