A decentralized, transparent, and secure platform for managing retail transactions and loyalty points using blockchain technology.
Traditional retail systems often suffer from:
- Lack of Transparency: Unclear data usage and loyalty point management.
- Centralized Control: Vulnerable to breaches and arbitrary rule changes.
- Interoperability Issues: Loyalty points locked within single brands.
- Fraud and Disputes: No immutable transaction records.
- Inefficient Record Keeping: Expensive, slow databases for large transaction volumes.
✅ Solution: Leverage blockchain to provide decentralized, transparent, and tamper-proof retail transaction management.
| Technology | Purpose | Why? |
|---|---|---|
| Solidity | Smart contract programming language. | Standard for EVM-based blockchains. |
| Ethereum/Ganache | Blockchain platform for transaction and loyalty records. | Decentralized ledger with local dev support via Ganache. |
| FastAPI | Web API framework (Python 3.7+). | High-performance, async support, automatic interactive docs. |
| Web3.py | Ethereum blockchain interaction library. | Connects to Ethereum nodes, manages smart contracts and transactions. |
| Pydantic | Data validation and management. | Robust validation for API requests and responses. |
| python-dotenv | Environment variable management. | Safely handles sensitive config like private keys. |
| solcx | Solidity compiler wrapper for Python. | Compiles smart contracts programmatically. |
| Docker | Containerization platform. | Consistent, portable deployment environment. |
+--------------------+ +----------------------------+ +-----------------------+
| 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 |<---------------------------
| Data / Status | | Transaction Receipts
| | | Loyalty Balances
| | |
+--------+---------+ +------------+---------------+ +-----------+-----------+
|
| Services:
| - Contracts Manager (compile, deploy, load)
| - Currency Converter (INR <-> Wei)
| - Loyalty Manager (calculate, award, redeem, check)
| - Transaction Manager (match off-chain IDs)
|
| Startup:
| - Initializes/Deploys Contracts
|
| Models:
| - Pydantic Schemas
Services:
- Contract Manager
- Currency Converter (INR ↔ Wei)
- Loyalty Manager (award/redeem/check points)
- Transaction Manager (map off-chain IDs)
Workflow:
- Startup: Compile & deploy smart contracts or load existing ones.
- Transactions: Record retail transactions & award loyalty points.
- Loyalty Management: Fetch balance, redeem points.
- Data Storage: Immutable records on the blockchain.
- ✅ Immutable retail transaction recording.
- ✅ Blockchain-based loyalty points.
- ✅ Automated point awarding.
- ✅ Points redemption via API.
- ✅ Loyalty balance inquiry.
- ✅ INR ↔ Wei currency conversion.
- ✅ Smart contract management utilities.
- ✅ Dockerized deployment support.
Base URL: http://localhost:8000
Available at:
/docs(Swagger UI)/redoc
Check API Status
curl -X GET "http://localhost:8000/"Record a Retail 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" }'Get Transaction Details
curl -X GET "http://localhost:8000/transactions/1"Get Loyalty Balance
curl -X GET "http://localhost:8000/loyalty/balance/0xCustomerEthAddress"Redeem Loyalty Points
curl -X POST "http://localhost:8000/loyalty/redeem" -H "Content-Type: application/json" -d '{ "customer_address": "0xCustomerEthAddress", "points_amount": 100 }'Prerequisites:
- Python 3.8+
- Node.js & npm (for Ganache CLI)
- Docker (optional)
Steps:
- Clone the repo, set environment variables, run Ganache, install dependencies, and start FastAPI.
- Use public testnets via Infura/Alchemy.
- Secure environment configs.
- Optimize contract management for production addresses.
- Replace fixed INR ↔ Wei rate with live rates.
- Ensure test ETH balance for transactions.
- Secure private keys and sensitive data.
- Improve transaction matching for production.
- Persist contract addresses after deployment.
-
📈 Increased Potential Customer Retention: Engineered a blockchain-based loyalty transaction system, increasing potential customer retention by 5–10% through transparent, tamper-proof reward point tracking and redemption.
-
💸 Profitability Impact: Automated loyalty points awarding and redemption workflows, potentially contributing to a 25–95% profit increase per retained customer, as supported by industry benchmarks.
- Real-time Currency Conversion: Use crypto APIs like CoinGecko for live conversion rates.
- Advanced Loyalty Rules: Introduce tier-based and bonus point systems.
- NFT-based Loyalty: Mint loyalty points as NFTs for tradable, unique rewards.
- Payment Gateway Integrations: Seamless blockchain integration with existing payment gateways.
- Frontend Interface: Build a modern UI for customers and retailers.
- Event Listeners: Automate backend updates via blockchain event subscriptions.
- Multi-chain Compatibility: Enable deployment across multiple blockchain networks.
- Admin Dashboard: Retailers can manage inventory, loyalty schemes, and analytics.
- Decentralized Identity (DID): Privacy-first customer authentication using decentralized IDs.
- Off-chain Data Storage: Use traditional databases for storing high-frequency, non-sensitive data.