ACREDIA

Blockchain-Based Academic Credential Verification System

Secure, Transparent, and Tamper-Proof Educational Credentials on Stellar Network

🎯 Built on Stellar Network

Cost-effective transactions • Fast settlement • Decentralized infrastructure • Native Soroban contracts

🌐 Stellar Network | 📊 Stellar Expert Explorer | 💧 Get Test XLM

🌐 VIEW LIVE DEMO

📽️ VIEW LIVE DEMO

🌟 Overview

Acredia is a revolutionary decentralized platform that transforms how academic credentials are issued, stored, and verified. Built on Stellar Network, a decentralized network focused on financial inclusivity and fast, low-cost transfers, Acredia leverages blockchain technology, IPFS, and modern web technologies to eliminate credential fraud, reduce verification time, and provide lifetime access to verified academic records.

Why Acredia?

Traditional paper-based or centralized digital credentials suffer from:

Easy forgery and tampering
Time-consuming verification processes
Risk of loss or damage
Limited accessibility
Centralized control and single points of failure

Acredia solves these problems by creating immutable, blockchain-verified credentials that are:

✅ Permanent and tamper-proof
✅ lntly verifiable
✅ Decentralized and censorship-resistant
✅ Accessible anywhere, anytime
✅ Privacy-preserving with student control

🚀 Why Stellar Network?

Acredia is built on Stellar Network, a decentralized network focused on providing financial inclusion and fast, low-cost transfers of assets globally:

Key Benefits

💰 Cost-Effective Transactions

Minimal transaction fees (less than a cent)
Makes credential issuance affordable for educational institutions worldwide
Students can claim credentials without significant costs

⚡ Fast Settlement

Transaction finality in 3-5 seconds
Instant credential verification
Improved user experience with near-instant confirmations

🌍 Global Reach & Accessibility

Designed for global financial inclusion
Works on low-bandwidth connections
Accessible from anywhere in the world

🔒 Decentralized Infrastructure

No single point of failure
Community-run validator network
Battle-tested since 2014

♻️ Energy Efficient

Minimal energy consumption
Uses consensus algorithm designed for efficiency
Supports sustainable applications

Network Details

Stellar Public Network: Production network (Network ID: Public Global Stellar Network)
Stellar Testnet: Testing environment with test XLM faucet
Block Explorer: Stellar Expert
RPC/API Endpoints: Horizon API for reliable connections
Native Currency: XLM (Lumens)

Smart Contracts: Soroban - Stellar's smart contract platform built on Rust

🎯 The Problem

The current academic credential system faces critical challenges:

Credential Fraud: Fake degrees and certificates cost employers billions annually
Slow Verification: Manual verification takes days or weeks
Institutional Dependency: Students rely on institutions to provide transcripts
Data Loss: Physical documents can be lost, damaged, or destroyed
Privacy Concerns: Sharing full credentials when only partial verification is needed

💡 Our Solution Is

Acredia creates a three-layer verification system powered by Stellar Network:

Blockchain Layer: Immutable credential records on Stellar Network using Soroban smart contracts
Storage Layer: Decentralized metadata storage on IPFS
Database Layer: Fast querying and indexing via Supabase

This architecture ensures credentials are:

Permanent: Stored on blockchain forever
Cost-Effective: Minimal transaction fees on Stellar Network make issuance affordable
Fast: Near-instant transaction settlement
Verifiable: Instant verification via token ID or QR code
Decentralized: No single point of failure
Detailed: Subject-wise marks, grades, and complete academic records
Accessible: Students own their credentials via blockchain accounts

📸 Screenshots

Landing Page

Modern, responsive landing page showcasing the platform's features

Student Dashboard

Students can view all their credentials with detailed information and blockchain verification

Institution Dashboard

Institutions can issue credentials with subject-wise marks, grades, and complete academic records

Credential Verification

Public verification page with blockchain proof and comprehensive credential details

Detailed subject-wise performance and blockchain transaction information

Admin Panel

Contract owner dashboard for authorizing institutions and monitoring system statistics

IPFS Decentralized Storage

Credential files and JSON metadata are permanently anchored on the decentralized IPFS network via Pinata

⚡ Key Features

For Students

Digital Wallet: Receive credentials as NFTs in your wallet
Instant Access: View all credentials anytime, anywhere
Easy Sharing: Generate QR codes or shareable verification links
Subject Details: Access complete subject-wise marks and grades
Lifetime Ownership: Credentials stored permanently on blockchain

For Institutions

Simple Issuance: Issue credentials with an intuitive web interface
Subject-Wise Records: Add detailed marks, grades, and performance data
Batch Processing: Upload credentials for multiple students
Blockchain Verification: Each credential is verifiable on-chain
Authorization Control: Admin-approved issuer system

