Because your health history shouldn't crumble in your wallet. 🗑️❌
Ever had that mini-heart attack 😰 because you couldn't find your yellow vaccination booklet right before a flight?
Enter MedBadge. 🌟 We turn your vaccination records into permanent, unchangeable, and totally verifiable Soulbound Tokens on the blockchain. ⛓️ It's like a digital health passport that you actually own, can't lose, and—best of all—gives you bragging rights. 😎
- Forever Proof 🧱: Your records live on the Base chain. They don't fade, tear, or get lost in the laundry. 🧺🚫
- You're in Charge 👑: You own your data. Not a hospital, not a corporation. You. 🫵
- Level Up 🚀: Literally. Get vaccinated, earn points, and go from Bronze 🥉 to Diamond 💎.
- Real Perks 🎁: Higher levels unlock real-world discounts. Finally, getting a shot pays off! 💸
- Get Vaccinated 🏥: Go to a verified provider.
- Mint Your Badge 🎟️: The provider issues a Soulbound Token directly to your wallet.
- HODL Your Health 💎🙌: View your shiny new badge, track your immunity level, and flex on anyone who questions your antibody game. 💪
Blockchain-based Vaccination Record Management System using Soulbound Tokens (ERC-5192)
Transform vaccination records into tamper-proof Soulbound Tokens deployed on the Base chain, giving users verifiable ownership of their health data.
MedBadge/
├── contracts/ # Foundry — Solidity smart contracts
│ ├── src/ # IERC5192, VaccineRegistry, RegistrarManager, MedBadgeSBT
│ ├── test/ # Unit, fuzz, and integration tests (85 tests)
│ └── script/ # Deployment scripts
├── backend/ # Hono + Bun — API server
│ └── src/
│ ├── config/ # Environment, constants, contract ABIs
│ ├── middleware/ # Auth (EOA+ERC-1271), rate-limit, CORS, error-handler
│ ├── routes/ # Metadata, badge, query, health endpoints
│ ├── services/ # Chain-reader, encryption, IPFS, badge-renderer, level-calculator, graph-client
│ ├── validators/ # Zod schemas
│ └── types/ # Shared TypeScript types
├── frontend/ # Next.js 16 — React UI
│ └── src/
│ ├── app/ # Pages: home, records, verify
│ ├── components/ # Header, Footer, Web3Provider
│ ├── config/ # Wagmi, contract ABIs
│ ├── lib/ # API client
│ └── messages/ # i18n (en, es, fr, de, pt, ja, ko, zh, ar)
└── subgraph/ # The Graph — event indexer
├── schema.graphql # Entity definitions
└── src/mapping.ts # Event handlers
| Layer | Technology |
|---|---|
| Chain | Base (EVM L2) |
| Token Standard | ERC-721 + ERC-5192 (Soulbound) |
| Smart Contracts | Solidity 0.8.28, Foundry, OpenZeppelin v5 |
| Backend | Hono, Bun, Viem, Satori, Sharp, Pinata, Upstash Redis |
| Frontend | Next.js 16, Wagmi v2, ConnectKit, React Query |
| Indexing | The Graph (Subgraph Studio) |
| Storage | IPFS (Pinata) + AES-256-GCM encryption |
bun install# Build
bun run contracts:build
# Test (85 tests)
bun run contracts:test
# Deploy to local Anvil
cd contracts
anvil &
forge script script/DeployMedBadge.s.sol --rpc-url http://localhost:8545 --broadcast# Copy and configure environment
cp backend/.env.example backend/.env
# Start development server
bun run backend:dev# Copy and configure environment
cp frontend/.env.example frontend/.env.local
# Start development server
bun run frontend:devbun run dev| Contract | Description |
|---|---|
IERC5192 |
Minimal Soulbound NFT interface standard |
VaccineRegistry |
On-chain extensible vaccine type registry |
RegistrarManager |
Institution-tier registrar permission management |
MedBadgeSBT |
Core Soulbound Token — mint, revoke, batch-revoke, reinstate |
- Storage-optimized
VaccinationRecordstruct — 2 slots (35 bytes) - Dual access control: Phase 1 (owner direct) + Phase 2 (institution admin)
- Revocation audit trail: reason stored on-chain with reinstatement support
- Batch operations: mass recall via
batchRevokeRecords - Emergency pause: Pausable + ReentrancyGuard
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/health |
— | Health check |
GET |
/api/v1/user/:address/records |
— | User vaccination records |
GET |
/api/v1/user/:address/level |
— | User level & progress |
GET |
/api/v1/vaccines |
— | Registered vaccine types |
GET |
/api/v1/records/:tokenId |
— | Single record |
GET |
/api/v1/stats |
— | System statistics |
GET |
/api/v1/badge/:tokenId |
— | Dynamic badge image (SVG/PNG/WebP) |
GET |
/api/v1/badge/:tokenId/json |
— | OpenSea metadata JSON |
POST |
/api/v1/metadata/encrypt |
✓ | Encrypt PII with wallet key |
POST |
/api/v1/metadata/upload |
✓ | Upload to IPFS |
DELETE |
/api/v1/metadata/:cid |
✓ | GDPR unpin |
- Self-Sovereign Data: Encryption key derived from wallet signature (SHA-256)
- GDPR Compliance: Right to erasure via IPFS unpin + key destruction
- Auth: EOA + ERC-1271 smart contract wallet signature verification
- Rate Limiting: Tiered (public/authenticated/sensitive/badge) via Upstash
- Soulbound: ERC-5192 — tokens are non-transferable by design
| Level | Points | Discount |
|---|---|---|
| 🥉 Bronze | 0–199 | 0% |
| 🥈 Silver | 200–499 | 5% |
| 🥇 Gold | 500–799 | 10% |
| 💎 Platinum | 800–1199 | 15% |
| 👑 Diamond | 1200+ | 20% |
Formula: points = Σ (doses/maxDoses × 100) + fullImmunizationBonuses
Planned features and improvements for future releases:
- Add more languages: Hindi, Thai, Vietnamese, Indonesian, Turkish, Russian, Ukrainian, Swahili
- Automatic locale detection via browser geolocation API
- Full RTL (Right-to-Left) layout support for Arabic and Hebrew
- Locale-aware date, number, and currency formatting
- Community-driven translation portal (Crowdin/Weblate)
- Per-user language preference stored on-chain or in user profile
- Full WCAG 2.2 AA compliance audit and certification
- Screen reader optimization (ARIA landmarks, live regions, announcements)
- Keyboard navigation for all interactive elements (focus traps, skip links)
- High contrast mode and custom color themes
- Reduced motion mode (
prefers-reduced-motionsupport) - Font size scaling without layout breakage
- Voice control and speech-to-text integration for form inputs
- Progressive Web App (PWA) with offline support and push notifications
- QR code generation for instant badge verification
- Dark/Light theme toggle with system preference detection
- Animated scroll transitions and skeleton loading states
- Mobile-native gesture support (swipe to navigate records)
- Interactive onboarding tutorial for first-time users
- Badge sharing to social media (OpenGraph image preview)
- Multi-wallet dashboard (view records across multiple wallets)
- ERC-4337 Account Abstraction — gasless onboarding with social login
- Expiration timestamps on SBTs for time-limited immunizations
- Verifier role with on-chain permission management
- Institution-level registrar management (sub-admins per hospital)
- Cross-chain badge portability (Base ↔ Ethereum ↔ Polygon)
- Zero-knowledge proof verification (selective disclosure)
- On-chain governance for vaccine registry updates
- Multi-sig admin operations for critical contract functions
- WebSocket API for real-time record update notifications
- GraphQL API layer alongside REST
- Redis-backed session management and caching layer
- Webhook integrations for healthcare provider systems (HL7 FHIR)
- Background job queue for asynchronous badge rendering
- API versioning strategy (v2, v3) with deprecation policies
- Horizontal scaling with load balancer support
- Automated database backup and disaster recovery
- Device fingerprinting for enhanced authentication
- Hardware wallet (Ledger/Trezor) optimized signing flows
- Audit log dashboard for data access history
- Configurable data retention policies per jurisdiction
- End-to-end encrypted record sharing with time-limited access links
- Bug bounty program and professional security audit
- Admin dashboard with vaccination statistics and heatmaps
- WHO ICD-11 vaccine code standard integration
- EU Digital COVID Certificate (DCC) format compatibility
- SMART Health Cards interoperability
- Regulatory compliance reporting tools (HIPAA, GDPR, PIPL)
- Automated compliance audit trails
- Partner integration API for pharmacies, clinics, and insurers
- Automated discount verification for partner merchants
- Travel verification integration (airline & border control APIs)
- Insurance premium reduction proof generation
- Healthcare provider SDK for easy SBT minting
- Open API documentation with interactive playground (Swagger/Redoc)
MIT