🌌 NUSA CHAIN

A High-Performance Blockchain with Advanced DeFi & Gaming Features

Multi-Language • Rust Core • Go Backend • Python AI • Production-Grade Architecture

🚀 Quick Start • 📖 Documentation • 💎 Features • 💰 Tokenomics • ⛏️ Mining Guide

89+ REST API Endpoints • 37K+ Lines of Code • Active Development

🎯 What is NUSA Chain?

NUSA Chain is an experimental blockchain platform designed for education, research, and prototyping advanced blockchain concepts. It combines a Rust-based core with Go backend services and Python AI components to explore DeFi primitives, Layer 2 scaling, and blockchain gaming infrastructure.

⚠️ Development Status: This is an unaudited research project. Not recommended for production use with real funds.

💎 Features Overview

📊 Feature Status Matrix

Feature Category	Status	Implementation Level	Documentation
🏗️ Core Blockchain	✅ Implemented	Production-grade Rust	Code
🗳️ DAO Governance	✅ Implemented	5 REST endpoints	API
🪙 Token & NFT (ERC-20/721)	✅ Implemented	8 REST endpoints	API
🎨 NFT Marketplace	✅ Implemented	9 REST endpoints	API
🔄 DEX/AMM	✅ Implemented	8 REST endpoints	API
🏦 Lending Protocol	✅ Implemented	10 REST endpoints	Docs
💵 NUSD Stablecoin	✅ Implemented	7 REST endpoints	API
🌉 Cross-Chain Bridge	🧪 Experimental	Basic framework	Code
🔒 Privacy Layer	🧪 Experimental	ZK framework	Code
📜 WASM Contracts	✅ Implemented	6 REST endpoints	Code
🔮 zkVM Integration	🧪 Experimental	3 REST endpoints	Code
📊 Rollups (L2)	✅ Implemented	12 REST endpoints	Code
🎮 GameFi Platform	✅ Implemented	28 REST endpoints	Code
💰 UBI System	✅ Implemented	Go backend	Server
🤖 AI Services	✅ Implemented	3 Python bots	Services
🔐 Quantum-Resistant Crypto	🗺️ Planned	Library imported	-
🛡️ MEV Protection	🗺️ Planned	Not implemented	-
🌐 Multi-VM (Move, EVM)	🧪 Experimental	Partial WASM only	Code

Legend:

✅ Implemented = Working code + REST endpoints + tests
🧪 Experimental = Partial implementation, needs refinement
🗺️ Planned = Documented but not yet implemented

Total: 89+ REST API Endpoints operational across 13 integrated modules.

🏗️ Core Features (Detailed)

⚡ Blockchain Infrastructure

🔗 Consensus Mechanism

Algorithm: TurboBFT (Byzantine Fault Tolerant)
Block Time: ~2 seconds target
Validator System: Permissionless with stake requirements
Implementation: src/consensus/

⛏️ Mining & Distribution

Mining-Based Token Distribution:

Block reward: 50 NUSA (halves every 190,000 blocks)
Miner share: 98% (49 NUSA)
UBI pool: 2% (1 NUSA)
Max supply: 19,000,000 NUSA
Pre-mine: 950,000 NUSA (5% dev fund)

Start Mining:

MINING_MODE=true MINER_ADDRESS=your_address ./target/release/nusa-node

📚 Complete Mining Guide

💰 Sustainable UBI System

Daily allocation: 5 NUSA per verified person
Funding sources:
- 2% mining tax (from block rewards)
- 30% of transaction fees
- No pre-allocation (self-sustaining!)
Anti-sybil: WorldID/Gitcoin Passport verification
Backend: Go service (l1-core/cmd/ubi-server/)

Test UBI:

curl http://localhost:8080/ubi/statistics

📚 UBI Documentation

💰 DeFi Ecosystem

🪙 ERC-20 & ERC-721 Tokens - Fungible & Non-Fungible Assets

Fungible Tokens (ERC-20):

Create custom cryptocurrencies
Transfer, balance queries
DeFi integration ready

Non-Fungible Tokens (ERC-721):

Mint unique digital assets
Ownership tracking
Marketplace compatible

Endpoints: 8 REST APIs
Test: ./test-token-nft.sh

📚 Token API Documentation

🎨 NFT Marketplace - Full marketplace with auctions

Features:

Fixed-price listings
Time-based auctions with bidding
Creator royalties (configurable)
Marketplace fee (2.5%)

Endpoints: 9 REST APIs
Test: ./test-marketplace.sh

