Stellar Scavenger

Soroban-powered on-chain quests, rewards, and community engagement on Stellar.

Stellar Scavenger is an open-source platform for creating wallet-based quests on the Stellar network. Projects can define tasks such as making a donation, interacting with a contract, sending a transaction, or completing an onboarding flow, then verify completion and distribute rewards transparently.

It is designed for hackathons, DAOs, community campaigns, grants programs, onboarding experiences, and ecosystem growth initiatives.

Repo Description

A Soroban-powered quest and reward platform for creating on-chain challenges, verifying wallet activity, and distributing community rewards on Stellar.

Core Features

• Create and manage quests
• Verify wallet-based quest completion
• Distribute rewards after verification
• Track participation and leaderboard rankings
• Expose API endpoints for apps and dashboards
• Support future integrations for badges, NFTs, and campaign analytics

Repository Structure

stellar-scavenger/
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── .gitignore
├── .env.example
├── docs/
│   ├── architecture.md
│   ├── api-spec.md
│   ├── endpoints.md
│   └── roadmap.md
├── contracts/
│   ├── quest-contract/
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   ├── reward-contract/
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   └── leaderboard-contract/
│       ├── Cargo.toml
│       └── src/lib.rs
├── api/
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   │   ├── index.ts
│   │   ├── health/
│   │   │   └── health.controller.ts
│   │   ├── quests/
│   │   │   ├── quests.controller.ts
│   │   │   └── quests.service.ts
│   │   ├── rewards/
│   │   │   ├── rewards.controller.ts
│   │   │   └── rewards.service.ts
│   │   ├── users/
│   │   │   └── users.controller.ts
│   │   └── verification/
│   │       └── verification.controller.ts
│   └── tests/
│       └── smoke.test.ts
├── web/
│   ├── package.json
│   ├── tsconfig.json
│   ├── app/
│   │   ├── page.tsx
│   │   ├── quests/page.tsx
│   │   ├── leaderboard/page.tsx
│   │   ├── wallet/page.tsx
│   │   └── rewards/page.tsx
│   └── components/
│       └── header.tsx
└── .github/
    ├── ISSUE_TEMPLATE/
    │   ├── bug_report.md
    │   ├── feature_request.md
    │   └── good_first_issue.md
    └── workflows/
        └── ci.yml

Suggested API Endpoints

Health

• GET /health

Quests

• POST /api/v1/quests
• GET /api/v1/quests
• GET /api/v1/quests/:questId
• PATCH /api/v1/quests/:questId
• POST /api/v1/quests/:questId/join
• POST /api/v1/quests/:questId/verify
• POST /api/v1/quests/:questId/complete

Rewards

• GET /api/v1/rewards
• POST /api/v1/rewards/claim
• GET /api/v1/rewards/:rewardId

Users

• GET /api/v1/users/:walletAddress
• GET /api/v1/users/:walletAddress/quests
• GET /api/v1/users/:walletAddress/rewards
• GET /api/v1/users/:walletAddress/leaderboard

Leaderboard / Analytics

• GET /api/v1/leaderboard
• GET /api/v1/analytics/quests
• GET /api/v1/analytics/rewards

MVP Flow

1. Admin creates a quest.
2. User connects a Stellar wallet.
3. User joins the quest.
4. App verifies required wallet activity.
5. Reward is marked claimable.
6. User claims reward.
7. Leaderboard and analytics update.

Local Development

API

cd api
npm install
npm run dev

Web

cd web
npm install
npm run dev

Contracts

Compile with Soroban tooling after adding your workspace configuration.

First Commit Recommendation

git init
git add .
git commit -m "feat: bootstrap stellar-scavenger repository"

Contributing

See CONTRIBUTING.md.

License

MIT