PROOFCHAINS

Blockchain-Powered Academic Certification Platform on Cardano

Issue, verify, and authenticate diplomas as immutable and tamper-proof NFTs.

---

TABLE OF CONTENTS

• Overview
• Applications
• Prerequisites
• Installation
• Configuration
• Commands
• Architecture
• Tech Stack
• Supported Wallets
• Features
• Documentation
• Security
• Contributing
• License

---

OVERVIEW

ProofChains is a comprehensive academic certification solution built on the Cardano blockchain. It enables institutions to issue diplomas as NFTs, ensuring permanent authenticity and traceability.

Why ProofChains?

• 🔐 Immutable — Certificates cannot be altered or forged
• ⚡ Instant Verification — Verify any diploma in seconds
• 🌍 Global Access — Accessible from anywhere in the world
• 💰 Cost-Effective — Low transaction fees on Cardano

---

APPLICATIONS

Application	Port	URL	Source Code
Landing + Verifier	3003	proofchains.org	apps/landing
Issuer Portal	3001	issuer.proofchains.org	apps/issuer
Admin Dashboard	3002	admin.proofchains.org	apps/admin

---

PREREQUISITES

Requirement	Version / Details
Node.js	>= 18.x
npm	>= 9.x
Supabase	supabase.com account
Blockfrost	blockfrost.io API key (Preprod)
Pinata	pinata.cloud account for IPFS
Wallet	Eternl or Lace

---

INSTALLATION

# Clone the repository
git clone https://github.com/your-org/proofchains.git
cd proofchains

# Install dependencies
npm install

# Copy and configure environment variables
cp .env.example .env

---

CONFIGURATION

Create a .env file at the project root:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJxxx...

# Cardano / Blockfrost
NEXT_PUBLIC_BLOCKFROST_PROJECT_ID=preprodXXX
NEXT_PUBLIC_BLOCKFROST_NETWORK=preprod

# IPFS / Pinata
PINATA_JWT=eyJxxx...

# Application URLs
NEXT_PUBLIC_LANDING_URL=https://proofchains.org
NEXT_PUBLIC_ISSUER_URL=https://issuer.proofchains.org
NEXT_PUBLIC_ADMIN_URL=https://admin.proofchains.org

⚠️ Warning: Never commit .env files to the repository.

---

COMMANDS

Development

npm run dev              # Start all applications
npm run landing:dev      # Landing only
npm run issuer:dev       # Issuer only
npm run admin:dev        # Admin only

Build & Quality

npm run build            # Production build
npm run lint             # ESLint check
npm run clean            # Clean builds

Deployment

npm run deploy           # Preview (all apps)
npm run deploy:prod      # Production (all apps)

See scripts/deploy.ps1 for details.

---

ARCHITECTURE

proofchains/
├── apps/
│   ├── landing/         # Landing page + diploma verification
│   ├── issuer/          # Institution portal
│   └── admin/           # Administration dashboard
├── packages/
│   ├── ui/              # Shared React components
│   ├── shared/          # Common services, hooks, types
│   └── chain/           # Cardano SDK (mint, verify)
├── scripts/             # Deployment scripts
└── supabase/            # SQL schema and migrations

---

TECH STACK

Category	Technologies
Frontend
Language
Blockchain	Lucid, Blockfrost API
Wallets	Eternl, Lace
Storage	via Pinata
Database	(PostgreSQL)
Auth	Supabase Auth
Monorepo
Deploy

---

SUPPORTED WALLETS

Wallet	Platform	Status
Eternl	Desktop Extension	✅ Supported
Eternl	Mobile (iOS/Android)	✅ Supported
Lace	Desktop Extension	✅ Supported

On mobile, the app automatically redirects to Eternl's built-in dApp browser.

Implementation: packages/ui/src/hooks/useWallet.ts

---

FEATURES

Institution Portal (Issuer)

• Issue diploma NFTs on Cardano
• Manage students and cohorts
• Real-time statistics dashboard
• Secure authentication

Public Verification (Landing)

• Search by document ID or Asset ID
• Instant blockchain verification
• Display diploma metadata

Administration (Admin)

• Institution KYC validation
• Platform-wide statistics
• User management
• Subscription management

---

DOCUMENTATION

The complete user guide is available:

User Guide (PDF)

Also accessible from the homepage under the "Documentation" section.

Contents:

• Introduction to ProofChains
• Issuing diplomas (institutions)
• Verifying diplomas
• Account management
• FAQ and troubleshooting

---

SECURITY

Excluded Sensitive Files

The following files are excluded from versioning (see .gitignore):

• .env, .env.local, .env.*.local
• .vscode/
• node_modules/

Report a Vulnerability

If you discover a security vulnerability, please contact us directly at [email protected] rather than opening a public issue.

---

CONTRIBUTING

Contributions are welcome! Please:

1. Fork the repository
2. Create a branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

---

LICENSE

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

---

PROOFCHAINS

Certifying the future, one diploma at a time.