Skip to content

Latest commit

 

History

History
368 lines (282 loc) · 10.5 KB

README.md

File metadata and controls

368 lines (282 loc) · 10.5 KB

StellarEarn

A quest-based earning platform that turns work into achievements on the Stellar blockchain

Overview

StellarEarn is a quest-based earning platform where teams define tasks ("quests"), contributors complete them, and rewards are distributed on-chain via Stellar smart contracts (Soroban). Users level up by completing quests, building an on-chain reputation trail and unlocking higher-value opportunities.

What It Does

  • Create & manage quests with criteria, rewards, deadlines, and proof requirements
  • Complete & verify quests with off-chain signals (API, GitHub webhooks, form attestations) and on-chain validation
  • Distribute rewards programmatically to contributors via Stellar assets
  • Track reputation and progress with XP and badges captured through contract state

Goals

  • Provide a trust-minimized, low-fee, and fast-settlement reward system
  • Align incentives for open-source projects, DAOs, and distributed teams
  • Leverage Stellar's strengths in payments, asset issuance, and on/off-ramps

Why Stellar?

Payments-first chain: Stellar was designed for fast, low-cost asset transfers and global remittances, making it ideal for frequent micro-reward payouts.

Asset issuance & compliance-friendly design: Projects can issue reward tokens or use existing assets with built-in trustlines and anchors to access real-world on/off-ramps.

Soroban smart contracts: Modern, Rust-based contracts bring programmability to Stellar, enabling verifiable task completion, escrow, and conditional payouts with deterministic execution and safety-focused tooling.

Learn more: Stellar Developers | Soroban Documentation

Who Is It For?

  • Open-source communities & maintainers who want to reward contributors transparently
  • DAOs & Web3 communities running bounty boards or seasonal quests
  • Startups & product teams incentivizing internal milestones or growth tasks
  • Education & talent platforms that issue credentials and micro-grants for verifiable learning

Key Features

  • 🧭 Quest management - Create, assign, and track task progress
  • 🧩 Flexible verification - Off-chain attestations, API checks, or multi-sig approvals
  • 💸 On-chain payouts - Automatic rewards via Stellar assets (stablecoins or project tokens)
  • 🛡️ Escrow & conditions - Release rewards only when criteria are met
  • ⭐ Reputation & levels - XP, badges, and a provable on-chain record
  • 🌐 Multi-network support - Local sandbox, testnet, or mainnet-ready configs

Architecture

┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│  Frontend       │      │   Backend        │      │  Stellar/       │
│  Next.js        │◄────►│   NestJS         │◄────►│  Soroban        │
│                 │      │                  │      │                 │
│ • User Dashboard│      │ • REST/GraphQL   │      │ • Quest Contract│
│ • Quest Browser │      │ • Auth & RBAC    │      │ • Reputation    │
│ • Submissions   │      │ • Quest Service  │      │ • Asset/Reward  │
│ • Wallet Connect│      │ • Payout Logic   │      │                 │
└─────────────────┘      │ • Webhooks       │      └─────────────────┘
                         │ • DB (Postgres)  │
                         └──────────────────┘

High-Level Flow

  1. Admin creates a quest (API persists off-chain metadata; contract registers reward logic)
  2. Contributor submits proof; API verifies (webhooks/API checks) and calls the contract
  3. Contract releases/stores state; payouts executed in Stellar assets
  4. UI reflects on-chain state + off-chain metadata; users level up

Repository Structure

EarnQuestOnestellar_Earn/
├── apps/
│   ├── web/                    # Next.js frontend (App Router)
│   │   ├── app/                # routes
│   │   ├── components/
│   │   ├── lib/                # wallet utils, API client
│   │   ├── public/
│   │   └── tests/
│   └── api/                    # NestJS backend
│       ├── src/
│       │   ├── main.ts
│       │   ├── app.module.ts
│       │   └── modules/
│       │       ├── quests/
│       │       ├── users/
│       │       ├── payouts/
│       │       └── webhooks/
│       ├── prisma/
│       └── test/
├── contracts/
│   └── earn-quest/             # Soroban/Rust contract
│       ├── src/
│       │   └── lib.rs
│       ├── Cargo.toml
│       └── tests/
├── infra/
│   ├── docker-compose.yml
│   └── migrations/
├── scripts/
├── .env.example
├── package.json
├── README.md
└── LICENSE

Getting Started

Prerequisites

  • Node.js ≥ 18.x and npm or pnpm
  • Rust & Cargo (stable)
  • Soroban CLI (for building/deploying contracts)
  • Docker (optional; for Postgres and local services)
  • Git

Install Rust:

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

Soroban CLI & Stellar tooling: See official docs

