Shardy x Stellar Technical Architecture

Shardy combines a browser-native compute plane (WebGPU/WASM workers with local Groth16 proof generation), an orchestration plane (Bun + libp2p dispatch, telemetry, redundancy, and result reconciliation), and a Stellar settlement plane (Soroban contracts for task escrow, staking, slashing, epoch settlement, and payout routing). Heavy compute and proof generation remain off-chain for latency and cost efficiency; economically critical state transitions are finalized on Stellar. Submitters pre-fund jobs in XLM or Stellar-issued assets, workers and orchestrators lock collateral, and verified task batches are settled through auditable onchain events and payouts. In this design, Stellar is not an add-on - it is the mechanism that makes Shardy’s verifiable compute market production-usable.

This document defines the planned grant scope for the Stellar-native economic layer. It is intentionally technical and self-contained so the integration boundary, contract responsibilities, and delivery targets can be evaluated without reference to token or sovereign-L1 narratives elsewhere in the public material.

1. System Overview

Shardy is organized around four cooperating planes:

• Compute plane: Browser-native workers execute WebGPU and WASM workloads, persist local scratch state in OPFS, and generate Groth16 proofs tied to result digests.
• Control plane: The Bun-based orchestrator accepts jobs, benchmarks workers, dispatches tasks, verifies outputs, handles redundancy, and advances the task lifecycle.
• Gossip plane: libp2p networking propagates worker presence, verification certificates, and peer coordination signals across the mesh.
• Settlement plane: Soroban contracts finalize the economically critical state transitions for job funding, collateral custody, slashability, payout routing, and public receipts.

Existing Shardy architecture mapped to the grant

2. Soroban Contract Suite

The grant scope centers on five contracts. The names below are canonical and should remain consistent across docs, dashboards, SDKs, and milestone reporting.

3. Off-chain vs On-chain Boundary

The integration is designed around a strict boundary: compute remains off-chain, while economic finality moves on-chain.

4. End-to-End Lifecycle

The lifecycle below is the canonical planned flow for the grant build.

Lifecycle stages

1. Fund job The submitter pre-funds a job in XLM or a Stellar-issued asset. TaskEscrow locks value before dispatch begins.
2. Register and lock stake Workers and orchestrators register through WorkerRegistry and maintain slashable collateral in StakeVault.
3. Dispatch and execute The orchestrator assigns work to browser-native workers using Shardy’s existing control and gossip planes.
4. Verify result Workers return result digests and Groth16 proofs. The orchestrator verifies correctness and redundancy off-chain.
5. Commit settlement epoch Verified task outcomes are grouped into an epoch record and finalized in SettlementEpoch.
6. Pay or slash FeeRouter distributes payouts, fees, or slash outcomes, while events expose the final public settlement trail.

5. Asset Model

The planned economic layer supports:

• XLM for straightforward job funding, stake custody, and payout routing.
• Stellar-issued assets via the Stellar Asset Contract (SAC) interface when ecosystem partners or applications need a specific settlement asset.

Asset handling rules for the grant scope:

• Funding and payout flows should use the same contract suite and event model regardless of whether the job is funded in XLM or a SAC-compatible asset.
• The SDK should expose asset selection explicitly rather than hiding the settlement asset behind runtime-specific logic.
• The first production launch can begin with a narrower asset set if needed, but the architecture and contract interfaces should remain SAC-compatible from the start.

6. Browser UX Model

The browser UX must preserve Shardy’s browser-native character rather than shifting complexity to users.

Auth-entry signing

• Browser users authorize contract actions using Soroban auth-entry signing.
• Authorization covers the user-approved action, while a separate relayer can handle transaction submission.

Relayed fee payer

• A fee-paying service submits the signed contract call and pays Stellar fees on behalf of the browser user.
• This keeps the UX aligned with browser onboarding, where users should not need deep wallet or fee-management expertise before trying the product.

UX implications

• Job funding can feel like an application action rather than a low-level contract interaction.
• Worker and orchestrator operators can keep one browser-first workflow for runtime participation and settlement authorization.
• The SDK can expose a clean authorize -> relay -> confirm pattern instead of forcing each app integrator to invent its own transaction flow.

7. Events, Indexing, and Public Verification

Public verifiability is a core reason to use Stellar here. The grant scope therefore includes both contract events and the supporting read layer.

Contract events

Each contract should emit structured events for the state changes external observers need to track:

• TaskEscrow: job funded, job released, job refunded
• StakeVault: stake locked, stake unlocked, slash executed
• SettlementEpoch: epoch opened, epoch committed, epoch disputed if a dispute path is added
• FeeRouter: payout routed, fee split routed, slash routed

Indexing and monitoring

• An indexer or event-consumption service will ingest Soroban events and expose them to the dashboard, explorer pages, and SDK readers.
• Monitoring should tie together off-chain verification status and on-chain settlement state so operators can identify stalled epochs, missing payouts, or failed relays.
• Public dashboards should display enough information to verify that a funded job reached settlement and what the final payout or slash outcome was.

Public verification trail

The intended audit path for any reviewer or user is:

1. Confirm that a job was funded in TaskEscrow.
2. Confirm that the relevant operator stake existed in StakeVault.
3. Confirm that the verified batch was committed in SettlementEpoch.
4. Confirm that funds were routed through FeeRouter.
5. Confirm the resulting Soroban events and transaction history through public RPC and indexer reads.

8. Open-source Plan

All Soroban contracts delivered under this grant should be open-sourced in the public Shardy repository.

The minimum public delivery set is:

• Source for TaskEscrow, WorkerRegistry, StakeVault, SettlementEpoch, and FeeRouter
• Unit and integration tests for the contract suite
• Deployment notes and published contract IDs for testnet and mainnet milestones
• SDK examples showing job funding and settlement reads
• Documentation for event formats and indexer expectations

This open-source plan matters because the contract suite is part of the product’s trust model, not a private implementation detail.

9. Milestone Mapping

This document supports a three-stage build narrative:

10. Relationship to Existing Shardy Docs

This document is the grant-specific architecture for the planned Stellar integration. It complements, but does not replace, the existing technical docs for the current runtime:

• Technical Architecture
• Task Execution and Verification
• Network and Node Technical Deep Dive

For reviewers, this page should be treated as the canonical explanation of how Shardy’s browser-native compute plane connects to its planned economic finality layer on Stellar.