Read-only MCP server: verify credentials and browse escrows on the Stellar testnet contract.
io.github.Iron-Mark/stellaroid-earn MCP Server
A read-only MCP server that verifies credentials and browses escrows on the Stellar testnet contract. It is designed for developers who need programmatic access to Stellar testnet escrow data and credential verification without modifying on-chain state.
🛠️ Key Features
Read-only MCP server
Verify credentials
Browse escrows on the Stellar testnet contract
🚀 Use Cases
Credential verification workflows for Stellar testnet escrow access
Inspecting escrow details from the Stellar testnet contract
⚡ Developer Benefits
Prevents state changes via read-only operation
Focused functions for credential checking and escrow browsing on the Stellar testnet
⚠️ Limitations
Read-only access (cannot perform write or transactional operations)
Verify a Stellaroid Earn credential by its SHA-256 certificate hash. Returns the on-chain status (issued/verified/revoked/suspended/expired), issuer, timestamps, and public audit links. Runs on Stellar testnet.
Look up an issuer in the Stellaroid Earn on-chain trust registry by Stellar address. Returns approval status (pending/approved/suspended), name, category, and website.
List escrowed paid trials (opportunities) on the Stellaroid Earn contract, newest first. Each ties an employer's escrowed XLM to a candidate's verified credential and moves draft -> funded -> submitted -> released/refunded.
Decoded recent contract events (credential registrations/verifications, escrow lifecycle, payments) from the Stellaroid Earn contract, deduplicated across Soroban RPC and the Stellar Expert indexer.
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.
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
Landing page Discover - Landing page with 3-step how-it-works flow
Verified proof block Verify - On-chain credential with green Verified badge
App dashboard Issue & Pay - Dual-role dashboard for issuers and employers
Mobile proof card Share - QR-scannable proof card on any mobile browser
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.
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.
ts
// frontend/src/lib/contract-client.tsimporttype * asStellarSdkfrom"@stellar/stellar-sdk";
// Lazy-load the SDK once, on the first contract read or wallet action.constgetSdk = () => 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_IDfunction: method, // e.g. "verify_certificate"
args, // sdk.nativeToScVal(...) per argument
}),
)
.setTimeout(30)
.build();
const signedXdr = await wallet.sign(tx.toXDR()); // Freighter / Albedo / Stellar Wallets Kitconst 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:
Contract function (contracts/stellaroid_earn/src/lib.rs)
Frontend wrapper (contract-client.ts)
register_issuer
registerIssuer()
approve_issuer
approveIssuer()
suspend_issuer
suspendIssuer()
get_issuer
getIssuer() (read / simulateTransaction)
register_certificate
registerCertificate()
verify_certificate
verifyCertificate()
get_certificate
getCertificate() (read / simulateTransaction)
revoke_certificate
revokeCertificate()
suspend_certificate
suspendCertificate()
reward_student
rewardStudent()
link_payment
linkPayment()
create_opportunity
createOpportunity()
fund_opportunity
fundOpportunity()
submit_milestone
submitMilestone()
approve_milestone
approveMilestone()
release_payment
releasePayment()
refund_opportunity
refundOpportunity()
get_opportunity
getOpportunity() (read / simulateTransaction)
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.
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
bash
cd frontend
cp .env.example .env.local # fill in contract ID + read address
npm install
npm run dev # http://localhost:3000
Open a paid-trial escrow against a verified credential
fund_opportunity(employer, opp_id)
Employer
Escrow the full trial amount into the contract
submit_milestone(candidate, opp_id)
Candidate
Mark the next milestone as delivered
approve_milestone(employer, opp_id)
Employer
Approve the submitted milestone
release_payment(employer, opp_id)
Employer
Release the approved milestone share to the candidate
refund_opportunity(employer, opp_id)
Employer
Return remaining escrowed funds to the employer
get_opportunity(opp_id)
Anyone
Read a paid-trial opportunity record
Credential Status Lifecycle
code
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:
code
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
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:
A trusted server obtains a user-signed transaction for an allowed Stellaroid Earn method
The trusted server calls /api/fee-bump with Authorization: Bearer <FEE_SPONSOR_TOKEN>
The route enforces XDR size, signature, operation count, network, contract ID, method allow-list, and fee-ceiling checks
Only then does the sponsor key wrap the transaction as a fee bump
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.
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.
