AetherMint

AetherMint is a decentralized learning and credential verification platform powered by Stellar blockchain. It enables secure, tamper-proof issuance and verification of educational credentials, certificates, and achievements using Soroban smart contracts.

🎯 Features

• 📚 Decentralized Learning - Course creation and management on blockchain
• 🎓 Credential Verification - Tamper-proof certificates and achievements
• 🔗 Stellar Integration - Fast, low-cost transactions on Stellar
• 💼 Professional Profiles - On-chain learning history and skills
• 🏆 Achievement System - NFT-based badges and milestones
• 📊 Learning Analytics - Progress tracking and insights
• 🔐 Secure Storage - IPFS integration for content persistence
• 🔮 Holographic Storage - Advanced 3D data storage simulation
• 🌐 Cross-Platform - Web and mobile applications

🛠️ Technology Stack

Blockchain Layer

• Stellar - Fast, scalable Layer 1 blockchain
• Soroban - Smart contract platform for Stellar
• Stellar SDK - JavaScript/TypeScript integration

Frontend

• Next.js 14 - React framework with App Router
• TypeScript - Type-safe development
• TailwindCSS - Utility-first CSS framework
• Stellar Wallets - Freighter, Albedo, and more
• IPFS - Decentralized content storage

Backend

• Node.js - Server-side JavaScript runtime
• Express.js - Fast, minimalist web framework
• PostgreSQL - Robust relational database
• Redis - High-performance caching
• Prisma - Modern database ORM
• JWT - Secure authentication
• IPFS HTTP Client - Decentralized storage integration

Smart Contracts

• Rust - Memory-safe smart contract language
• Soroban SDK - Stellar smart contract development
• Shared Storage Utilities - Reusable packing/hashing helpers for gas-efficient state

🚀 Quick Start

Prerequisites

• Node.js (v18+)
• npm or yarn
• PostgreSQL
• Redis
• Freighter or compatible Stellar wallet
• Rust (stable toolchain, 1.84+)
• Soroban SDK (26.1.0)
• Soroban CLI (26.1.0)

Rust and Soroban Setup

Install Rust

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add wasm32v1-none target (required for Soroban contracts with Rust 1.84+)
rustup target add wasm32v1-none

Note: If you have Rust 1.82 or earlier, use wasm32-unknown-unknown instead. However, Rust 1.84+ is recommended and requires the newer wasm32v1-none target.

Install Soroban CLI

# Install specific version for compatibility
cargo install --locked stellar-cli --version 26.1.0

# Verify installation
stellar version

Version Compatibility Matrix

Component	Version	Notes
soroban-sdk	26.1.0	Pinned with = in Cargo.toml
stellar-cli (soroban-cli)	26.1.0	Must match SDK version
Rust toolchain	1.84.0+ (stable)	Required for wasm32v1-none target
wasm32v1-none	(installed via rustup)	Required build target for Rust 1.84+
wasm32-unknown-unknown	(legacy)	Only for Rust 1.81 or earlier

Important:

• The soroban-sdk and stellar-cli versions must be compatible. We use exact version pinning (=26.1.0) to ensure consistency across development and CI environments.
• Rust 1.84.0+ requires the wasm32v1-none target instead of the legacy wasm32-unknown-unknown target.
• If you're using Rust 1.82 or 1.83, you must downgrade to Rust 1.81 or upgrade to 1.84+.

Installation

# Clone the repository
git clone https://github.com/AetherEdu/AetherMint.git
cd AetherMint

# Install dependencies
npm run install:all

# Set up environment
cp .env.example .env
# Edit .env with your configuration

# Start development
npm run dev

Development Setup

# Start Stellar network (local)
stellar standalone start

# Deploy contracts
cd contracts
npm run deploy:local

# Start backend
cd ../backend
npm run dev

# Start frontend
cd ../frontend
npm run dev

📐 Architecture Decision Records

Significant architectural decisions are documented as Architecture Decision Records (ADRs) in docs/adr/.

ADR	Decision	Status
001	Stellar/Soroban over Ethereum/EVM	Accepted
002	Dual database (PostgreSQL + MongoDB)	Accepted
003	IPFS for decentralized content storage	Accepted
004	Federated learning for AI/ML features	Accepted
005	Quantum-resistant cryptography	Proposed
006	Microservices-lite architecture	Accepted
007	TypeScript gradual migration	Accepted

See the ADR index for details.

📁 Project Structure

AetherMint/
├── contracts/              # Soroban smart contracts (Rust)
│   ├── src/
│   │   ├── lib.rs       # Main contract logic
│   │   └── test.rs      # Contract tests
│   └── Cargo.toml        # Rust dependencies
├── frontend/               # Next.js React application
│   ├── src/
│   │   ├── app/          # App Router pages
│   │   ├── components/    # Reusable UI components
│   │   └── lib/          # Utility functions
│   ├── public/             # Static assets
│   └── package.json        # Frontend dependencies
├── backend/                # Node.js API server
│   ├── src/
│   │   ├── routes/       # API endpoints
│   │   ├── models/        # Database models
│   │   ├── middleware/    # Auth and validation
│   │   └── utils/         # Helper functions
│   └── package.json        # Backend dependencies
├── docs/                   # Project documentation
└── scripts/                # Deployment and utility scripts