📚 Marketplace API

🔄 Decentralized Exchange (DEX) - AMM with liquidity pools

AMM Features:

Constant product formula (x × y = k)
Liquidity pools with LP tokens
Token swaps with slippage protection
0.3% trading fee (LP rewards)

Endpoints: 8 REST APIs
Test: ./test-dex.sh

📚 DEX API Documentation

🏦 Lending Protocol - Collateralized lending + flash loans

Lending Features:

Deposit collateral, borrow assets
Dynamic interest rates (2-22% APY)
Health factor monitoring
Flash loans (0.09% fee)
Liquidation system (5% penalty)

Endpoints: 10 REST APIs
Test: ./test-lending.sh

💵 NUSD Stablecoin - Algorithmic USD-pegged asset

Stablecoin Design:

Target: $1.00 (±$0.01 tolerance)
150% over-collateralization with NUSA
Automatic rebalancing
Liquidation at 120% ratio

Endpoints: 7 REST APIs
Test: ./test-stablecoin.sh

🚀 Advanced Features

📊 Layer 2 Rollups - Optimistic + ZK rollups framework

Rollup Support:

Optimistic rollups (7-day challenge)
ZK rollups (instant finality)
Sovereign rollups
Fraud proof system

Endpoints: 12 REST APIs
Test: ./test-rollups.sh

🎮 GameFi Platform - Complete gaming ecosystem

Gaming Features:

Multi-game management
Player profiles (XP, reputation)
NFT items (6 rarity tiers)
Tournament system
Guild/clan mechanics
Token staking (APY rewards)
Lootbox system
In-game marketplace

Endpoints: 28 REST APIs (most extensive module)
Test: ./test-gamefi.sh

📚 GameFi Implementation - 1,420 lines

📜 WASM Smart Contracts - WebAssembly execution

WASM Support:

Deploy WASM contracts
Execute contract calls
Query contract state
Gas metering

Endpoints: 6 REST APIs
Test: ./test-wasm.sh

🌉 Cross-Chain Bridge - Multi-chain interoperability (Experimental)

Status: Framework implemented, production bridges need external validator networks.

Planned Support:

Ethereum (enum defined)
Bitcoin (planned)
Solana (planned)
Others (framework ready)

Endpoints: 9 REST APIs
Code: src/rpc/bridge.rs

⚠️ Note: This is experimental. Real cross-chain bridges require external infrastructure.

🤖 AI Layer

🔍 AI Smart Contract Auditor

Vulnerability pattern detection
Security scoring (0-100)
Gas optimization suggestions
Implementation: l3-ai/src/auditor.py

📈 AI Trading Bot

Arbitrage detection
Price monitoring
Trade execution
Implementation: l3-ai/src/trading_bot.py

🔎 AI Block Explorer

Real-time block indexing
Transaction analytics
Implementation: l3-ai/src/block_explorer.py

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      NUSA CHAIN STACK                       │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: AI & Services (Python)                           │
│  ├─ Auditor (79 lines)                                     │
│  ├─ Trading Bot (120 lines)                                │
│  └─ Explorer (95 lines)                                    │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: VM & Execution (Rust)                            │
│  ├─ 13 RPC Modules (89+ endpoints)                         │
│  ├─ WASM Runtime (wasmtime)                                │
│  └─ Rollups Framework                                      │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Core Blockchain (Rust + Go)                      │
│  ├─ Consensus (TurboBFT)                                   │
│  ├─ Mining System                                          │
│  ├─ State Management                                       │
│  └─ UBI Server (Go)                                        │
├─────────────────────────────────────────────────────────────┤
│  Storage & Infrastructure                                   │
│  ├─ PostgreSQL (state + indexer)                           │
│  ├─ Redis (optional caching)                               │
│  └─ Grafana (monitoring)                                   │
└─────────────────────────────────────────────────────────────┘

🚀 Quick Start

Option 1: Docker (Recommended)

# Clone repository
git clone https://github.com/alejandrozahran-cyber/NusaChain.git
cd NusaChain

# Start all services (blockchain + UBI + AI)
docker-compose up -d

# Check service health
docker-compose ps

# View logs
docker-compose logs -f nusa-node

Services Started:

nusa-node (Blockchain RPC) → http://localhost:8545
postgres (Database) → localhost:5432
nusa-go (Event processor) → http://localhost:8081
nusa-ubi-server (UBI distribution) → http://localhost:8080
nusa-ai-auditor (Contract auditor) → http://localhost:8001
nusa-ai-trading (Trading bot) → http://localhost:8002
nusa-ai-explorer (Block explorer) → http://localhost:8003
grafana (Monitoring) → http://localhost:3001

