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

🌐 Live app (Stellar testnet)

Product Vision · Architecture · Contributing · Security

📑 Table of Contents

Overview
Why Stellar Network
The Problem
Our Solution
Who Benefits
Key Features
Smart Contracts
Technology Stack
Testing Strategy
System Architecture
How It Works
Getting Started
Environment Setup
Usage Guide
Project Structure
Documentation
Contributing

🌟 Overview

Acredia is a decentralized platform that transforms how academic credentials are issued, stored, and verified. Built on the Stellar network — designed for fast, low-cost, globally accessible transactions — Acredia combines a Soroban smart contract, IPFS storage, and a modern web app to eliminate credential fraud, cut verification time from days to seconds, and give students lifetime ownership of their records.

Vision. The trust layer for academic credentials: institutions issue tamper-proof credentials, students own them for life, and anyone verifies them in seconds — for free.

For the full product vision, personas, differentiators, and business model, see docs/product/vision.md.

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

👥 Who Benefits

Acredia connects four roles around a single, shared source of truth. See the Usage Guide for detailed walkthroughs and docs/product/vision.md for the full product vision, personas, and business model.

Role	What they get	How they use it
🏛 Institutions (universities, colleges, bootcamps, cert bodies)	Fraud-proof credentials and near-zero verification overhead.	1. Get approved as an authorized issuer → 2. Connect a Stellar wallet → 3. Fill the issuance form (student, degree, subjects, document) → 4. Sign the transaction to mint the credential on-chain and pin the document to IPFS. Revoke anytime.
🎓 Students / graduates	Lifelong, portable ownership of their achievements.	1. Sign up and link a wallet → 2. Receive credentials directly in the dashboard → 3. Share a verification link or QR code with employers → 4. Export/download the credential whenever needed.
✅ Verifiers (employers, ATS, admissions)	Instant, free authenticity checks.	1. Open the shared link or scan the QR (or enter a token ID) on `/verify` → 2. See authenticity, revocation status, and credential details in seconds — no account required.
🛡 Admins / operators	Governance of who can be trusted to issue.	1. Review institution applications → 2. Authorize legitimate issuers on-chain → 3. Monitor issuance/verification statistics.

⚡ 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 single unified Soroban smart contract, AcrediaCredential, written in Rust and deployed on the Stellar network.

✅ AcrediaCredential Contract — Live on Testnet

