StrellerMinds-SmartContracts

StrellerMinds-SmartContracts is a comprehensive suite of Stellar smart contracts built with Soroban, powering the StarkMinds blockchain education platform. This repository provides secure, efficient on-chain logic for educational credentialing, learning analytics, token incentives, and progress tracking. Designed for educational institutions, online learning platforms, and EdTech developers who need reliable blockchain infrastructure for verifiable learning achievements and decentralized education ecosystems.

Documentation site: https://starkmindshq.github.io/StrellerMinds-SmartContracts

🚀 Quick Start

Get up and running in under 5 minutes:

# 1. Clone the repository
git clone https://github.com/StarkMindsHQ/StrellerMinds-SmartContracts.git
cd StrellerMinds-SmartContracts

# 2. Build all contracts
./scripts/build.sh

# 3. Run tests
cargo test

That's it! Your contracts are built and tested. See Getting Started for detailed installation instructions.

✨ Features

• Smart contract development using Soroban on Stellar
• Secure, efficient on-chain logic for education and credentialing
• Comprehensive testing suite for contract functionality
• Modular and scalable design for future enhancements
• Role-Based Access Control (RBAC) across all contracts
• Advanced analytics and progress tracking
• Multi-signature certificate issuance
• Token incentive system with staking capabilities

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Rust (v1.75 or later)
• Stellar CLI & Soroban CLI
• Docker (optional, for running a local Stellar testnet)
• Node.js v18+ (for E2E tests)

Quick Setup: Use our automated setup script to install all prerequisites:

./scripts/setup.sh

This script will automatically:

• Install Rust target wasm32-unknown-unknown
• Install Soroban CLI (pinned version 21.5.0)
• Install Stellar CLI (pinned version 21.5.0)
• Verify all installations
• Optionally install Binaryen (wasm-opt) for WASM optimization

Required Environment Variables

• STELLAR_SECRET_KEY - Your Stellar secret key for deployment

🛠️ Getting Started

Installation

1. Clone the Repository:

   git clone https://github.com/StarkMindsHQ/StrellerMinds-SmartContracts.git
   cd StrellerMinds-SmartContracts

2. Run the Setup Script (Recommended):

   ./scripts/setup.sh

   This automated script will set up your entire development environment, including:

   • Rust toolchain with WASM target
   • Soroban CLI (v21.5.0)
   • Stellar CLI (v21.5.0)
   • Optional: Binaryen for WASM optimization

   The script will guide you through the installation process and verify all components.

3. Build the Smart Contracts:

   ./scripts/build.sh
   # Or manually:
   cargo build --release --target wasm32-unknown-unknown

Testing

Unit Tests

Run unit tests to ensure everything is functioning as expected:

cargo test

End-to-End (E2E) Tests

Run the complete E2E test suite against a local Soroban network:

./scripts/run-e2e-tests.sh

This will:

• Build all contracts
• Start a local Soroban network
• Deploy contracts
• Run integration tests
• Clean up resources

For more details, see the E2E Test Documentation.

Linting and Formatting

To maintain code quality and consistency, run the following commands locally before committing:

• Format code:

  cargo fmt

• Check for linting issues:

  cargo clippy -- -D warnings

These checks are also enforced in CI and will fail the build if there are formatting issues or warnings.

🚢 Deployment

The repository includes a comprehensive deployment script for Soroban smart contracts supporting multiple networks:

Deployment Script Usage

./scripts/deploy.sh --network <local|testnet|mainnet> --contract <name> --wasm <path> [--dry-run]

Available Flags

Flag	Description
--network <network>	Specify which network to deploy to (local, testnet, or mainnet)
--contract <name>	Name of the contract to deploy
--wasm <path>	Path to the WASM file to deploy
--dry-run	Simulate the deployment steps without executing them

Quick Deployment Examples

# Dry-run deployment to testnet (preview only)
./scripts/deploy_testnet.sh --dry-run

# Deploy specific contract to testnet
./scripts/deploy_testnet.sh --contract certificate

# Verbose deployment with custom profile
./scripts/deploy_mainnet.sh --contract certificate --profile myprofile --verbose

Environment Configuration

Network-specific settings are managed via .env.<network> files. The script automatically loads the correct configuration based on the --network flag.

Before Deploying

1. Build and optimize contracts:

   cargo build --release --target wasm32-unknown-unknown

2. Set required environment variables:

   export STELLAR_SECRET_KEY='your_secret_key_here'

3. Optional: Set custom RPC endpoint:

   export SOROBAN_RPC_URL='https://your-rpc-endpoint.com'