📚 Complete Docker Guide

Option 2: Build from Source

Prerequisites

Rust 1.70+ (rustup)
Go 1.21+
Python 3.11+
PostgreSQL 14+
Docker (optional)

Build Steps

# 1. Clone repository
git clone https://github.com/alejandrozahran-cyber/zahran-2-chain.git
cd zahran-2-chain

# 2. Build Rust blockchain
cargo build --release

# 3. Build Go services
cd l1-core
go build -o ubi-server ./cmd/ubi-server
cd ..

# 4. Setup Python environment
cd l3-ai
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cd ..

# 5. Setup database
createdb nusa_chain
psql nusa_chain < schema.sql  # if schema exists

# 6. Run blockchain
./target/release/nusa-node

# 7. Run UBI server (separate terminal)
cd l1-core
./ubi-server

# 8. Run AI services (separate terminal)
cd l3-ai
python src/auditor.py &
python src/trading_bot.py &
python src/block_explorer.py &

Option 3: Mining Mode

# Start mining (CPU mining)
MINING_MODE=true \
MINER_ADDRESS=your_wallet_address \
./target/release/nusa-node

📚 Mining Guide - Rewards, pools, hardware requirements

🧪 Testing

Run All Tests

./test-all-features.sh

Test Individual Modules

./test-governance.sh       # Governance (8 tests)
./test-token-nft.sh        # Tokens & NFTs (12 tests)
./test-marketplace.sh      # NFT Marketplace (15 tests)
./test-dex.sh              # DEX/AMM (18 tests)
./test-lending.sh          # Lending (22 tests)
./test-stablecoin.sh       # Stablecoin (24 tests)
./test-bridge.sh           # Bridge (12 tests)
./test-privacy.sh          # Privacy (10 tests)
./test-zkvm.sh             # zkVM (8 tests)
./test-wasm.sh             # WASM (10 tests)
./test-rollups.sh          # Rollups (17 tests)
./test-gamefi.sh           # GameFi (45 tests)

Total: 16 test scripts, 229+ automated tests

📖 Documentation

Core Documentation

Getting Started - Setup guide (if exists)
Architecture - System design
Tokenomics - Economic model (19M max supply)
Mining Guide - Mining setup & rewards
UBI System - Universal Basic Income
Whitepaper - Technical whitepaper

API Documentation

REST API Reference - Core endpoints
Token & NFT API - ERC-20/721
Marketplace API - NFT marketplace
DEX API - Decentralized exchange
Governance API - DAO governance

Technical Guides

TPS Optimization - Performance tuning
Parallel Execution - Concurrency design
Token Standards - Token specifications
Deployment Guide - Production deployment

💰 Tokenomics

Token Supply (Mining-Based Model)

Parameter	Value
Max Supply	19,000,000 NUSA (fixed cap)
Pre-mine	950,000 NUSA (5% - dev fund)
Mineable Supply	18,050,000 NUSA (95%)
Initial Block Reward	50 NUSA
Halving Interval	Every 190,000 blocks (~11 months)
Mining Tax	2% → UBI pool
Transaction Fee Split	70% burn, 30% → UBI pool

Token Distribution

Total: 19,000,000 NUSA
├─ Mineable: 18,050,000 (95.0%)
│  ├─ Miner Rewards: 17,688,100 NUSA (98% of mining)
│  └─ UBI Pool Tax: 361,900 NUSA (2% of mining)
└─ Pre-mine: 950,000 (5.0%)
   └─ Development Fund

UBI Sustainability

Self-Funding Model (no pre-allocation):

Income: 2% mining tax + 30% tx fees
Distribution: 5 NUSA/person/day
Early Stage: Surplus accumulation (750 NUSA/day income, 500 expense)
Growth Stage: Balanced by reserves
Mature Stage: Tx fees > expenses

📚 Complete Tokenomics

🔐 Security Status

⚠️ Security Disclaimer

IMPORTANT: This is an UNAUDITED experimental project.

Known Limitations:

❌ No professional security audit
❌ No bug bounty program
❌ Not tested in production with real funds
❌ Cryptographic primitives not formally verified
⚠️ Quantum-resistant crypto imported but not active
⚠️ MEV protection not implemented
⚠️ Cross-chain bridges are experimental

🛡️ Security Measures Implemented