Installation

# Clone the repository
git clone https://github.com/<your-org>/EarnQuestOnestellar_Earn.git
cd EarnQuestOnestellar_Earn

# Install dependencies
cd apps/web && pnpm install
cd ../api && pnpm install
cd ../../

# Build contract
cd contracts/earn-quest && cargo build
cd ../../

Environment Variables

Create .env files based on .env.example:

Root .env:

# Network
STELLAR_NETWORK=testnet
SOROBAN_RPC_URL=https://<testnet-rpc>
CONTRACT_ID=<set-after-deployment>

# Wallet/Signing
SOROBAN_SECRET_KEY=<server-key>
ISSUER_PUBLIC_KEY=<reward-asset-issuer>

# Database
DATABASE_URL=postgres://user:pass@localhost:5432/earnquest

Frontend (apps/web/.env.local):

NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_SOROBAN_RPC_URL=
NEXT_PUBLIC_CONTRACT_ID=
API_BASE_URL=http://localhost:3001

Backend (apps/api/.env):

PORT=3001
DATABASE_URL=postgres://user:pass@localhost:5432/earnquest
STELLAR_NETWORK=testnet
SOROBAN_RPC_URL=
CONTRACT_ID=
SOROBAN_SECRET_KEY=
JWT_SECRET=your_jwt_secret

Running Locally

1. Start Postgres:

docker compose -f infra/docker-compose.yml up -d

2. Run database migrations:

cd apps/api
pnpm prisma migrate dev

3. Start backend:

cd apps/api
pnpm start:dev

4. Start frontend:

cd apps/web
pnpm dev
# Access at http://localhost:3000

Smart Contract Development

Contract Structure

The Soroban smart contract includes these conceptual modules:

  • QuestRegistry - Create/update quests (reward asset, amount, verifier)
  • Submission - Submit proof; store status; emit event
  • Verifier - Check conditions (role-based, multi-sig, or data-driven)
  • Payout - Transfer asset to recipient upon approval
  • Reputation - Track XP/badges per address

Key Contract Functions

register_task(id, reward_asset, amount, verifier)
submit_proof(id, proof_ref)
approve(id, address, amount)
claim_reward(id)
get_user_stats(address)
get_task(id)

Build & Test

cd contracts/earn-quest

# Build
cargo build --release

# Run tests
cargo test

Deploy to Testnet

export STELLAR_NETWORK=testnet
export SOROBAN_RPC_URL=<your-testnet-rpc>

soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/earn_quest.wasm \
  --network $STELLAR_NETWORK \
  --secret-key $SOROBAN_SECRET_KEY \
  --rpc-url $SOROBAN_RPC_URL

# Save the CONTRACT_ID output to your .env files

Invoke Contract

# Register a quest
soroban contract invoke \
  --id $CONTRACT_ID \
  --fn register_task \
  --arg id=Q-001 --arg reward_asset=... --arg amount=100

# Get user stats
soroban contract invoke \
  --id $CONTRACT_ID \
  --fn get_user_stats \
  --arg address=<stellar-address>

Testing

Frontend:

cd apps/web
pnpm test
pnpm test:watch
pnpm lint
pnpm typecheck

Backend:

cd apps/api
pnpm test
pnpm test:e2e
pnpm lint

Contracts:

cd contracts/earn-quest
cargo test

Networks & Configuration

  • Local - Fastest iteration; use sandbox RPC and fake keys
  • Testnet - Public test environment; faucet for test funds
  • Mainnet - Real assets and fees; ensure audits and monitoring

Switching Networks

Update STELLAR_NETWORK and SOROBAN_RPC_URL in:

  • Contract deployment scripts
  • Backend .env
  • Frontend .env.local

Important: Ensure reward assets exist and users have trustlines set before payouts.

API Endpoints

Quests

  • POST /quests - Create quest
  • GET /quests - List quests
  • POST /quests/:id/submit - Submit proof
  • POST /quests/:id/approve - Approve submission

Payouts

  • POST /payouts/claim - Claim rewards

Users

  • GET /users/:address/stats - Get reputation & earnings

Contributing

We welcome contributions! Here's how to get started:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Set up your environment using the installation steps
  4. Write tests and ensure they pass
  5. Lint and typecheck your code
  6. Open a pull request with a clear description

Commit Convention

Use Conventional Commits:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • chore: - Maintenance tasks
  • refactor: - Code refactoring
  • test: - Test updates

Security

  • Do not include secrets in pull requests
  • Report vulnerabilities privately (contact TBD)

FIGMAlink

Resources

License

MIT (or specify your chosen license)

Questions or feedback? Open an issue or reach out to the maintainers.