Stellaroid Earn documentation
Developer documentation for Stellaroid Earn, an early-access pilot on Stellar testnet that anchors credential hashes on a Soroban smart contract and pays verified graduates in XLM. Start with the quickstart below, then use the map to reach the contract, integration, architecture, and security pages.
Stellaroid Earn treats a credential as an on-chain record. A school or bootcamp anchors a certificate's SHA-256 hash to a student's Stellar wallet through a Soroban smart contract, an approved issuer verifies it, and an employer pays the graduate in XLM in the same flow. Verification is public and read-only: anyone can open a proof page and confirm a credential without a wallet, login, or API key.
For developers, the system is deliberately small. The contract is Rust + soroban-sdk, deployed to Stellar testnet, with a 19-function public surface — a credential core plus a milestone-escrow extension — and typed contract errors. The frontend is Next.js 15 + React 19 using @stellar/stellar-sdk: read-only calls go through simulateTransaction, and writes are signed with Freighter or Albedo and submitted over Soroban RPC. Every state change emits a contract event that is auditable on Stellar Expert.
This docs hub is written for developers, technical issuers, and security reviewers. The first rollout is intentionally bounded to a small testnet issuer pilot; issuer intake happens at /pilot on the live site.
The core flow
The happy path is three contract calls. Each one is a real transaction on Stellar testnet and each emits an on-chain event.
| Function | Caller | Effect |
|---|---|---|
| register_certificate(issuer, student, cert_hash, title, cohort, metadata_uri) | Approved issuer | Binds the certificate's SHA-256 hash to the student's wallet; duplicate hashes are rejected on-chain; emits cert_reg |
| verify_certificate(verifier, cert_hash) | Approved issuer or admin | Sets the credential status to Verified; emits cert_ver |
| link_payment(employer, student, cert_hash, amount) | Employer | Transfers XLM via the native Stellar Asset Contract directly to the verified student; emits payment |
These three functions sit on a 19-function surface: an issuer trust layer (register_issuer → approve_issuer, plus suspend_issuer), credential lifecycle controls (revoke_certificate, suspend_certificate), an admin-initiated reward_student payment, read-only lookups (get_certificate, get_issuer), and a seven-function milestone-escrow extension for funded paid trials (create_opportunity through get_opportunity). A revoked credential blocks downstream payments on-chain. The full reference, including error codes and the status lifecycle, is in /docs/contract.
Quickstart: try the pilot
You can go from zero to a signed testnet transaction in a few minutes. Step 1 requires nothing installed.
1. Open a proof page — no wallet required
Open a live verified credential: https://stellaroid.tech/proof/c02ce1602d5bbb6ddfe93c6603d7f4e3dae3b2fb571ea4e70669ccd5a359aea3 — the page reads the certificate record from the contract via simulateTransaction. A green badge means verified on-chain; amber means issued but not yet verified.
2. Connect a wallet on testnet
Install the Freighter browser extension and switch it to Testnet, or use Albedo, a web-based wallet that also covers the mobile signing path. Then open https://stellaroid.tech/app and connect.
3. Fund a testnet account via friendbot
Testnet accounts are funded with test XLM by friendbot, Stellar's testnet faucet. With the Stellar CLI (v26+), the --fund flag friendbot-funds the key at creation:
stellar keys generate my-key --network testnet --fund
stellar keys address my-key4. Run the /app flow
The dashboard at https://stellaroid.tech/app has two roles. As an issuer, you register a certificate hash for a student wallet and then approve it (verify_certificate). As an employer, you paste a verified hash and an amount to send a credential-linked XLM payment. Note the trust gate: issuer registration enters a Pending queue on-chain, and only admin-approved issuers can register or verify credentials — suspended issuers are blocked at the contract level.
Documentation map
| Page | What it covers |
|---|---|
| /docs/contract | Full Soroban contract reference: all 19 public functions, typed error codes, events, and the credential status lifecycle |
| /docs/integration | Calling the contract from your own frontend: environment config, the wallet layer (Freighter + Albedo), and the read/write transaction paths |
| /docs/architecture | System design: the Next.js app, two read paths (server-rendered proof pages + client-side simulation), one write path, and event indexing |
| /docs/security | Security posture: contract access control, CSP and security headers, input validation, and the fee-sponsor authorization boundary |
Source and deployment
- GitHub repository (MIT license): https://github.com/Iron-Mark/Hackathon-Stellaroid_Earn
- Contract source: https://github.com/Iron-Mark/Hackathon-Stellaroid_Earn/tree/main/contract
- Deployed contract (testnet): CDMUOHMARNVOJZM3IVOCJUPGBHDTHFBMZCCZXEZPQDVJGILH3NIKTTW3 — inspect it at https://stellar.expert/explorer/testnet/contract/CDMUOHMARNVOJZM3IVOCJUPGBHDTHFBMZCCZXEZPQDVJGILH3NIKTTW3
- Live app: https://stellaroid.tech · operational status: https://stellaroid.tech/status
The deployed testnet contract's WASM hash is 59ca403e347f4c24b1dd16fbcb65662c2837cc852946e3ae88374eed509d6f7f. Build/source verification (contract metadata plus GitHub attestation) is tracked in the repo's verification runbook and is not yet complete, so the deployment should not be described as source-verified.
Frequently asked questions
- Is Stellaroid Earn running on Stellar mainnet?
- No. All flows run on Stellar testnet only. Stellaroid Earn is a free early-access pilot with no purchase, subscription, or mainnet funds involved, and it should not be treated as a production financial product.
- Do I need a wallet to verify a credential?
- No. Proof pages are public and read-only — they check on-chain state via simulateTransaction, so anyone can confirm a credential without a wallet, login, or API key. A wallet is only needed to issue, verify, or pay on-chain.
- Which wallets does Stellaroid Earn support?
- Freighter (a browser extension, set to Testnet) and Albedo (a web-based wallet that also covers the mobile signing path). Reads never require a wallet; writes are signed by whichever wallet you connect.
- Where can I inspect the deployed contract?
- The contract is deployed on Stellar testnet at CDMUOHMARNVOJZM3IVOCJUPGBHDTHFBMZCCZXEZPQDVJGILH3NIKTTW3 and can be inspected on Stellar Expert. The Rust source lives in the contract/ directory of the GitHub repository under an MIT license.
- Can anyone register credentials on the contract?
- No. Issuers self-register on-chain into a Pending queue and must be approved by the admin before they can register or verify credentials. Suspended issuers are blocked at the contract level, and revoked credentials block downstream payments.
Run it yourself on testnet
Everything documented here is live in the early-access pilot — free, testnet-only, and auditable on stellar.expert.