✅ Input validation on all RPC endpoints
✅ Signature verification for transactions
✅ Rate limiting (basic)
✅ SQL injection prevention (SQLx parameterized queries)
✅ Test coverage for critical paths

🐛 Bug Reporting

If you discover a security vulnerability:

DO NOT open a public issue
Email: [security contact needed]
Include: description, reproduction steps, impact assessment

📊 Performance & Benchmarks

⚡ Performance Targets

Current Status: Benchmarking in progress

Metric	Target	Status	Notes
TPS	50,000+	🧪 Testing	Requires GPU verification + Redis
Block Time	2s	✅ Achieved	Configurable
Finality	2s	✅ Achieved	Single-slot finality
Gas Cost	Low	✅ Optimized	Dynamic gas market

🔬 Running Benchmarks

# Parallel execution benchmark
./benchmark-parallel.sh

# Extreme performance test (requires tuning)
./benchmark-extreme.sh

# Standard benchmark
cargo bench

Note: High TPS claims (50K+) require specific hardware configurations:

GPU for signature verification
Redis for state caching
Optimized BlockSTM execution

📚 Missing: Reproducible benchmark documentation (to be created)

🎓 Academic & Research Use

This project is suitable for:

✅ Blockchain education & teaching
✅ Research papers & thesis work
✅ Prototyping blockchain concepts
✅ Learning Rust/Go/Python integration
✅ DeFi protocol design studies

Cite this project:

NUSA Chain: A Multi-Language Blockchain Research Platform
URL: https://github.com/alejandrozahran-cyber/zahran-2-chain
Year: 2024-2026

🗺️ Roadmap

✅ Completed (2024-2025)

🔄 In Progress (Q1 2026)

🗺️ Planned (2026+)

👥 Contributing

Contributions are welcome! This is an open-source research project.

How to Contribute:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

📚 Contributing Guide

📞 Community & Support

GitHub: @alejandrozahran-cyber
Repository: zahran-2-chain
Issues: GitHub Issues

📄 License

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

🙏 Acknowledgments

NUSA Chain incorporates ideas and learning from:

Bitcoin (Mining, UTXO)
Ethereum (Smart contracts, EVM)
Solana (Parallel execution concepts)
Cosmos (IBC inspiration)
Aptos/Sui (Move language concepts)

Special thanks to the Rust, Go, and open-source blockchain communities.

⚠️ Final Disclaimer

NUSA Chain is experimental software for research and education.

Not financial advice
No guarantees of security or functionality
Use at your own risk
Not recommended for production with real value
Developers not liable for any losses

For serious blockchain projects, always:

Get professional security audits
Conduct thorough testing
Start with testnets
Have incident response plans
Comply with local regulations

Built with curiosity for blockchain technology

⭐ If this project helps your research, please star it! ⭐

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
docker		docker
docs		docs
examples		examples
explorer-backend		explorer-backend
explorer-frontend		explorer-frontend
kms		kms
l1-core		l1-core
l2-vm		l2-vm
l3-ai		l3-ai
monitoring		monitoring
pq-ffi		pq-ffi
scripts		scripts
src		src
wallet-app		wallet-app
web3-client		web3-client
.gitattributes		.gitattributes
.gitignore		.gitignore
ARCHITECTURE.txt		ARCHITECTURE.txt
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
MINING.md		MINING.md
README.md		README.md
SECURITY.md		SECURITY.md
TESTNET_LAUNCH_GUIDE.md		TESTNET_LAUNCH_GUIDE.md
TOKENOMICS.md		TOKENOMICS.md
deploy-testnet.sh		deploy-testnet.sh
docker-compose.yml		docker-compose.yml
test-all-features.sh		test-all-features.sh
test-block-time.sh		test-block-time.sh
test-bridge.sh		test-bridge.sh
test-dex.sh		test-dex.sh
test-gamefi.sh		test-gamefi.sh
test-governance.sh		test-governance.sh
test-lending.sh		test-lending.sh
test-marketplace.sh		test-marketplace.sh
test-parallel-execution.sh		test-parallel-execution.sh
test-privacy.sh		test-privacy.sh
test-rollups.sh		test-rollups.sh
test-stablecoin.sh		test-stablecoin.sh
test-token-nft.sh		test-token-nft.sh
test-token-transfer.sh		test-token-transfer.sh
test-wasm.sh		test-wasm.sh
test-zkvm.sh		test-zkvm.sh
testnet-config.toml		testnet-config.toml

License

alejandrozahran-cyber/NusaChain

Folders and files

Latest commit

History

Repository files navigation