Contract ID: CARWFW27MJ3OJADAUAHI3TDFHIL62YMLVEKTUTMSNXOMH7JJTNZKC3DK
Network: Stellar Testnet
Owner / Deployer: GAMI3XDDII72W23RADNPPAZ2GYEZ2MTYXLETOU36R4ISXMQ7IURFEKFP
Deployed: 2026-06-27 (Redeployed) 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(BytesN<32>) → persistent storage (SHA-256 hash bytes → 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 (Deferred — testnet now, mainnet later)

Acredia is production-ready on Stellar testnet today. Mainnet deployment is intentionally deferred — going live is a configuration switch (NEXT_PUBLIC_STELLAR_NETWORK + contract addresses) once the mainnet-readiness checklist (independent contract audit, key custody, keeper strategy — see the roadmap backlog) is complete. Mainnet endpoints, for reference:

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

Layer	Technology	Purpose
Frontend	Next.js 16 (App Router), React 19, TypeScript	Web app + server API routes
UI / styling	Tailwind CSS v4, Radix UI, Framer Motion, Lucide	Design system, accessible primitives, motion, icons
Auth	Supabase Auth	Email/password sessions and JWTs
Wallet	Freighter (`@stellar/freighter-api`)	Stellar wallet connection & transaction signing
Smart contract	Rust + Soroban SDK	`AcrediaCredential` — issuance, authorization, revocation
Blockchain	Stellar (testnet) · Soroban RPC · Horizon	Ledger, contract calls, network queries
Client SDK	`@stellar/stellar-sdk`	Build / simulate / submit transactions, read contract state
Storage	IPFS via Pinata	Credential documents & metadata (encryption on the roadmap)
Database	Supabase (PostgreSQL) + Row Level Security	Off-chain index: profiles, credentials, verification logs
Testing	Vitest, Cargo test, `@vitest/coverage-v8`	Frontend, contract, and coverage
Tooling	npm, ESLint, Prettier, Stellar CLI, GitHub Actions	Dev, lint/format, deploy, CI

🧪 Testing Strategy

Acredia employs a layered testing methodology across the smart contract, the frontend, and the Stellar SDK integration.

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 TD
    U["Student · Institution · Verifier"]
    FE["Next.js App (React 19)"]
    FW["Freighter Wallet"]
    API["Next.js API Routes"]
    AUTH["Supabase Auth"]
    DB[("Supabase Postgres + RLS")]
    IPFS[("IPFS via Pinata")]
    SC["AcrediaCredential (Soroban)"]
    L[("Stellar Ledger")]

    U --> FE
    FE --> AUTH
    FE --> FW
    FE --> API
    FE -->|"read / verify (RPC)"| SC
    FW -->|"sign issue / revoke tx"| SC
    API --> DB
    API --> IPFS
    SC --> L

    style FE fill:#0ea5e9,color:#fff
    style SC fill:#f59e0b,color:#000
    style IPFS fill:#8b5cf6,color:#fff
    style DB fill:#10b981,color:#fff
    style AUTH fill:#10b981,color:#fff

Deeper dive: see docs/architecture.md for component responsibilities and the full issue / verify / revoke data flows, frontend/VERIFIABLE_CREDENTIALS.md for the W3C Verifiable Credential / Open Badges 3.0 metadata schema, field mapping, and a third-party verification recipe, and frontend/PIN_REDUNDANCY.md for the IPFS pin-redundancy/keeper durability guarantee.

Data flow (summary)

Issue: institution fills the form → document + metadata (modeled as a W3C VC / Open Badges 3.0 document) pinned to IPFS → SHA-256 hash computed over the canonical payload → issuer signs issue_credential(student, issuer, hash, ipfs_uri) via Freighter → the credential is written on-chain and indexed in Postgres.
Verify: anyone opens /verify (token/QR) → the app reads the credential from the contract via Soroban RPC → shows authenticity + revocation status; a privacy-safe entry is recorded in verification_logs.
Revoke: the original issuer signs revoke_credential(token_id, issuer) → the on-chain record is flagged revoked (still readable, so verifiers see "revoked" not "missing") → the index is updated.

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 wasm32v1-none
# 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-06-27)
# Single unified AcrediaCredential contract (replaces separate NFT + Registry)
NEXT_PUBLIC_CREDENTIAL_NFT_CONTRACT=CARWFW27MJ3OJADAUAHI3TDFHIL62YMLVEKTUTMSNXOMH7JJTNZKC3DK
NEXT_PUBLIC_CREDENTIAL_REGISTRY_CONTRACT=CARWFW27MJ3OJADAUAHI3TDFHIL62YMLVEKTUTMSNXOMH7JJTNZKC3DK

# Stellar Network Configuration
NEXT_PUBLIC_STELLAR_NETWORK=testnet

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
# Server-only (set in hosting secret store for production)
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
VERIFICATION_LOG_HASH_SECRET=your_random_audit_hash_secret

# 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, VERIFICATION_LOG_HASH_SECRET, and all Stellar secret keys server-only. Never put server secrets in NEXT_PUBLIC_* variables, browser code, screenshots, logs, or GitHub issues.

Database Setup

Set Up Supabase Database

Run the canonical SQL setup in your Supabase SQL Editor. For a fresh Supabase project, run the single idempotent setup file:

frontend/sql/FULL_SETUP.sql

FULL_SETUP.sql creates tables, indexes, triggers, canonical credential hash metadata columns, and production RLS policies. It can be safely re-run after older deployments. frontend/sql/database_schema.sql is kept as a focused base schema reference, but clean deployments should use FULL_SETUP.sql.

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 wasm32v1-none --release

# Step 2: Deploy to Stellar Testnet
stellar contract deploy \
  --wasm target/wasm32v1-none/release/acredia_stellar.wasm \
  --source deployer \
  --network testnet
# => Returns: CARWFW27MJ3OJADAUAHI3TDFHIL62YMLVEKTUTMSNXOMH7JJTNZKC3DK

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

# Step 4: Authorize an institution to issue credentials
stellar contract invoke \
  --id CARWFW27MJ3OJADAUAHI3TDFHIL62YMLVEKTUTMSNXOMH7JJTNZKC3DK \
  --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:

Switch to Mainnet: Set NEXT_PUBLIC_STELLAR_NETWORK=mainnet in your production environment variables to point the application to the live Stellar network.
Keep one network switch: Use only NEXT_PUBLIC_STELLAR_NETWORK (testnet, mainnet, or custom). Testnet/Mainnet profiles are boot-time validated and endpoint/passphrase overrides are blocked.
Update Contract Addresses: Ensure NEXT_PUBLIC_CREDENTIAL_NFT_CONTRACT and NEXT_PUBLIC_CREDENTIAL_REGISTRY_CONTRACT are updated to your verified mainnet deployment IDs. (The app will fail to boot if it detects the known testnet contract on mainnet).
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, VERIFICATION_LOG_HASH_SECRET, Stellar secret keys) only in the hosting provider's protected environment variables.
Confirm Supabase RLS is enabled and production policies come from frontend/sql/FULL_SETUP.sql.
Verify contract IDs on Stellar Expert before pointing users at a production environment.

