Hackathon Stellaroid Earn MCP Server

Stellaroid Earn

On-chain credential trust for Stellar PH Bootcamp 2026

Issue, verify, and pay graduates on Stellar testnet: Soroban smart contract, 8 supported wallets (Freighter, Albedo, xBull, LOBSTR & more), installable PWA, end-to-end.

---

Project Status

The bootcamp/event submission is complete. Stellaroid Earn is now maintained as a living Stellar credential proof project.

• Roadmap: ROADMAP.md
• Maintenance checks: MAINTENANCE.md
• Docs index: docs/README.md
• Release and deployment: docs/operations/release-and-deployment.md
• Pro-research intake: docs/planning/research-intake-status.md
• Demo checklist: docs/operations/demo-checklist.md
• Canonical live URL: stellaroid.tech
• Operational status route: /status
• Pilot intake route: /pilot

www.stellaroid.tech and earn.stellaroid.tech redirect to the canonical apex URL.

Version archive

Each monthly build cycle is preserved as a frozen snapshot at a pinned subdomain, independent of the live site:

stellaroid.tech always serves the latest production build (main). The April source lives on the april-bootcamp-and-monthly-builder branch; June and July on june-monthly-builder and july-monthly-builder.

July v3.2 product surface

• Wallet-less guided demo - /demo: the full register → verify → escrow → payout story on real seeded testnet data (a released 25 XLM escrow and a live funded one), with per-step stellar.expert audit links. No wallet, no extension, works on a phone.
• Opportunity directory - /opportunity: every live escrowed paid trial on the contract, with wallet-scoped filters (for you / created by you) and deep links into the milestone console.
• Live escrow evidence - the status page and activity feeds now decode all escrow events (create/fund/submit/approve/release/refund) alongside credential events, deduplicated across the RPC and the Stellar Expert indexer; /app shows the events involving your connected wallet.
• On-site pilot intake - /pilot has a real lead-capture form (rate-limited, honeypot-guarded, delivered by email) instead of a link-out, plus /contact, an honest privacy & terms page, and an RFC 9116 security.txt.
• Performance pass - the multi-megabyte stellar-sdk is lazy-loaded out of every route's First Load JS (/app dropped 483 → ~260 KB gzipped), the brand typefaces (Orbitron/Exo 2) are self-hosted via next/font, and first-party client-error telemetry reports runtime failures to server logs with no third-party service.
• Installable PWA - manifest with maskable icons, service worker (network-first pages, offline fallback, per-deploy cache versioning; verification pages are never served from cache), iOS splash screens. Add it to a phone home screen from the live site.
• Mobile-first redesign - app-style bottom navigation with a More sheet, auto-hiding header, bottom-sheet dialogs, full safe-area/notch handling.
• Developer docs hub - /docs: contract reference (all 19 functions, 17 error codes, 16 events), integration, architecture, and security posture.
• Content engine - audience landing pages for bootcamps, employers, and graduate payouts, plus a guides library and a verifiable-credentials glossary - all with FAQPage/HowTo/DefinedTermSet structured data and an llms.txt.
• Multi-wallet signing - Freighter and Albedo natively, plus xBull, Rabet, LOBSTR, Hana, Klever, and Bitget via Stellar Wallets Kit - all behind one provider interface, lazy-loaded on first use.

The public entry flow is organized around three personas: Issue, Verify, and Hire. Verified proof pages now hand employers into /employer with the proof hash and candidate wallet preloaded, then require a review checklist before escrow creation. They also hand recruiters into /talent/<address>?proof=<hash> so the candidate passport can show a known proof without pretending wallet-wide credential discovery exists yet. Issuer registration now explains approval readiness before signing, and /pilot keeps the first rollout bounded to a small testnet issuer pilot. Employer proof packs include a recruiter-safe summary plus an unsigned standards-alignment preview for W3C VC 2.0 and Open Badges 3.0 mapping. That preview is not a signed standards credential yet.

---

30-Second Pitch

Problem: Bootcamp certificates are PDFs that anyone can fake and no one can independently verify. Employers skip verification or pay for a background check service.

Solution: Stellaroid Earn anchors credential hashes on a Soroban smart contract where approved issuers register and verify certificates, anyone checks proof at a public URL with no login, and employers pay graduates in XLM on Stellar testnet, all on-chain.

Why Stellar: Sub-cent fees and 5-second finality make issuing credentials cheap enough that skipping it makes no sense. simulateTransaction lets anyone verify with zero wallet setup. Native XLM via SAC closes the loop from proof to payout on one chain.

---

Feature Gallery

---

Live Trust Artifact

Every credential produces a public Verified Badge URL - no wallet, no login, no API key. Green means verified on-chain. Amber means issued but not yet verified.

Contract on Stellar Expert: CAD6C24P…ISZCV

---

Architecture

Full architecture document: docs/reference/architecture.md