For Verifiers (Employers/Universities)

Instant Verification: Verify credentials in seconds via token ID or QR code
Blockchain Proof: Direct links to blockchain transactions
Complete Details: View student information, institution, marks, and grades
No Login Required: Public verification page accessible to anyone
Tamper-Proof: Impossible to forge or modify credentials

For Administrators

Authorization Management: Approve institutions to issue credentials
System Statistics: Real-time dashboard with credential counts
Contract Ownership: Full control over smart contract parameters
Security: Only contract owner can authorize new issuers

📜 Smart Contracts

Acredia uses a unified Soroban smart contract deployed on Stellar Network:

✅ AcrediaCredential Contract — Live on Testnet

Contract ID: CCGDFDLPELTOWG5H5OA4MBR5OZWDP4XJI3S3TQZVZ7XTVP77EKOFORYF
Network: Stellar Testnet
Owner / Deployer: GAJRNUO6HSMQG4FNHNWQVRXJZJZ7QRA7HXPYYB6H5PTA3EAAJXJNZD7U
Deployed: 2026-04-01 (Updated Setup) Explorer: View on Stellar Expert ↗

This single contract replaces two separate EVM contracts (CredentialNFT + CredentialRegistry) with one unified Soroban contract written in Rust. Additionally, it features upgraded Next.js boundary protection to bypass @stellar/stellar-sdk object coercions on the browser.

Purpose: Issue, store, and verify academic credentials on Stellar Network

Key Features:

Authorization system — only admin-approved institutions can issue credentials
Immutable on-chain credential storage with IPFS metadata links
Credential lookup by token ID or SHA-256 hash
Revocation mechanism with issuer-only control
Timestamp-based issuance records via env.ledger().timestamp()

Contract Functions:

Function	Access	Description
`initialize(owner)`	One-time	Initialize contract with owner address
`authorize_issuer(issuer)`	Owner only	Grant institution credential issuance rights
`revoke_issuer(issuer)`	Owner only	Remove institution authorization
`is_authorized_issuer(issuer)`	Public	Check if address is an authorized issuer
`issue_credential(student, issuer, hash, uri)`	Authorized issuers	Mint a new credential, returns `token_id`
`revoke_credential(token_id, issuer)`	Issuer only	Revoke an issued credential
`get_credential(token_id)`	Public	Fetch full credential struct by ID
`verify_credential(hash)`	Public	Look up credential by SHA-256 hash
`is_revoked(token_id)`	Public	Check revocation status
`total_credentials()`	Public	Get total credentials ever issued

Storage Architecture:

DataKey::Authorized(Address) → instance storage (low-cost, ephemeral)
DataKey::Credential(u64) → persistent storage (permanent, survives ledger closings)
DataKey::HashIndex(String) → persistent storage (hash → token_id index)

Stellar Testnet Deployment (Active)

Network: Stellar Testnet
RPC Endpoint: https://soroban-testnet.stellar.org
Horizon API: https://horizon-testnet.stellar.org
Block Explorer: Stellar Expert (Testnet)

Stellar Mainnet Deployment (Production)

Network: Stellar Public Network
RPC Endpoint: https://soroban-mainnet.stellar.org
Horizon API: https://horizon.stellar.org
Block Explorer: Stellar Expert

🔍 Smart Contract Verification Links (Important!)

All deployments, metadata hashes, and transaction executions can be publicly verified directly on the Stellar ledger explorer:

Main Contract Viewer: AcrediaCredential Testnet Explorer ↗
Deployer Account Ledger: Stellar Account Overview ↗
Soroban RPC Instance: https://soroban-testnet.stellar.org

⚠️ Important: Always verify contract IDs on Stellar Expert before interacting with them. Never trust addresses from unofficial sources.

🛠 Technology Stack

Frontend

Next.js 16 - React framework with App Router for optimal performance
TypeScript - Type-safe development
Tailwind CSS - Utility-first styling
Radix UI - Accessible component primitives
Stellar SDK - Wallet connection and blockchain interactions
Lucide React - Modern icon library

Blockchain (Stellar)

Rust - Language for Soroban smart contracts
Soroban SDK - Smart contract development on Stellar
Stellar Network - Distributed ledger for credential management
Stellar SDK (JavaScript/Python) - Client library for blockchain interactions
Horizon API - REST API for Stellar network queries

Storage & Backend

IPFS - Decentralized metadata storage via Pinata
Supabase - PostgreSQL database with Row Level Security
PostgreSQL - Relational database for indexing
RESTful APIs - Custom API routes in Next.js

Development Tools

npm - Package manager used by frontend/package-lock.json
ESLint - Code quality
Prettier - Code formatting
Git - Version control

