Contract reference

The Stellaroid Earn contract is written in Rust with soroban-sdk and deployed to Stellar testnet. It exposes 19 public functions: a one-shot init, nine credential-surface write functions covering issuer trust, credential lifecycle, and payment, two read functions, and a seven-function milestone-escrow extension for funded paid trials (documented below). The frontend invokes it through @stellar/stellar-sdk — writes are signed by the connected wallet and submitted over Soroban RPC; reads run as free simulations.

Function surface

Auth requirements below are derived from the on-chain roles each function encodes: the admin wallet set at init, issuers in the approval queue, and the employer or student addresses passed as arguments. Unauthorized callers are rejected with error 3 Unauthorized.

Credential status lifecycle

A credential moves through five on-chain statuses. Actions attempted in the wrong state fail with error 10 InvalidStatus.

Status transitions are one-way: verify_certificate requires an Issued credential (a suspended credential cannot be re-verified) and revocation is terminal. The frontend additionally defines an unknown status as a client-side fallback for records it cannot decode; it is not an on-chain state.

Error codes

All 12 contract errors, as surfaced to callers and normalized by the frontend error layer.

Events

The contract emits events as Soroban RPC events with a symbol topic. The app's activity feed decodes the following event kinds; anyone can audit them independently on a Stellar explorer such as stellar.expert.

A cert_fail event kind also exists; the frontend activity feed intentionally filters it out of the public feed.

Calling the contract

Writes via Stellar CLI

Write functions require the caller's signature. With Stellar CLI (v21+, stellar contract invoke — the deprecated soroban CLI is not used) and a funded testnet identity, registering a certificate looks like this:

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source my-key \
  --network testnet \
  -- \
  register_certificate \
  --issuer <ISSUER_G_ADDRESS> \
  --student <STUDENT_G_ADDRESS> \
  --cert_hash <64_CHAR_SHA256_HEX> \
  --title "Soroban Bootcamp Certificate" \
  --cohort "2026-Q2" \
  --metadata_uri "https://example.com/credential.json"

cert_hash is a 32-byte value supplied as 64 hexadecimal characters — the frontend converts the hex string to a bytes32 ScVal before invoking, and the same format applies from the CLI. The invoking issuer must already be registered and approved, or the call fails with error 7 IssuerNotFound or 8 IssuerNotApproved.

Reads are free simulations

get_certificate and get_issuer never touch the ledger. The frontend builds an unsigned transaction from a configured read address (with a hardcoded fallback account when none is set) and executes it via the RPC simulateTransaction method, decoding the return value with scValToNative. No wallet, no signature, and no fee is required — this is what powers the public proof pages.

How the frontend submits writes

• Builds an invokeContractFunction operation with TransactionBuilder at BASE_FEE, pinned to the expected network passphrase from config.
• Prepares the transaction against Soroban RPC (with a raw-simulation fallback for SDK XDR parse failures), then hands the XDR to the connected wallet — Freighter or Albedo — for signing.
• Submits via sendTransaction and accepts PENDING or DUPLICATE as in-flight statuses, then polls the transaction result for up to 20 attempts at 1.2 s intervals.
• Serializes arguments with nativeToScVal; addresses as address, strings as string, and certificate hashes as 32-byte values converted from hex.

Test coverage

The contract ships with twelve tests in contract/src/test.rs (t1–t12). Together they cover the happy path, the issuer trust layer, revocation gating, event emission, and the escrow lifecycle.

Escrow extension: funded paid trials

Beyond the credential core, the contract includes a milestone-escrow extension that lets an employer fund a paid trial tied to a verified credential. The escrowed amount is held by the contract and released as milestones are approved. These seven functions complete the 19-function public surface.

The extension adds five typed error codes on top of the credential-surface errors:

Escrow events mirror the flow: opp_crt, opp_fund, mile_sub, mile_apr, pay_rel, and pay_ref — all auditable on stellar.expert alongside the credential events.