Hackathon Stellaroid Earn MCP Server

Stellaroid Earn

A reusable prove, verify, pay primitive for on-chain credentials, built for Stellar PH Bootcamp 2026

Issue, verify, and pay graduates on Stellar testnet: Soroban smart contract, 8 supported wallets plus WalletConnect for mobile (Freighter, Albedo, LOBSTR, xBull & 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
• Case study (how it was built and verified): /case-study
• Handoff (repo state, invariants, what remains): HANDOFF.md
• Campaign and launch graphics: assets/campaign/, including the 2-minute promotional walkthrough stellaroid-promotional-demo.mp4

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, July, and August on june-monthly-builder, july-monthly-builder, and august-monthly-builder. July is a read-only archive. August is the live monthly-builder branch, and v4.stellaroid.tech serves its Vercel deployment.

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 (live tag v3.0.0: 19 functions, 17 error codes; source adds refresh/expiry writes), 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, WalletConnect for mobile wallets (LOBSTR, xBull, Hana, Freighter mobile), and on desktop xBull, Rabet, LOBSTR, Hana, Klever, and Bitget via Stellar Wallets Kit - all behind one provider interface, lazy-loaded on first use. WalletConnect activates when a Reown project id is configured.

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 and the WalletConnect relay - no other third-party origins

---

Contract Integration (Frontend to Soroban)

The frontend talks to the deployed stellaroid_earn contract with @stellar/stellar-sdk. The client lives in frontend/src/lib/contract-client.ts (writes + client-side reads) and frontend/src/lib/contract-read-server.ts (server-rendered proof pages). The SDK is lazy-loaded so its multi-megabyte bundle stays out of every route's first load.

// frontend/src/lib/contract-client.ts
import type * as StellarSdk from "@stellar/stellar-sdk";

// Lazy-load the SDK once, on the first contract read or wallet action.
const getSdk = () => import("@stellar/stellar-sdk");

// READ (no wallet): simulate an invocation against Soroban RPC.
const server = new sdk.rpc.Server(appConfig.rpcUrl);
const sim = await server.simulateTransaction(tx);
const value = sdk.scValToNative(sim.result.retval);

// WRITE: build with TransactionBuilder, wallet signs, submit + poll.
const tx = new sdk.TransactionBuilder(account, {
  fee: sdk.BASE_FEE,
  networkPassphrase: getExpectedNetworkPassphrase(),
})
  .addOperation(
    sdk.Operation.invokeContractFunction({
      contract: appConfig.contractId,   // NEXT_PUBLIC_SOROBAN_CONTRACT_ID
      function: method,                  // e.g. "verify_certificate"
      args,                              // sdk.nativeToScVal(...) per argument
    }),
  )
  .setTimeout(30)
  .build();

const signedXdr = await wallet.sign(tx.toXdr());        // Freighter / Albedo / Stellar Wallets Kit
const sent = await server.sendTransaction(sdk.TransactionBuilder.fromXdr(signedXdr, passphrase));
const result = await server.pollTransaction(sent.hash);

Every public contract function has a matching typed wrapper in the client. The wrapper passes the exact contract function name to Operation.invokeContractFunction:

The network passphrase in NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE must match the network the contract is deployed on (testnet), or the wallet rejects the signature.

---

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 contracts/stellaroid_earn
make test                     # cargo test (contract suite)
make 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…):

Live testnet contract CAD6C24P… is tag v3.0.0 (19 functions). The three refresh and expiry writes exist in this source tree and stay unused against that WASM until a new deploy.

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   (past a nonzero expires_at window; renew_certificate restores Issued or Verified)

---

Tests

Contract tests cover the trust layer, access control, revocation, opportunity escrow, milestone caps, issuer refresh dates, credential expiry, and events:

running 15 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. 15 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
• Request policy: frontend/src/lib/fee-bump-policy.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)
├── contracts/
│   └── stellaroid_earn/
│       ├── src/
│       │   ├── lib.rs          # Soroban credential + payment contract
│       │   └── test.rs         # contract security and lifecycle tests
│       ├── Makefile            # build / test / fmt / clean targets
│       └── 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

Campaign cut (2026-08): assets/campaign/stellaroid-promotional-demo.mp4

Two-minute live-site walkthrough of stellaroid.tech with voice-over: landing, wallet-less /demo tour, verified proof, employer handoff, and the opportunity directory. Stellar testnet, no real funds.

Submission cut: 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.

Both videos are committed in this repository so the links do 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

62 of 50 Testnet Wallet Accounts

Stellaroid Earn has 62 of the targeted 50 documented testnet wallet accounts with public network activity. That total is two groups: 30 independent participant wallets from the testnet review, plus 32 controlled QA accounts that I operate myself for structured product verification (24 from the July guided cohort, plus 8 from the August QA wave). Both groups are listed in full below and every wallet and transaction links to Stellar Expert.

The 32 QA accounts are disclosed as QA personas, not as independent people. So the figure above is wallet-account coverage with real network activity. It is not a claim of 62 separate users, and the independent participant count remains 30. A prior snapshot of this figure was 54 (30 independent plus 24 QA).

Testnet Wallet Evidence

30 independent 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.

The 32 QA account addresses that complete the 62-account total are listed separately in the guided QA evidence log (24 July accounts) and the August 2026 QA wave log (8 additional accounts I operate), so each group stays checkable on its own.

Guided Testnet QA Coverage

Alongside the independent participant review, 24 controlled QA accounts I operate completed eight structured issuer, graduate, and employer journeys on the public testnet contract. The run produced 64 QA-account-signed transactions plus eight facilitator approvals, including eight verified credentials and eight released 1 testnet XLM paid opportunities (no monetary value).

The guided QA evidence log links every July public account and transaction. In August 2026 I added 8 more QA accounts I operate, logged in guided-qa-wave-2026-08.md. Those 8 are not independent participants. Combined QA coverage is 32 accounts I operate. The organization, credential, cohort, and opportunity names are fictional scenario data. All 32 QA accounts are included in the 62-account testnet coverage total and identified by their QA purpose in the evidence logs.

Feedback Collection

• Google Form: Stellaroid Earn - User Feedback Form
• Response export (Excel): docs/planning/user-feedback-responses.xlsx (plain-text CSV also committed: user-feedback-responses.csv)
• Full feedback documentation: docs/planning/user-feedback.md

Improvements Based on Feedback

Every improvement below maps to a piece of pilot feedback and the commit that shipped it:

Documentation truncated — see the full README on GitHub.