🔧 Smart Contracts

The core Soroban contracts handle:

• CredentialRegistry - Stores and verifies educational credentials
• CourseManager - Manages course creation and enrollment
• AchievementIssuer - Handles NFT-based achievement badges
• ProfileManager - Manages on-chain learning profiles

Building Contracts

# Navigate to contracts directory
cd contracts

# Build for wasm32v1-none target (required for Rust 1.84+)
cargo build --target wasm32v1-none --release

# OR for Rust 1.81 or earlier, use the legacy target:
# cargo build --target wasm32-unknown-unknown --release

# Run tests
cargo test --release

# The compiled WASM will be in:
# target/wasm32v1-none/release/aethermint_education_contracts.wasm
# (or target/wasm32-unknown-unknown/release/ for legacy target)

Important: Make sure you're using the correct target for your Rust version:

• Rust 1.84+: Use wasm32v1-none (recommended)
• Rust 1.81 or earlier: Use wasm32-unknown-unknown
• Rust 1.82-1.83: Not supported - upgrade to 1.84+ or downgrade to 1.81

Deploying Contracts

# Build the contract first with stellar contract build (recommended)
stellar contract build

# OR manually build
cargo build --target wasm32v1-none --release

# Deploy to testnet
stellar contract deploy \
  --wasm target/wasm32v1-none/release/aethermint_education_contracts.wasm \
  --network testnet

# Deploy to local standalone network
stellar contract deploy \
  --wasm target/wasm32v1-none/release/aethermint_education_contracts.wasm \
  --network standalone

Testing Contracts

# Run all contract tests
cd contracts
cargo test

# Run specific test
cargo test test_credential_issuance

# Run with output
cargo test -- --nocapture

⚡ Storage Optimization

Our smart contracts implement advanced storage optimization techniques to reduce gas costs and improve deployment efficiency:

🔑 Key Optimizations

1. Bit Packing - Multiple boolean flags and small integers packed into single bytes
2. Hash-Based Storage - Large strings and vectors stored as hashes to save space
3. Separate Storage Tiers - Frequently vs infrequently accessed data separated
4. Packed Timestamps - Creation and update timestamps combined in single U256
5. Optimized Ratings - Rating values and review counts packed together
6. Shared Utilities - Common storage patterns abstracted into reusable utilities

📊 Gas Savings Results

Contract	Storage Slots (Before)	Storage Slots (After)	Reduction	Gas Savings
UserProfile	10	6	40%	~2,500 gas
CourseMetadata	17	12	29%	~3,200 gas
Credential	9	7	22%	~1,800 gas
Achievement	7	5	28%	~1,500 gas
Overall	43	30	30%	~9,000 gas

🔬 Technical Implementation

// Before: Separate fields
pub struct UserProfile {
    pub created_at: u64,
    pub updated_at: u64,
    pub is_verified: bool,
    pub is_active: bool,
    pub privacy_level: PrivacyLevel,
}

// After: Packed storage
pub struct UserProfile {
    pub timestamps: PackedTimestamps,  // 2 timestamps in 1 U256
    pub flags: PackedUserFlags,       // 5 flags in 1 byte
}

🧪 Benchmarking

Run gas usage benchmarks:

cd contracts
cargo test --release -- --nocapture test_gas_benchmarks

Generate detailed gas report:

stellar contract invoke \
  --id <contract-id> \
  --fn generate_gas_report \
  --wasm target/wasm32v1-none/release/aethermint_education_contracts.wasm

📖 API Documentation

AetherMint ships with fully interactive API reference documentation built on OpenAPI 3.0 / Swagger.

Resource	URL	Description
Swagger UI	http://localhost:3001/api/docs	Interactive browser-based API explorer
Raw OpenAPI spec	http://localhost:3001/api/docs/json	Machine-readable JSON spec for tooling
Developer Portal	http://localhost:3002	Full playground with code generation and auth docs
Auth Docs	http://localhost:3002/auth-docs	JWT flow, API key usage, roles & error codes
Published docs	GitHub Pages	Auto-updated on every push to main

To start the documentation locally:

# Swagger UI is served automatically by the backend
cd backend && npm run dev           # → http://localhost:3001/api/docs

# Developer portal (API Playground + Auth Docs)
cd backend/portal && npm run dev    # → http://localhost:3002

The OpenAPI spec is validated on every CI run — a PR fails if fewer than 10 paths are documented or the spec is structurally invalid.

🌐 API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User authentication
• POST /api/auth/refresh - Token refresh

Courses

• GET /api/courses - List available courses
• POST /api/courses - Create new course
• GET /api/courses/:id - Course details
• POST /api/courses/:id/enroll - Enroll in course

Credentials

• POST /api/credentials/issue - Issue new credential
• GET /api/credentials/:id - Verify credential
• GET /api/credentials/user/:address - User credentials