After successful deployment, contract IDs are saved to:

target/<contract_name>.<network>.id

For advanced configurations, see the Soroban documentation.

📦 Smart Contracts

This repository contains several smart contracts that power the StarkMinds educational platform:

Core Contracts

• Analytics Contract - Comprehensive learning analytics and progress tracking with performance metrics and engagement insights
• Token Contract - Token management with incentive system, staking capabilities, and reward mechanisms
• Shared Contract - Common utilities including RBAC, reentrancy protection, and validation functions

Supporting Contracts

• Mobile Optimizer Contract - Mobile optimization with offline capabilities and gas optimization
• Progress Contract - Simple course progress tracking with validation
• Proxy Contract - Upgradeable contract implementation with rollback support
• Search Contract - Advanced search system with saved searches and analytics
• Student Progress Tracker Contract - Granular module-level progress tracking

Contract Documentation

Each contract includes comprehensive documentation covering:

• Overview: Purpose and main functionality
• Interface: Public functions and parameters
• Events: Emitted events and their schemas
• Configuration: Settings and environment variables
• Testing: Unit and integration test examples

Note: Some contracts were removed during cleanup to ensure project stability. See the cleanup notes for details.

🤝 Contributing

We welcome contributions to improve our smart contracts!

1. Fork the repository
2. Create a new branch:

   git checkout -b feature/your-feature-name

3. Make your changes with clear, descriptive commit messages
4. Ensure tests pass:

   cargo test
   cargo fmt
   cargo clippy

5. Push your branch and open a pull request with a detailed description

Please read our Contributing Guidelines for more details.

📚 Documentation

• Published Site: https://starkmindshq.github.io/StrellerMinds-SmartContracts/
• Development Guide
• Security Guidelines
• RBAC Implementation
• Mobile Optimizer System
• Token Incentive System
• Security Audit Report

📖 Quickstart: Contributing to Documentation

1. Install dependencies (Python 3.x):

   pip install mkdocs mkdocs-material

2. Run local preview from the repo root:

   mkdocs serve

   Open http://127.0.0.1:8000 to view the docs.
3. Edit content in docs/. The homepage is docs/index.md.
4. Update navigation in mkdocs.yml under the nav: section.
5. Submit a PR. The site auto-deploys to GitHub Pages on merges to main.

📝 License

This project is licensed under the terms specified in the LICENSE file.

🧹 Cleanup Notes

This repository has undergone significant cleanup to ensure stability and maintainability:

Removed Components

• Certificate Contract - Had extensive compilation errors and missing trait implementations
• Mint Batch Certificates Contract - Type conversion issues and incomplete implementation
• Unused files - .DS_Store, node_modules, and other temporary files

Current Status

• ✅ All remaining contracts compile successfully
• ✅ Core functionality preserved (analytics, token, shared utilities)
• ✅ Tests passing for shared contract
• ⚠️ Minor warnings remain (non-critical unused variables)

Repository Structure

StrellerMinds-SmartContracts/
├── contracts/
│   ├── analytics/          # Learning analytics and progress tracking
│   ├── token/              # Token management with incentives
│   ├── shared/             # Common utilities and RBAC
│   ├── mobile-optimizer/   # Mobile optimization features
│   ├── progress/           # Simple progress tracking
│   ├── proxy/              # Upgradeable contract pattern
│   ├── search/             # Search functionality
│   └── student-progress-tracker/  # Granular progress tracking
├── e2e-tests/            # End-to-end integration tests
├── docs/                  # Comprehensive documentation
├── scripts/               # Build, deploy, and utility scripts
└── Cargo.toml            # Workspace configuration

🔗 Helpful Links

Development & Documentation

• Published Documentation - Full API documentation and guides
• Development Guide - Detailed setup and development workflow
• Security Guidelines - Security best practices and audit reports
• RBAC Implementation - Role-based access control documentation
• Mobile Optimizer System - Mobile optimization architecture
• Token Incentive System - Token economics and incentives

Platform & Community

• StarkMinds Website - Main platform website
• Stellar Documentation - Stellar network documentation
• Soroban Documentation - Smart contract development guide
• Issue Tracker - Bug reports and feature requests
• Discussions - Community discussions and Q&A

Contribution Resources

• Contributing Guidelines - Detailed contribution process
• Code of Conduct - Community guidelines
• Release Process - How releases are managed
• Architecture Overview - High-level system design

📧 Support

For questions or support, please:

• Open an issue
• Check our documentation
• Join our community discussions

---