🧪 Testing Strategy

Acredia employs a rigorous testing methodology to ensure absolute security and reliability before deployment on the Stellar Network:

1. Smart Contract Constraints (Rust)

DataKey Validation: Utilizing #[contracttype] enumerations rigorously enforces that unique contract state keys are tightly managed off-ledger, avoiding standard library allocation exceptions (no_std) required by Soroban.
Address Validation: Hardened validation ensuring symbol_short! usage keeps within maximum string lengths, confirming valid G-Type Stellar identities.

2. Frontend Validation & Logic (Vitest)

Comprehensive unit testing utilizing vitest covering all utility logic natively on the UI structure:

Ledger Identity Matching: isValidAddress accurately verifies if a 55-character string matches the absolute Stellar Ledger Public pattern (^G[A-Z2-7]{54}$).
State Transition Machine: Business-logic evaluations (getNextStatus) verifying strict one-way credential progression: Draft ➔ Pending_Issuance ➔ Issued ➔ Revoked. Hard-coded safety blocks malicious regression.
Malicious Payload Defense: Dynamic testing blocking inputs containing short strings, missing public keys, or invalid empty object injections before the transaction reaches the Freighter wallet prompt.

3. Edge-case SDK Resiliency (Implemented)

Freighter API v6 Compatibility: Safe-parse bypass resolving e.switch is not a function by seamlessly handling both string and object responses (signedTxXdr) natively returned during wallet transaction signing.
RPC Parsing Fallback: Strict bypasses for parsing xdr.ScVal primitives (like booleans) ensuring boolean RPC responses (e.g., is_authorized_issuer) do not crash if executed directly through client-side Javascript prototype boundaries.
Zero-Balance Accounts: The simulation explicitly constructs dummy Account sequences (e.g., Sequence "0") to ensure read-only blockchain queries execute gracefully even if the user connects an unfunded 0 XLM wallet.

🏗 System Architecture

graph TB
    subgraph "Frontend Layer"
        A[Next.js Application]
        B[React Components]
        C[Stellar SDK]
    end

    subgraph "Blockchain Layer"
        D[AcrediaCredential Contract]
        F[Stellar Network Ledger]
    end

    subgraph "Storage Layer"
        G[IPFS Network]
        H[Pinata IPFS Gateway]
    end

    subgraph "Database Layer"
        I[Supabase PostgreSQL]
        J[Row Level Security]
    end

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

    style A fill:#0ea5e9
    style D fill:#f59e0b
    style E fill:#f59e0b
    style G fill:#8b5cf6
    style I fill:#10b981

Architecture Layers

Presentation Layer: User interfaces for students, institutions, and verifiers
Application Layer: Business logic, authentication, and API routes
Blockchain Layer: Smart contracts deployed on Stellar Network using Soroban for decentralized transaction processing
Storage Layer: IPFS for decentralized metadata storage ensuring data persistence
Database Layer: Supabase for fast queries and off-chain indexing with Row Level Security

Why This Architecture?

Global Reach: Stellar Network's infrastructure is designed for global financial inclusion and accessibility

Cost-Efficiency: Minimal transaction fees on Stellar Network make the system economically viable for educational institutions worldwide

Security: Multi-layer approach ensures data integrity - blockchain for immutability, IPFS for decentralization, and Supabase for access control

Performance: Fast transaction settlement on Stellar Network provides excellent user experience

🔄 How It Works

Credential Issuance Flow

sequenceDiagram
    participant Institution
    participant Frontend
    participant IPFS
    participant Blockchain
    participant Database
    participant Student

    Institution->>Frontend: Enter credential details
    Frontend->>IPFS: Upload metadata + documents
    IPFS-->>Frontend: Return IPFS hash
    Frontend->>Blockchain: Mint NFT with IPFS hash
    Blockchain-->>Frontend: Transaction confirmed
    Frontend->>Database: Store credential record
    Database-->>Frontend: Success
    Frontend->>Student: Send NFT to wallet
    Frontend-->>Institution: Credential issued successfully

Verification Flow

sequenceDiagram
    participant Verifier
    participant Frontend
    participant Database
    participant IPFS
    participant Blockchain

    Verifier->>Frontend: Enter token ID or scan QR
    Frontend->>Database: Query credential data
    Database-->>Frontend: Return metadata
    Frontend->>IPFS: Fetch detailed metadata
    IPFS-->>Frontend: Return full data
    Frontend->>Blockchain: Verify on-chain status
    Blockchain-->>Frontend: Confirm validity
    Frontend-->>Verifier: Display verification result

Step-by-Step Process

For Institutions (Issuing Credentials)

