Phase 1 MVP — 2 of 6 challenges implemented (33%) · Wave submission ready

A hands-on Soroban smart contract challenge platform. Pick a challenge, write your contract, run the tests, and level up your Stellar/Soroban skills.

PLEarn is a learn-by-doing platform for Soroban smart contract development. Each challenge gives you:

• A clear objective and requirements
• Starter code with TODO stubs to fill in
• Pre-written tests that validate your solution automatically

No guessing whether your contract is correct — the tests tell you.

The diagram below shows how the pieces fit together: the challenge folders, the test harness that validates a solution, and the feedback loop a learner goes through from picking a challenge to seeing green tests.

Diagram: PLEarn system architecture — created for Issue #2, maintained in docs/diagrams/.

For how an individual contract call behaves once it reaches the Soroban host — authorization, storage, and how unit tests simulate all of it locally — see the supplementary diagram:

Diagram: Contract lifecycle in the Soroban environment.

See docs/diagrams/README.md for the tools used and how to update these diagrams.

PLEarn-Contract/
├── challenges/
│   ├── beginner/
│   │   ├── 01-hello-token/
│   │   │   ├── INSTRUCTIONS.md   # What to build
│   │   │   ├── Cargo.toml
│   │   │   ├── src/lib.rs        # Your solution goes here
│   │   │   └── tests/test.rs     # Pre-written tests
│   │   └── 02-token-transfer/
│   │       ├── INSTRUCTIONS.md
│   │       ├── Cargo.toml
│   │       ├── src/lib.rs
│   │       └── tests/test.rs
│   ├── intermediate/
│   │   ├── 01-voting-contract/
│   │   └── 02-access-control/
│   └── advanced/
│       ├── 01-staking-contract/
│       └── 02-multisig-wallet/
├── scripts/
│   ├── run-tests.sh              # Run all challenges
│   └── validate.sh               # Validate a single challenge
└── docs/
    ├── SOROBAN_SDK_QUICK_REFERENCE.md  # SDK patterns & examples
    ├── SETUP_GUIDE.md                  # Installation & setup
    ├── contributing.md                 # How to contribute
    └── diagrams/

Goal: Get up and running in under 15 minutes!

# Install Rust stable
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Add WebAssembly target (required for Soroban)
rustup target add wasm32-unknown-unknown

rustc --version  # Should show stable version
cargo --version  # Should show matching version

git clone https://github.com/SoroGame-Plearn/PLEarn-Contract.git
cd PLEarn-Contract

# Test your setup with the first challenge
./scripts/validate.sh challenges/beginner/01-hello-token

Expected output:

🔍 Validating: challenges/beginner/01-hello-token
✅ Challenge passed!

# Test specific challenge
./scripts/validate.sh challenges/beginner/01-hello-token

# Test all challenges
./scripts/run-tests.sh

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes, then commit
git add .
git commit -m "feat: add voting contract challenge"

# Push and create PR
git push -u origin feature/your-feature-name

• feat: New features/challenges
• fix: Bug fixes
• docs: Documentation updates
• test: Test improvements

❌ "wasm32-unknown-unknown not found"

rustup target add wasm32-unknown-unknown

❌ "cargo test failed" on macOS

# Install build essentials
xcode-select --install

❌ "linker error" on Ubuntu/Debian

sudo apt update
sudo apt install build-essential pkg-config

❌ "permission denied" on Windows

• Run terminal as Administrator
• Or use WSL2 with Ubuntu

❌ Tests pass locally but fail in CI

• Ensure Rust stable version
• Check Cargo.toml has correct soroban-sdk = "22.0.11"

1. Check Soroban Setup Guide
2. Verify Rust Installation
3. Open an issue with your error output

• 📚 Soroban SDK Quick Reference - START HERE for SDK patterns used in PLEarn
• 📖 Soroban Documentation - Official docs
• 🚀 Stellar Developer Portal - Broader ecosystem
• 🎓 Soroban by Example - Code examples
• 💬 Stellar Developer Discord - Community help
• 📝 Soroban SDK Reference - API documentation
• 🛠️ Detailed Setup Guide - Step-by-step installation

• Rust (stable)
• Soroban target: rustup target add wasm32-unknown-unknown
• Soroban CLI (optional, for deployment)

Browse the challenges/ folder. Start with beginner/ if you're new to Soroban.

challenges/beginner/01-hello-token/INSTRUCTIONS.md

Each challenge has an INSTRUCTIONS.md with:

• The objective
• Required functions to implement
• Expected behavior
• Hints

Open src/lib.rs and fill in the TODO stubs:

#[contractimpl]
impl HelloToken {
    pub fn initialize(env: Env, admin: Address) {
        // your code here
    }

    pub fn mint(env: Env, to: Address, amount: i128) {
        // your code here
    }

    pub fn balance(env: Env, account: Address) -> i128 {
        // your code here
    }
}

./scripts/validate.sh challenges/beginner/01-hello-token

You'll see either:

✅ Challenge passed!

or a detailed test failure output showing exactly what went wrong.

./scripts/run-tests.sh

PLEarn is built in the open. Contributions are welcome across all skill levels. See docs/contributing.md for the full guide.

• Add a new challenge — Create a new folder under the appropriate difficulty level with INSTRUCTIONS.md, src/lib.rs, tests/test.rs, and Cargo.toml
• Write test cases — Improve coverage for existing challenges
• Fix broken tests — Find and fix tests that don't compile or have incorrect assertions
• Improve instructions — Make challenge descriptions clearer or add better hints

challenges/<difficulty>/<number>-<name>/
├── INSTRUCTIONS.md
├── Cargo.toml
├── src/
│   └── lib.rs        # starter code with TODO stubs
└── tests/
    └── test.rs       # pre-written tests

Follow the naming convention: 01-hello-token, 02-token-transfer, etc.

• INSTRUCTIONS.md has a clear objective, requirements, expected behavior, and hints
• src/lib.rs has the contract struct, #[contractimpl] block, and TODO comments
• tests/test.rs covers the happy path and at least one failure case
• Cargo.toml uses soroban-sdk = "22.0.11" with testutils feature
• ./scripts/validate.sh challenges/<path> runs without errors on a correct solution

MIT