sequenceDiagram
  autonumber
  actor Issuer as Approved Issuer
  actor Student
  actor Employer
  participant FE as Stellaroid Earn (Next.js)
  participant FR as Freighter
  participant SC as Soroban contract<br/>(stellaroid_earn)
  participant XLM as Stellar testnet

  Issuer->>FE: Open /app, paste student wallet + cert hash
  FE->>FR: requestAccess + signTransaction(register_certificate)
  FR->>XLM: Submit tx
  XLM->>SC: register_certificate(issuer, student, hash, title, cohort, uri)
  SC-->>XLM: cert_reg event
  Issuer->>FE: Click "Approve credential"
  FE->>FR: signTransaction(verify_certificate)
  FR->>XLM: Submit tx
  XLM->>SC: verify_certificate(verifier, hash)
  SC-->>XLM: cert_ver event
  Student->>FE: Share /proof/<hash> (QR or link)
  Note over FE,SC: Read-only get_certificate via simulateTransaction
  Employer->>FE: Open /app as Employer, paste hash + amount
  FE->>FR: signTransaction(link_payment)
  FR->>XLM: Submit tx (XLM transfer + payment event)

Design decisions:

• soroban-sdk 26.1 with typed #[contracterror] enum (17 variants), persistent + instance storage, TTL 518k/1.04M ledgers
• Issuer trust layer: self-register → admin approve → issue credentials. Suspended issuers are blocked on-chain
• Two read paths: server-side RSC with revalidate=60 (CDN-cached proof pages) + client-side simulateTransaction (dashboard state)
• One write path: Freighter signs → sendTransaction → poll for result
• CSP locks connect-src to *.stellar.org - no third-party data leaks

---

Quick Start

Prerequisites

• Rust (stable) + wasm32v1-none target
• Stellar CLI v26+
• Node.js 20+ and npm
• Freighter browser extension set to Testnet

Full setup guide: docs/reference/pre-workshop-setup-guide.pdf

Smart Contract

cd contract
cargo test                    # contract test suite
stellar contract build        # builds wasm32v1-none target

# Deploy to testnet
stellar keys generate my-key --network testnet --fund
stellar contract deploy \
  --wasm target/wasm32v1-none/release/stellaroid_earn.wasm \
  --source my-key --network testnet

CI runs the contract gate with cargo test -p stellaroid_earn --locked and cargo build -p stellaroid_earn --target wasm32v1-none --release --locked in Contract CI.

Frontend

cd frontend
cp .env.example .env.local    # fill in contract ID + read address
npm install
npm run dev                   # http://localhost:3000

Environment variables (.env.local):

NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_STELLAR_NETWORK=TESTNET
NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
NEXT_PUBLIC_SOROBAN_CONTRACT_ID=<your deployed contract ID>
NEXT_PUBLIC_STELLAR_ADMIN_ADDRESS=<your admin G... address>
NEXT_PUBLIC_STELLAR_READ_ADDRESS=<any funded testnet address for read-only calls>
NEXT_PUBLIC_SOROBAN_ASSET_ADDRESS=CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC
NEXT_PUBLIC_SOROBAN_ASSET_CODE=XLM
NEXT_PUBLIC_SOROBAN_ASSET_DECIMALS=7
NEXT_PUBLIC_STELLAR_EXPLORER_URL=https://stellar.expert/explorer/testnet
NEXT_PUBLIC_CANONICAL_URL=https://stellaroid.tech

---

Verifiable On-Chain

Every action in the demo flow is a real transaction on Stellar testnet. Click any hash to verify on Stellar Expert.

Live certificates (testnet, contract CAD6C24P…):

Contract Functions

Credential Status Lifecycle

Issued --> Verified  (issuer or admin calls verify_certificate)
       --> Revoked   (issuer or admin calls revoke_certificate)
       --> Suspended (issuer or admin calls suspend_certificate)
       --> Expired   (reserved status; new credentials currently use expires_at = 0 unless a future issuer flow sets expiry)

---

Tests

Contract tests cover the trust layer, access control, revocation, opportunity escrow, milestone caps, and events:

running 12 tests
test test::t1_happy_path_with_approved_issuer ... ok
test test::t2_unapproved_issuer_cannot_issue ... ok
test test::t3_suspended_issuer_cannot_issue ... ok
test test::t4_wrong_approved_issuer_cannot_verify ... ok
test test::t5_revoked_credential_blocks_payment ... ok
test test::t6_issuer_events_emit ... ok

test result: ok. 12 passed; 0 failed; 0 ignored

---

Security

Full security checklist: docs/reference/security.md

Covers: smart contract access control, frontend CSP/HSTS/X-Frame-Options, strict input validation, JSON-LD escaping, URL sanitization, proof-claim integrity, fee-sponsor restrictions, error normalization, SSRF prevention, and operational security.

---

Advanced Feature: Fee Sponsorship (Gasless Transactions)

Stellaroid Earn keeps fee bump transaction support (CAP-0015) behind a server-to-server authorization boundary. Public browser clients do not automatically send signed XDR to /api/fee-bump.