Connect Wallet: Institution connects authorized wallet (Stellar account)
Enter Student Details: Name, wallet address, credential type
Add Academic Data: Degree, major, GPA, issue date
Add Subject Marks: Subject name, marks obtained, maximum marks, grade
Upload to IPFS: System uploads metadata to decentralized storage
Record on Blockchain: Smart contract records credential on Stellar Network
Database Record: System creates searchable database entry
Confirmation: Student receives credential on Stellar blockchain

For Students (Viewing Credentials)

Login: Authenticate with email or wallet
Dashboard: View all issued credentials from Stellar
Details: Click credential to see complete information stored on Stellar blockchain
Share: Generate QR code or verification link
Download: Export credential details or share blockchain proof from Stellar Expert

For Verifiers (Checking Credentials)

Access: Navigate to public verification page (no login required)
Input: Enter credential token ID or scan QR code
Verification: System checks Stellar blockchain and IPFS
Results: View complete credential details with blockchain proof
Confirmation: Verify authenticity via Stellar Expert blockchain explorer link

🚀 Getting Started

Clean Clone Quick Start

Use npm for the frontend. This repository commits frontend/package-lock.json, and CI installs with npm ci.

From a fresh clone:

git clone https://github.com/Soumen1080/ACREDIA-STELLAR.git
cd ACREDIA-STELLAR\frontend
npm ci
Copy-Item .env.local.example .env.local
npm run dev

Then fill frontend\.env.local, run the Supabase SQL scripts listed below, and open http://localhost:3000.

TL;DR: Install prerequisites, clone the repo, run npm ci in frontend, copy frontend/.env.local.example, run the two Supabase SQL scripts, and start npm run dev. Deploy the contract only if you changed contract code or need a fresh contract ID.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v20 recommended; v18 minimum) - Download
npm (bundled with Node.js) - this repo includes frontend/package-lock.json
Git - Download
Stellar CLI - Install Guide
Rust (for Soroban contracts) - Install
Test XLM Tokens - Get from Stellar Testnet Faucet

Installation

Clone the Repository

git clone https://github.com/Soumen1080/ACREDIA-STELLAR.git
cd ACREDIA-STELLAR

Install Frontend Dependencies

cd frontend
npm ci

Install Contract Build Toolchain

cd ../contracts
# Install the WASM32 build target (one-time setup)
rustup target add wasm32-unknown-unknown
# Install Stellar CLI if not already installed
cargo install --locked stellar-cli

Configuration

Set Up Environment Variables

Copy the canonical frontend example:

cd ..\frontend
Copy-Item .env.local.example .env.local

Edit frontend\.env.local and replace placeholder values:

# Smart Contract Addresses — Stellar Testnet (deployed 2026-04-01)
# Single unified AcrediaCredential contract (replaces separate NFT + Registry)
NEXT_PUBLIC_CREDENTIAL_NFT_CONTRACT=CCGDFDLPELTOWG5H5OA4MBR5OZWDP4XJI3S3TQZVZ7XTVP77EKOFORYF
NEXT_PUBLIC_CREDENTIAL_REGISTRY_CONTRACT=CCGDFDLPELTOWG5H5OA4MBR5OZWDP4XJI3S3TQZVZ7XTVP77EKOFORYF

# Stellar Network Configuration
NEXT_PUBLIC_CHAIN_ID=testnet
NEXT_PUBLIC_NETWORK_NAME=testnet
NEXT_PUBLIC_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
NEXT_PUBLIC_HORIZON_URL=https://horizon-testnet.stellar.org
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Admin access control
# Comma-separated list of emails that may access admin API routes.
# Admin accounts must be provisioned by a trusted Supabase/service-role process.
ADMIN_EMAIL_ALLOWLIST=admin@example.com

# Pinata IPFS (server-side only; set this in the frontend app environment)
PINATA_JWT=your_pinata_jwt_token
# Optional: custom Pinata gateway domain
# NEXT_PUBLIC_PINATA_GATEWAY=https://your-gateway.mypinata.cloud

For contract deployment secrets, copy the contract example only when you are deploying:

cd ..\contracts
Copy-Item .env.example .env

Then edit contracts\.env:

STELLAR_NETWORK=testnet
STELLAR_SOURCE_ACCOUNT=deployer
STELLAR_CONTRACT_ID=

Production warning: Keep SUPABASE_SERVICE_ROLE_KEY, PINATA_JWT, and all Stellar secret keys server-only. Never put service-role keys, Pinata JWTs, or Stellar secret keys in NEXT_PUBLIC_* variables, browser code, screenshots, logs, or GitHub issues.

Database Setup

Set Up Supabase Database

Run the canonical SQL setup listed in frontend/sql/README.md. For a fresh Supabase project, run only these scripts in your Supabase SQL Editor:

-- Run these in order:
1. frontend/sql/database_schema.sql
2. frontend/sql/secure_rls_migration.sql

database_schema.sql creates tables, indexes, triggers, and enables RLS without opening broad public policies. secure_rls_migration.sql is the canonical production policy set and can be safely re-run after older deployments.

The older one-off SQL repair scripts are retained only as compatibility notices: they point back to the canonical setup flow and should not be run for new deployments.

Smart Contract Deployment

The public testnet contract is already listed in frontend/.env.local.example. Skip this section unless you changed contracts/src/lib.rs, need an isolated test deployment, or are preparing a production deployment.

Set Up Stellar Identity

# Generate a new Stellar account for deployment
stellar keys generate --network testnet deployer

# Fund the account with testnet XLM from Friendbot
stellar keys fund deployer --network testnet

# Confirm your address
stellar keys address deployer

Build & Deploy AcrediaCredential Contract

cd contracts

# Step 1: Build the WASM binary
cargo build --target wasm32-unknown-unknown --release

# Step 2: Deploy to Stellar Testnet
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/acredia_credential.wasm \
  --source deployer \
  --network testnet
# => Returns: CCGDFDLPELTOWG5H5OA4MBR5OZWDP4XJI3S3TQZVZ7XTVP77EKOFORYF

# Step 3: Initialize the contract with your admin address
stellar contract invoke \
  --id CCGDFDLPELTOWG5H5OA4MBR5OZWDP4XJI3S3TQZVZ7XTVP77EKOFORYF \
  --source deployer \
  --network testnet \
  -- initialize \
  --owner $(stellar keys address deployer)

# Step 4: Authorize an institution to issue credentials
stellar contract invoke \
  --id CCGDFDLPELTOWG5H5OA4MBR5OZWDP4XJI3S3TQZVZ7XTVP77EKOFORYF \
  --source deployer \
  --network testnet \
  -- authorize_issuer \
  --issuer <INSTITUTION_STELLAR_ADDRESS>

For Mainnet deployment, replace --network testnet with --network public and use a funded mainnet account.

📝 Note: The contract is already deployed to testnet. You only need to re-deploy if you modify the contract code.

Running the Application

Start the Development Server

cd frontend
npm run dev

Open in Browser

Navigate to http://localhost:3000

Production Build

cd frontend
npm ci
npm run build
npm start

Before deploying to production:

Use Stellar Public Network values only after contract review and a verified mainnet deployment.
Rotate any secret that was pasted into chat, screenshots, logs, browser code, or an issue.
Set server-only secrets (SUPABASE_SERVICE_ROLE_KEY, PINATA_JWT, Stellar secret keys) only in the hosting provider's protected environment variables.
Confirm Supabase RLS is enabled and production policies come from frontend/sql/secure_rls_migration.sql.
Verify contract IDs on Stellar Expert before pointing users at a production environment.

⚙️ Environment Setup

Getting API Keys

Pinata IPFS Setup

Visit Pinata and sign up for free (no credit card required)
Go to API Keys → New Key
Enable pinFileToIPFS and pinJSONToIPFS permissions
Copy the JWT token
Add it to your frontend .env.local as PINATA_JWT=... so only the server routes can use it.

Free tier: 1 GB storage, unlimited pins — more than enough for development and testing.

Supabase Setup

Create account at Supabase
Create a new project
Get your project URL and anon key from Settings > API
Run the canonical SQL scripts in SQL Editor (see frontend/sql/README.md):
- frontend/sql/database_schema.sql
- frontend/sql/secure_rls_migration.sql

The older repair scripts are kept for legacy deployments only. For a clean clone, use the two scripts above.

Stellar Account Setup

Create Stellar account using Stellar CLI:

stellar keys generate --network testnet admin

Fund your account with test XLM:

stellar keys fund admin --network testnet

Get your public key: stellar keys address admin
For testnet, fund from Stellar Testnet Faucet

Wallet Setup for Stellar Network

Install Stellar Wallet (Options):
- Stellar Laboratory - Web-based
- Freighter Wallet - Browser extension (recommended)
- StellarTerm - Web interface
Create or Import Wallet:
- Generate new Stellar keypair or import existing
- Save your secret key securely (never share!)
Configure for Testnet:
- Network: Stellar Testnet
- Horizon API: https://horizon-testnet.stellar.org
- Soroban RPC: https://soroban-testnet.stellar.org
- Network Passphrase: Test SDF Network ; September 2015
Get Test XLM Tokens:
- Visit Stellar Testnet Faucet
- Click "Get Test Network Lumens"
- Select Account ID
- Enter your public key
- Request 10,000 test XLM
- Tokens arrive instantly
For Mainnet Deployment (Production):
- Network: Stellar Public Network
- Horizon API: https://horizon.stellar.org
- Soroban RPC: https://soroban-mainnet.stellar.org
- Network Passphrase: Public Global Stellar Network ; September 2015
- Purchase XLM from exchange or use peer-to-peer transfers

