Stellaroid Earn

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.

[Live Demo] [Stellar Testnet] [Soroban SDK (deployed)] [Contract CI] [Next.js] [License: MIT]

[Stellaroid Earn]

[Top 5 - Stellar Bootcamp Prize Pool]

Project Status

The bootcamp/event submission is complete and the project is parked. Maintenance keeps the existing Stellar testnet demo and evidence available; product development is not active.

• 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 a local desktop picker for xBull, Rabet, LOBSTR, Hana, Klever, and Bitget using direct wallet APIs. Bridge SDKs load on first use. WalletConnect activates when a Reown project id is configured. See the wallet integration notes.

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.

[From proof to payment: register, verify, read, fund, approve, release]

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

[Contract history on Stellar Expert]

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.tsimport 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());        // The selected wallet providerconst 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_earnmake test                     # cargo test (contract suite)make build                    # builds wasm32v1-none target
# Deploy to testnetstellar keys generate my-key --network testnet --fundstellar 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 frontendcp .env.example .env.local    # fill in contract ID + read addressnpm installnpm run dev                   # http://localhost:3000

Environment variables (.env.local):

NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.orgNEXT_PUBLIC_STELLAR_NETWORK=TESTNETNEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015NEXT_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=CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSCNEXT_PUBLIC_SOROBAN_ASSET_CODE=XLMNEXT_PUBLIC_SOROBAN_ASSET_DECIMALS=7NEXT_PUBLIC_STELLAR_EXPLORER_URL=https://stellar.expert/explorer/testnetNEXT_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 teststest test::t1_happy_path_with_approved_issuer ... oktest test::t2_unapproved_issuer_cannot_issue ... oktest test::t3_suspended_issuer_cannot_issue ... oktest test::t4_wrong_approved_issuer_cannot_verify ... oktest test::t5_revoked_credential_blocks_payment ... oktest 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

[On-chain metrics panel with indexed contract events and the live activity feed]

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.

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:

Community Contribution

[Threads Post]

Built By

Mark Siazon - Hybrid Product Designer & Full-Stack Developer

[Portfolio] [LinkedIn]
[GitHub Main]
[GitHub Professional Acct]

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.