See SECRETS_ROTATION.md for the complete key-rotation runbook and pre-commit/CI secret-scan workflow.

⚙️ 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 frontend/sql/FULL_SETUP.sql in the Supabase SQL Editor.

The base frontend/sql/database_schema.sql file is retained as a schema reference. For a clean clone, use FULL_SETUP.sql.

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 logo (favicon/icon source)
│   ├── favicon.ico / icon.png      # Site icons
│   └── auth-illustration.png       # Marketing illustration
├── 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)
├── created_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
Legacy schema: metadata_schema_version = 0, hash_algorithm = sha256:json-stringify
Shared implementation: frontend/src/lib/credentialHash.ts
Stellar byte encoding: frontend/src/lib/credentialHashEncoding.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, ISO date-times are normalized to YYYY-MM-DD, 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 wasm32v1-none --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

The full, current production & market backlog (25 issues covering privacy, standards, indexer/worker, verification API, docs, and more) lives in ISSUE_DRAFTS.md. The phases below are a high-level summary.

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

📚 Documentation

Deeper documentation lives under docs/:

Product Vision & Positioning — what Acredia is, who it's for, personas, differentiators, and the business model.
Architecture — components, layers, and the issue / verify / revoke data flows.
Contract reference — the Soroban AcrediaCredential contract, storage/TTL model, and deployment.
Roadmap & backlog — the production & market issue backlog.
API reference — planned (see the "public verification API" item in the backlog).

🤝 Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the workflow, coding standards, and how to run the test suite.

Security: found a vulnerability? Follow the responsible-disclosure process in SECURITY.md — please do not open a public issue for security reports.
Issue labels: bug, docs, frontend, contracts, database, security.

📄 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 335 Commits
.github		.github
contracts		contracts
docs		docs
frontend		frontend
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
FUNDING.json		FUNDING.json
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

📑 Table of Contents

🌟 Overview

Why Acredia?

🚀 Why Stellar Network?

Key Benefits

Network Details

🎯 The Problem

💡 Our Solution Is

👥 Who Benefits

⚡ 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 (Deferred — testnet now, mainnet later)

🔍 Smart Contract Verification Links (Important!)

🛠 Technology Stack

🧪 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

Application Security

Data Privacy

🎨 Design Philosophy

🧪 Testing

Running Tests

Testing on Stellar Testnet

Manual Testing Checklist

🚧 Roadmap

Phase 1: Core Features ✅

Phase 2: Enhanced Features 🚧

Phase 3: Advanced Features 📋

Phase 4: Enterprise Features 🔮