📖 Usage Guide

For Administrators

Authorizing Institutions

Connect the contract owner wallet
Navigate to Admin Dashboard
Enter institution wallet address
Click "Authorize Wallet"
Confirm blockchain transaction
Institution can now issue credentials

For Institutions

Issuing a Credential

Login with authorized institution account
Go to Dashboard > Issue Credential tab
Fill in student details:
- Student Name
- Student Wallet Address
- Credential Type (Degree, Certificate, etc.)
- Degree/Major/GPA
- Issue Date
Add subjects (click "+ Add Subject"):
- Subject Name
- Marks Obtained
- Maximum Marks
- Grade (optional)
Click "Issue Credential"
Confirm wallet transaction
Wait for confirmation
Student receives NFT in their wallet

Viewing Issued Credentials

Go to Dashboard > Issued Credentials tab
View all credentials issued by your institution
See blockchain transaction hashes
Access IPFS metadata links

For Students

Viewing Your Credentials

Login with student account
Dashboard displays all your credentials
Click on any credential to see:
- Institution details
- Credential type and dates
- Subject-wise marks and grades
- Overall performance statistics
- Blockchain verification proof

Sharing Credentials

Click "Share" on any credential
Options:
- Generate QR Code
- Copy verification link
- Share token ID
Recipients can verify without login

For Verifiers (Employers/Universities)

Verifying Credentials

Go to verification page (no login required)
Enter credential token ID OR scan QR code
View complete credential details:
- Student information
- Issuing institution
- Academic records
- Subject-wise performance
- Blockchain proof
Click blockchain link to verify on Stellar Expert
Confirm credential is authentic and not revoked on Stellar Network

📁 Project Structure

Frontend Directory Structure

frontend/
├── public/
│   ├── logo.png                    # Acredia logo
│   ├── Acredia.png                 # Brand assets
│   └── screenshots/                # UI screenshots
├── src/
│   ├── app/
│   │   ├── page.tsx               # Landing page
│   │   ├── layout.tsx             # Root layout with providers
│   │   ├── globals.css            # Global styles
│   │   ├── about/
│   │   │   └── page.tsx           # About page
│   │   ├── admin/
│   │   │   └── page.tsx           # Admin dashboard
│   │   ├── api/
│   │   │   └── admin/
│   │   │       ├── stats/route.ts          # Statistics API
│   │   │       └── update-authorization/   # Authorization sync
│   │   ├── auth/
│   │   │   ├── login/             # Student/Institution login
│   │   │   ├── register/          # User registration
│   │   │   ├── admin-login/       # Admin authentication
│   │   │   └── admin-setup/       # Initial admin setup
│   │   ├── dashboard/
│   │   │   └── page.tsx           # User dashboard
│   │   └── verify/
│   │       └── page.tsx           # Public verification page
│   ├── components/
│   │   ├── institution/
│   │   │   ├── AuthorizeIssuer.tsx           # Authorization UI
│   │   │   ├── CredentialUploadForm.tsx      # Issuance form
│   │   │   └── IssuedCredentialsList.tsx     # Issued credentials
│   │   ├── student/
│   │   │   ├── StudentCredentialsList.tsx    # Student's credentials
│   │   │   ├── QRCodeModal.tsx              # QR code display
│   │   │   └── CredentialDiagnostic.tsx     # Debug component
│   │   ├── verification/
│   │   │   └── (verification components)
│   │   ├── shared/
│   │   │   └── (shared components)
│   │   └── ui/
│   │       ├── button.tsx         # Button component
│   │       ├── card.tsx           # Card component
│   │       ├── input.tsx          # Input component
│   │       ├── form.tsx           # Form components
│   │       └── (other UI primitives)
│   ├── contexts/
│   │   └── AuthContext.tsx        # Authentication context
│   ├── hooks/
│   │   └── useAuth.ts             # Authentication hook
│   ├── lib/
│   │   ├── contracts.ts           # Smart contract interactions
│   │   ├── credentialService.ts   # Credential issuance service
│   │   ├── ipfs.ts                # IPFS upload utilities
│   │   ├── supabase.ts            # Supabase client
│   │   ├── stellar.ts             # Stellar/Soroban configuration
│   │   └── utils.ts               # Utility functions
│   └── types/
│       └── index.ts               # TypeScript type definitions
├── package.json                    # Dependencies
├── tsconfig.json                   # TypeScript config
├── next.config.ts                  # Next.js configuration
├── tailwind.config.js              # Tailwind CSS config
├── postcss.config.mjs              # PostCSS config
└── components.json                 # Shadcn UI config