Profiles

• GET /api/profiles/:address - Learning profile

IPFS Content Management

• POST /api/content/upload - Upload file to IPFS
• POST /api/content/upload/batch - Upload multiple files
• GET /api/content/:cid - Retrieve content from IPFS
• GET /api/content/:cid/metadata - Get content metadata
• POST /api/content/:cid/pin - Pin content to IPFS
• DELETE /api/content/:cid/pin - Unpin content from IPFS
• GET /api/content/health - Check IPFS service health

Holographic Storage

• POST /api/holographic/encode - Encode content in holographic format
• GET /api/holographic/decode/:hash - Decode holographic content
• POST /api/holographic/access/parallel - High-speed parallel access
• GET /api/holographic/metrics - Storage density and performance metrics
• POST /api/holographic/optimize - Optimize storage density

📁 IPFS Integration

AetherMint integrates with IPFS (InterPlanetary File System) for decentralized content storage, providing:

Features

• File Upload & Storage - Upload educational content to IPFS with metadata
• Content Retrieval - Retrieve content in multiple formats (buffer, base64, stream)
• Progress Tracking - Real-time upload progress with WebSocket support
• Authentication - JWT-based auth with role-based permissions
• Caching - In-memory caching for improved performance
• Error Handling - Comprehensive error handling with retry mechanisms

Usage

import ipfsClient from './lib/ipfs';

// Upload a file
const result = await ipfsClient.uploadFile(file, {
  metadata: { course: 'math101' },
  onProgress: (progress) => console.log(`${progress.progress}%`)
});

// Retrieve content
const content = await ipfsClient.getContent(result.cid, 'base64');

Configuration

See backend/.env.example for IPFS configuration options.

For detailed documentation, see IPFS_INTEGRATION_README.md.

🔮 Holographic Storage System

AetherMint includes an advanced holographic storage abstraction layer that simulates 3D spatial data storage:

Features

• 3D Spatial Encoding - Data mapped to interference patterns in 3D space
• High-Speed Parallel Access - Simultaneous retrieval up to 15,000 MB/s
• Holographic Compression - Wavelet-based compression (2-3x ratio)
• Storage Density Optimization - Automatic optimization achieving 80-90% density
• Hardware-Ready API - Designed for future physical holographic hardware integration

Usage

// Encode educational content
const result = await fetch('/api/holographic/encode', {
  method: 'POST',
  body: JSON.stringify({
    contentId: 'course-101',
    data: Buffer.from(content).toString('base64')
  })
});

// Parallel access for multiple resources
const materials = await fetch('/api/holographic/access/parallel', {
  method: 'POST',
  body: JSON.stringify({ hashes: [hash1, hash2, hash3] })
});

For detailed documentation, see HOLOGRAPHIC_STORAGE_README.md.

Gas Optimization

• GET /api/gas/benchmarks - View gas usage benchmarks
• GET /api/gas/report - Generate optimization report
• GET /api/gas/compare - Compare old vs new storage patterns

🎓 Use Cases

For Students

• Earn Verifiable Certificates - Complete courses, earn blockchain-verified credentials
• Build On-Chain Portfolio - Showcase learning history and achievements
• Lifelong Learning Records - Persistent, portable academic records

For Educators

• Create Blockchain Courses - Deploy courses with smart contract integration
• Issue Digital Certificates - Automate credential issuance
• Track Student Progress - Monitor engagement and completion

For Institutions

• Verify Credentials Instantly - Eliminate fraud with on-chain verification
• Reduce Administrative Overhead - Automate certificate management
• Global Credential Recognition - Cross-border verification

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🐛 Found a Bug?

• Create an issue

💡 Feature Request?

• Suggest a feature

🔒 Security Issue?

Please do not report vulnerabilities in public issues. Email security@aetheredu.xyz — see SECURITY.md for our disclosure process.

👥 Contributors

Thanks to all our contributors! See the CONTRIBUTORS.md file for details.

📄 License

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

🌟 Community

• Discord
• Twitter
• GitHub Discussions
• Website

📊 Project Status

• Version: 0.1.0 (Alpha)
• Network: Stellar Testnet
• Status: Under Development
• Roadmap: View Project Board
• Gas Optimization: ✅ 30% storage reduction achieved
• Holographic Storage: ✅ Software abstraction layer implemented
• Latest Update: Holographic storage system with 3D spatial encoding

🏆 Optimization Achievements

• ✅ 30% overall storage reduction across all contracts
• ✅ Bit packing implementation for boolean flags and small integers
• ✅ Hash-based storage for large data structures
• ✅ Separate storage tiers for access pattern optimization
• ✅ Comprehensive benchmarking suite implemented
• ✅ Shared storage utilities for code reuse and consistency

📈 Performance Metrics

• Deployment Gas: Reduced by ~9,000 gas per contract deployment
• Transaction Gas: 15-25% reduction in average transaction costs
• Storage Efficiency: 30% fewer storage slots used
• Code Maintainability: Improved with shared utilities and patterns

---

⭐ Star this repository to support decentralized education on Stellar!