🏗️ System Architecture
This document provides wireframes and diagrams showing how the Fleet SDK Tutorial system works and how all components connect.
High-Level Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ FLEET SDK TUTORIAL SYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 📚 Docs │ │ 🎮 Playground│ │ 🧪 Tests │ │ 💻 Examples │ │
│ │ VitePress │ │ Browser │ │ Vitest │ │ TypeScript │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ └──────────────────┼──────────────────┼──────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌───────────────────────────────┐ │
│ │ 🔧 Fleet SDK Core │ │
│ │ @fleet-sdk/core + modules │ │
│ └───────────────┬───────────────┘ │
│ │ │
├────────────────────────────────────┼───────────────────────────────────────┤
│ │ │
│ ┌──────────────────────────┼──────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 🔗 Testnet │ │ 🔗 Mainnet │ │ 🧪 MockChain│ │
│ │ Explorer │ │ Explorer │ │ (Local) │ │
│ │ API │ │ API │ │ │ │
│ └──────┬──────┘ └──────┬──────┘ └─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Ergo Testnet│ │ Ergo Mainnet│ │
│ │ Nodes │ │ Nodes │ │
│ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Component Breakdown
1. User Interface Layer
┌─────────────────────────────────────────────────────────────────┐
│ USER INTERFACE LAYER │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ 📖 VitePress │ │ 🎮 Playground │ │
│ │ Documentation │ │ (index.html) │ │
│ ├─────────────────────┤ ├─────────────────────┤ │
│ │ • Tutorials │ │ • Monaco Editor │ │
│ │ • Concepts │ │ • Code Examples │ │
│ │ • Examples │ │ • Run Button │ │
│ │ • Guides │ │ • Output Console │ │
│ │ • Troubleshooting │ │ • Error Display │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │ │ │
│ │ HTTP (localhost:5173) │ │
│ └────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ npm run docs:dev │ │
│ │ (Vite Dev Server) │ │
│ └───────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘2. Fleet SDK Module Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ FLEET SDK MODULES │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ @fleet-sdk/core │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │ Transaction │ │ Output │ │ ErgoAddress │ │ │
│ │ │ Builder │ │ Builder │ │ │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │ Box │ │ Token │ │ Constants │ │ │
│ │ │ Selection │ │ Helpers │ │ (SAFE_MIN_BOX_VALUE) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────┼─────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ @fleet- │ │ @fleet- │ │ @fleet- │ │
│ │ sdk/wallet │ │ sdk/crypto │ │sdk/compiler │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ • Signing │ │ • Hashing │ │ • ErgoScript│ │
│ │ • Keys │ │ • Encoding │ │ • Compile │ │
│ │ • Mnemonics │ │ • Base58 │ │ • Validate │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ @fleet- │ │ @fleet- │ │ @fleet- │ │
│ │sdk/serializ │ │ sdk/common │ │sdk/mock-chai│ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ • Sigma │ │ • Types │ │ • MockChain │ │
│ │ • ErgoTree │ │ • Utilities │ │ • Test Boxes│ │
│ │ • Registers │ │ • Helpers │ │ • Simulate │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘3. Network Connection Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ NETWORK CONNECTION FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────┐ │
│ │ Your Application │ │
│ │ (Tutorial Examples) │ │
│ └───────────┬───────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ ErgoExplorerClient │ │
│ │ (testnet-integration)│ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌───────┴───────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ │
│ │ TESTNET │ │ MAINNET │ │
│ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ERGO EXPLORER API │ │
│ ├─────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ TESTNET: https://api-testnet.ergoplatform.com │ │
│ │ MAINNET: https://api.ergoplatform.com │ │
│ │ │ │
│ │ Endpoints: │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ GET /api/v1/boxes/unspent/byAddress/{address} → Fetch UTXOs │ │ │
│ │ │ GET /api/v1/boxes/{boxId} → Get Box │ │ │
│ │ │ GET /api/v1/tokens/{tokenId} → Token Info │ │ │
│ │ │ POST /api/v1/mempool/transactions/submit → Submit TX │ │ │
│ │ │ GET /api/v1/transactions/{txId} → TX Status │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ERGO BLOCKCHAIN │ │
│ ├─────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Node │────▶│ Node │────▶│ Node │────▶│ Node │ │ │
│ │ │ #1 │◀────│ #2 │◀────│ #3 │◀────│ #N │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │ │ │ │ │
│ │ └───────────────┴───────────────┴───────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────┐ │ │
│ │ │ Blockchain │ │ │
│ │ │ (UTXOs) │ │ │
│ │ └─────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Transaction Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ TRANSACTION LIFECYCLE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1️⃣ FETCH UTXOs │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ User │ ──GET──▶│ Explorer │ ──GET──▶│ Ergo Node │ │
│ │ Code │◀─UTXOs──│ API │◀─UTXOs──│ │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │ │
│ ▼ │
│ 2️⃣ BUILD TRANSACTION │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ TransactionBuilder │ │
│ ├─────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ .from([utxos]) ──▶ Select input boxes │ │
│ │ .to(OutputBuilder) ──▶ Define outputs │ │
│ │ .sendChangeTo(address) ──▶ Handle change │ │
│ │ .payFee(amount) ──▶ Set mining fee │ │
│ │ .build() ──▶ Create unsigned TX │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 3️⃣ SIGN TRANSACTION │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Unsigned │ @fleet-sdk/wallet │ Signed │ │ │
│ │ │ Transaction │ ──────────────────▶ │ Transaction │ │ │
│ │ └──────────────┘ (Private Key) └──────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 4️⃣ SUBMIT TO NETWORK │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Signed │ ──POST─▶│ Explorer │ ──POST─▶│ Ergo Node │ │
│ │ TX │◀─TxId───│ API │◀─TxId───│ Mempool │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │ │
│ ▼ │
│ 5️⃣ CONFIRMATION │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Mempool ──▶ Block Mining ──▶ Block Added ──▶ TX Confirmed │ │
│ │ ⏱️ ⛏️ 📦 ✅ │ │
│ │ (~1 sec) (~2 min) (1 confirm) (10+ confirms) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Testing Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ TESTING ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ TEST RUNNER (Vitest) │ │
│ ├─────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ npm test │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ TEST FILES (86 tests) │ │ │
│ │ ├──────────────────────────────────────────────────────────┤ │ │
│ │ │ │ │ │
│ │ │ tests/ │ │ │
│ │ │ ├── 01-transactions.test.ts (15 tests) │ │ │
│ │ │ ├── 02-tokens.test.ts (12 tests) │ │ │
│ │ │ ├── 03-nft.test.ts (10 tests) │ │ │
│ │ │ ├── 04-contracts.test.ts (14 tests) │ │ │
│ │ │ ├── 05-wallet.test.ts (11 tests) │ │ │
│ │ │ ├── 06-advanced.test.ts (12 tests) │ │ │
│ │ │ └── 07-integration.test.ts (12 tests) │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ @fleet-sdk/mock-chain │ │ │
│ │ ├──────────────────────────────────────────────────────────┤ │ │
│ │ │ │ │ │
│ │ │ • MockChain - Simulates Ergo blockchain │ │ │
│ │ │ • MockUTxO - Create test boxes │ │ │
│ │ │ • MockWallet - Sign without real keys │ │ │
│ │ │ • MockState - Track chain state │ │ │
│ │ │ │ │ │
│ │ │ ❌ NO NETWORK CALLS - Everything runs locally │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Interactive Playground Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ INTERACTIVE PLAYGROUND │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ BROWSER │ │
│ ├─────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ Monaco Editor │ │ │
│ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ import { TransactionBuilder } from "@fleet-sdk/core"; │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ const tx = new TransactionBuilder(height) │ │ │ │
│ │ │ │ .from(inputs) │ │ │ │
│ │ │ │ .to(output) │ │ │ │
│ │ │ │ .build(); │ │ │ │
│ │ │ └───────────────────────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌─────────┴─────────┐ │ │
│ │ │ ▶ Run Code │ │ │
│ │ └─────────┬─────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ JavaScript Engine │ │ │
│ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ • Parse code │ │ │ │
│ │ │ │ • Execute with Fleet SDK (bundled) │ │ │ │
│ │ │ │ • Capture console.log() output │ │ │ │
│ │ │ │ • Handle errors gracefully │ │ │ │
│ │ │ └───────────────────────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ Output Panel │ │ │
│ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ > Transaction built successfully! │ │ │ │
│ │ │ │ > Outputs: 2 │ │ │ │
│ │ │ │ > Fee: 1100000 nanoERG │ │ │ │
│ │ │ └───────────────────────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘XP & Achievement System Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ XP & ACHIEVEMENT SYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ USER ACTIONS │ │
│ ├────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ Complete Tutorial ───┐ │ │
│ │ Pass Tests ──────────┼───▶ Trigger XP Award │ │
│ │ Finish Quest ────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ LEADERBOARD ENGINE │ │
│ │ (src/leaderboard.ts) │ │
│ ├────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Award XP │ │ Check │ │ Unlock │ │ │
│ │ │ │───▶│ Achievement │───▶│ Achievement │ │ │
│ │ │ +100 XP │ │ Criteria │ │ 🏆 Badge │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Calculate │ │ Update │ │ Display │ │ │
│ │ │ Rank │───▶│ Progress │───▶│ Status │ │ │
│ │ │ 🥉→🥈→🥇 │ │ 85% │ │ Terminal │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ LOCAL STORAGE │ │
│ │ (.fleet-progress.json) │ │
│ ├────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ { │ │
│ │ "username": "developer123", │ │
│ │ "xp": 850, │ │
│ │ "rank": "Apprentice Builder", │ │
│ │ "achievements": ["first_tx", "token_handler"], │ │
│ │ "completedTutorials": [1, 2, 3] │ │
│ │ } │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘CI/CD Pipeline
┌─────────────────────────────────────────────────────────────────────────────┐
│ GITHUB ACTIONS CI/CD │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ │
│ │ Git Push │ │
│ │ or PR │ │
│ └───────┬───────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ GitHub Actions Workflow │ │
│ │ (.github/workflows/ci.yml) │ │
│ ├───────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ STAGE 1: Setup │ │ │
│ │ │ ├── Checkout code │ │ │
│ │ │ ├── Setup Node.js 18/20 │ │ │
│ │ │ └── Install dependencies (npm ci) │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ STAGE 2: Quality Checks │ │ │
│ │ │ ├── TypeScript compilation (npm run build) │ │ │
│ │ │ └── Linting (npm run lint) │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ STAGE 3: Testing │ │ │
│ │ │ ├── Run all 86 tests (npm test) │ │ │
│ │ │ └── Generate coverage report │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ STAGE 4: Documentation │ │ │
│ │ │ └── Build VitePress docs (npm run docs:build) │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ ✅ PASS ❌ FAIL │ │ │
│ │ │ └── Ready to merge └── Block PR │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘File Structure Overview
fleet-sdk-tutorial/
│
├── 📁 src/ # Source code
│ ├── leaderboard.ts # XP & achievements engine
│ └── testnet-integration.ts # Ergo Explorer API client
│
├── 📁 tests/ # Test suites (86 tests)
│ ├── 01-transactions.test.ts
│ ├── 02-tokens.test.ts
│ ├── 03-nft.test.ts
│ ├── 04-contracts.test.ts
│ ├── 05-wallet.test.ts
│ ├── 06-advanced.test.ts
│ └── 07-integration.test.ts
│
├── 📁 examples/ # Working code examples
│ ├── 01-basic-transaction.ts
│ ├── 02-multi-output.ts
│ ├── 03-token-transfer.ts
│ └── ... (9 examples total)
│
├── 📁 docs/ # VitePress documentation
│ ├── 📁 .vitepress/ # VitePress config
│ │ └── config.ts
│ ├── 📁 tutorials/ # Step-by-step guides
│ ├── 📁 concepts/ # Core concepts
│ ├── 📁 examples/ # Example documentation
│ ├── 📁 guides/ # Feature guides
│ │ ├── testnet-integration.md
│ │ └── leaderboard.md
│ ├── 📁 playground/ # Interactive editor
│ │ ├── index.md
│ │ └── index.html
│ ├── 📁 testing/ # Testing guide
│ └── index.md # Homepage
│
├── 📁 .github/
│ └── 📁 workflows/
│ └── ci.yml # GitHub Actions CI/CD
│
├── package.json # Dependencies & scripts
├── tsconfig.json # TypeScript config
├── vitest.config.ts # Test config
└── README.md # Project overviewSummary
| Component | Purpose | Connection |
|---|---|---|
| VitePress Docs | User-facing documentation | Serves on localhost:5173 |
| Playground | Interactive code editor | Runs Fleet SDK in browser |
| Fleet SDK | Transaction building | Connects to Explorer API |
| Explorer API | Blockchain queries | Interfaces with Ergo nodes |
| Ergo Nodes | Blockchain network | P2P network consensus |
| MockChain | Local testing | No network (simulated) |
| Leaderboard | Progress tracking | Local JSON storage |
| GitHub Actions | CI/CD pipeline | Runs on push/PR |