Contracts Directory Structure

contracts/
├── src/
│   └── lib.rs                     # Soroban Smart Contract
├── Cargo.toml                     # Rust/Soroban dependencies
├── Makefile                       # Build and deployment scripts
└── target/                        # Compiled WASM build output

Database Schema (Supabase)

credentials
├── id (uuid)
├── token_id (bigint) - NFT token ID
├── student_id (uuid) - Reference to students
├── institution_id (uuid) - Reference to institutions
├── ipfs_hash (text) - IPFS metadata hash
├── blockchain_hash (text) - Transaction hash
├── metadata (jsonb) - Credential details
├── metadata_schema_version (integer) - Canonical metadata schema version
├── hash_algorithm (text) - Hash algorithm identifier
├── issued_at (timestamp)
├── revoked (boolean)
├── revoked_at (timestamp)
├── student_wallet_address (text)
└── issuer_wallet_address (text)

students
├── id (uuid)
├── email (text)
├── name (text)
├── wallet_address (text)
└── created_at (timestamp)

institutions
├── id (uuid)
├── email (text)
├── name (text)
├── wallet_address (text)
├── verified (boolean)
└── created_at (timestamp)

verification_logs
├── id (uuid)
├── credential_id (uuid)
├── verified_at (timestamp)
└── verification_result (jsonb)

Credential Metadata Hashing

Credential hashes are derived from a versioned canonical payload, not directly from raw JSON.stringify(metadata).

Current schema: metadata_schema_version = 1
Current algorithm: hash_algorithm = sha256:canonical-json:v1
Shared implementation: frontend/src/lib/credentialHash.ts
Test vectors: frontend/tests/credentialHash.test.ts

Schema v1 hashes only the credential meaning needed for verification: name, description, image, student wallet/name, credential type, degree, major, GPA, issue date, institution name, and normalized subjects. Optional fields are represented as null or empty arrays, numeric-like values are converted to strings where the UI treats them as text, and object keys are serialized in sorted canonical order.

Future metadata fields can be added to stored metadata or IPFS display metadata without changing old hashes. To make a new field part of the on-chain digest, add a new schema version and algorithm identifier, keep the v1 builder intact, add new fixed test vectors, store the new version on newly issued credentials, and keep verification dispatching by each row's stored metadata_schema_version and hash_algorithm.

🔐 Security Features

Smart Contract Security

Rust & Soroban: Memory-safe and highly deterministic smart contracts
Access Control: Only authorized issuers can mint credentials
Owner Authorization: Contract owner controls authorization
Soroban Security: Built-in protections against common smart contract vulnerabilities

Application Security

Row Level Security (RLS): Supabase database policies
Wallet Authentication: Cryptographic signature verification
Environment Variables: Sensitive data never committed
HTTPS Only: All production traffic encrypted
Public Verification: No authentication required for verification

Data Privacy

Student Control: Students own their credential NFTs
Selective Disclosure: Share only what's necessary
IPFS Storage: Decentralized, censorship-resistant
No PII on Blockchain: Personal data only in IPFS/database

🎨 Design Philosophy

Acredia follows modern web design principles:

Responsive: Works on desktop, tablet, and mobile
Accessible: WCAG 2.1 compliant components
Consistent: Unified design system with Tailwind CSS
Intuitive: Clear user flows and interactions
Professional: Gradient accents and modern aesthetics
Fast: Optimized with Next.js App Router

🧪 Testing

Running Tests

# Contract tests (Rust based)
cd contracts
cargo test

# Build WASM
cargo build --target wasm32-unknown-unknown --release

# Frontend tests (if configured)
cd frontend
npm test

Testing on Stellar Testnet

Before testing, ensure:

Freighter Wallet is connected to Stellar Testnet
You have sufficient test XLM tokens in your wallet
Environment variables are properly configured

Manual Testing Checklist

Network & Wallet

Freighter Wallet connected to Stellar Testnet
Test XLM tokens available in wallet
Contract addresses correct in .env.local

Credential Issuance

Institution can issue credential on Stellar Network
Transaction completes within 3-5 seconds
Student receives NFT in wallet
Metadata uploaded to IPFS successfully
Database record created with correct chain data
Subject-wise marks displayed correctly
Gas fees are minimal (< $0.01)

Verification

Public verification page loads
Token ID search works
QR code scanning works
Stellar Expert blockchain link redirects correctly
Subject table displays properly
Transaction hash verifiable on Stellar Expert

Authorization