How it works:

1. A trusted server obtains a user-signed transaction for an allowed Stellaroid Earn method
2. The trusted server calls /api/fee-bump with Authorization: Bearer <FEE_SPONSOR_TOKEN>
3. The route enforces XDR size, signature, operation count, network, contract ID, method allow-list, and fee-ceiling checks
4. Only then does the sponsor key wrap the transaction as a fee bump

Implementation:

• Server route: frontend/src/app/api/fee-bump/route.ts
• Client helper: frontend/src/lib/fee-bump.ts
• Config: FEE_SPONSOR_SECRET + FEE_SPONSOR_TOKEN are server-only. Public browser auto-sponsorship stays disabled; trusted server callers must provide the bearer token explicitly.
• Browser fallback: normal user-paid Freighter transactions remain the default path.

---

Metrics & Monitoring

• Status metrics: /status#metrics - public contract-event evidence, proof hashes, reward/payment events, and source labels on the operational status page
• Health endpoint: /api/health - cached JSON health check (config, RPC latency, contract availability)
• Events API: /api/events - structured contract event data for external consumers
• Events stream: /api/events/stream - short-lived Server-Sent Events stream for live demo refreshes without adding a database
• MCP server: /api/mcp - read-only remote Model Context Protocol endpoint (Streamable HTTP, no auth) so AI agents can verify credentials, inspect issuers, and browse escrowed paid trials; built on Vercel's mcp-handler + the official MCP TypeScript SDK
• Vercel Analytics: Page analytics plus privacy-safe custom events for proof sharing, proof-pack downloads, employer handoff, shortlist saves, and escrow-start actions

Data Indexing

Contract events are read from two public sources. The app first queries Soroban RPC getEvents for recent contract events, then supplements that result with Stellar Expert's public contract event index so older testnet activity does not disappear from the demo surface when the RPC retention window moves on. Events are decoded from ScVal/XDR where possible, categorized by kind (cert_reg, cert_ver, reward, payment), deduplicated, source-labelled, and served through /api/events, /api/events/stream, plus /status#metrics.

This remains a lightweight serverless evidence layer, not a full analytics warehouse. Vercel page analytics and custom events help inspect proof/share/employer flow interest without storing raw wallet addresses or proof hashes; durable proof history, issuer conversion, and long-term product analytics still require a first-party read model.

---

Tech Stack

---

Project Structure

stellaroid-earn/
├── Cargo.toml                   # Rust workspace (Soroban contract)
├── contract/
│   ├── src/
│   │   ├── lib.rs              # Soroban credential + payment contract
│   │   └── test.rs             # contract security and lifecycle tests
│   └── Cargo.toml
├── frontend/
│   ├── src/
│   │   ├── app/                # Next.js App Router pages
│   │   │   ├── app/            # Participant dashboard (issuer + employer)
│   │   │   ├── issuer/         # Issuer registration + lookup
│   │   │   └── proof/[hash]/   # Public shareable verified badge
│   │   ├── components/         # UI components (proof card, wallet, badges)
│   │   ├── hooks/              # Freighter wallet state
│   │   └── lib/                # Contract client, RPC helpers, types
│   └── .env.example
├── docs/                       # Product docs, setup references, operations, and archives
├── demo/                       # Demo script, FAQ, press kit
├── images/                     # README screenshots
├── scripts/                    # Screenshot capture and operations scripts
├── LICENSE
└── README.md

---

Demo Video

demo/stellaroid-earn-demo.mp4

Full walkthrough: landing page → about → app dashboard (wallet connect) → issuer console → verified proof page → on-chain evidence on Stellar Expert.

The demo video is committed in this repository so the submission does not depend on an expiring external upload URL.

Demo Day slides: /slides (integrated into the app, arrow keys to navigate)

Submission/demo checklist: docs/operations/demo-checklist.md

Submission evidence map: docs/operations/submission-evidence.md

---

User Validation

Testnet Wallet Evidence

30 real participant wallet addresses from the Stellar testnet review are listed for public review. Each wallet address is verifiable on Stellar Expert. Some wallets have direct contract interactions such as register_issuer; others are funded participant wallets used during the review flow. The committed feedback snapshot keeps participant names and emails redacted.

Feedback Collection

• Google Form: Stellaroid Earn - User Feedback Form
• Anonymized response snapshot: docs/planning/user-feedback-responses.csv
• Full feedback documentation: docs/planning/user-feedback.md

Improvements Based on Feedback

After reviewing the anonymized pilot feedback snapshot, the following iteration was completed:

---

Community Contribution

---

Built By

Mark Siazon - Hybrid Product Designer & Full-Stack Developer

Acknowledgments

• Rise In - Stellar Smart Contract Bootcamp
• Stellar Philippines - Stellar PH Bootcamp 2026
• Workflow PH - Community partner
• Stellar Docs · Soroban SDK · Freighter · Stellar Expert

---

MIT License - see LICENSE for details.