Admin can authorize institutions
Unauthorized wallets cannot issue
Authorization status updates in database

🚧 Roadmap

Phase 1: Core Features ✅

Phase 2: Enhanced Features 🚧

Bulk credential issuance
Advanced filtering and search
Email notifications
PDF certificate generation
Stellar Network integration (Fast and low cost)

Phase 3: Advanced Features 📋

Phase 4: Enterprise Features 🔮

🐛 Troubleshooting

Common Issues

Problem: Freighter Wallet not connecting

Solution: Ensure you're on Stellar Testnet and site permissions are granted
Refresh the page and try connecting again

Problem: "Wrong Network" error

Solution: Switch to Stellar Testnet in your wallet settings

Problem: Transaction failing

Solution: Check you have enough test XLM tokens in your wallet
Verify wallet is authorized to issue credentials (for institutions)
Ensure your sequence number is correct

Problem: Contract deployment fails

Solution: Verify your identity is funded on testnet (stellar keys fund deployer --network testnet)
Ensure sufficient XLM balance for deployment
Check Soroban SDK version compatibility in Cargo.toml

Problem: IPFS upload timeout / failed

Ensure PINATA_JWT is set in your frontend .env.local
Verify the JWT is valid at app.pinata.cloud
Check your internet connection and try again
Free tier is limited to 1 GB — check your Pinata dashboard usage

Problem: Verification page shows "not found"

Solution: Ensure RLS policies are enabled in Supabase (run SQL scripts)
Check contract addresses in .env.local are correct
Verify token ID exists on blockchain

Problem: Subjects not displaying

Solution: Clear browser cache and reload page
Ensure IPFS metadata contains subjects array
Check IPFS gateway is accessible

📄 License

License

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

🙏 Acknowledgements

Built with amazing open-source technologies:

Next.js - React framework
Stellar Network - Decentralized network for global financial infrastructure
Pinata - Immutable IPFS file storage APIs
Supabase - Open-source Firebase alternative
Soroban SDK - Native smart contracts platform for Stellar
Tailwind CSS - Utility-first CSS framework
Radix UI - Accessible component primitives
Lucide Icons - Beautiful icon library
IPFS - Decentralized storage network

📞 Contact & Support

For questions, feedback, or support:

Open an issue on GitHub Issues
Check existing issues for solutions
Include setup steps, affected file paths, expected behavior, actual behavior, and labels such as bug, docs, frontend, contracts, or database.

Thank You!

Making Academic Credentials Secure, Transparent, and Accessible on Stellar Network

⭐ Star this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 140 Commits
.github		.github
contracts		contracts
frontend		frontend
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md

Folders and files

Latest commit

History

Repository files navigation

ACREDIA

Blockchain-Based Academic Credential Verification System

🎯 Built on Stellar Network

🌐 VIEW LIVE DEMO

📽️ VIEW LIVE DEMO

📑 Table of Contents

🌟 Overview

Why Acredia?

🚀 Why Stellar Network?

Key Benefits

Network Details

🎯 The Problem

💡 Our Solution Is

📸 Screenshots

Landing Page

Student Dashboard

Institution Dashboard

Credential Verification

Admin Panel

IPFS Decentralized Storage

⚡ Key Features

For Students

For Institutions

For Verifiers (Employers/Universities)

For Administrators

📜 Smart Contracts

✅ AcrediaCredential Contract — Live on Testnet

Stellar Testnet Deployment (Active)

Stellar Mainnet Deployment (Production)

🔍 Smart Contract Verification Links (Important!)

🛠 Technology Stack

Frontend

Blockchain (Stellar)

Storage & Backend

Development Tools

🧪 Testing Strategy

1. Smart Contract Constraints (Rust)

2. Frontend Validation & Logic (Vitest)

3. Edge-case SDK Resiliency (Implemented)

🏗 System Architecture

Architecture Layers

Why This Architecture?

🔄 How It Works

Credential Issuance Flow

Verification Flow

Step-by-Step Process

For Institutions (Issuing Credentials)

For Students (Viewing Credentials)

For Verifiers (Checking Credentials)

🚀 Getting Started

Clean Clone Quick Start

Prerequisites

Installation

Configuration

Database Setup

Smart Contract Deployment

Running the Application

Production Build

⚙️ Environment Setup

Getting API Keys

Pinata IPFS Setup

Supabase Setup

Stellar Account Setup

Wallet Setup for Stellar Network

📖 Usage Guide

For Administrators

For Institutions

For Students

For Verifiers (Employers/Universities)

📁 Project Structure

Frontend Directory Structure

Contracts Directory Structure

Database Schema (Supabase)

Credential Metadata Hashing

🔐 Security Features

Smart Contract Security