Documentation · v0.1 testnet MVP

SprintOS

A milestone review and settlement workflow on Stellar. The sponsor funds defined work, the builder submits public proof, and a human reviewer decides. AI can advise, but it cannot approve, sign, or move funds.

Open the app Evidence pack

01 · Getting started

Run the app

SprintOS is a Next.js web app, a Soroban settlement contract and a separate advisory package. Reads work without a wallet. Every write is simulated, prepared and signed by the connected wallet.

cp .env.example .env.local
pnpm install
pnpm dev

Serverless storage is required on Vercel.Create a Blob store in the project's Storage tab and connect it to the project. Vercel then adds BLOB_READ_WRITE_TOKEN. Never commit that token.

Set NEXT_PUBLIC_APP_URL to the deployed HTTPS origin before creating an engagement. That URL is written into the evidence pointer stored by the contract.

Check deployment health · Read the first-month evidence pack

02 · Workflow

One engagement, three roles

Sponsor

Connect a wallet, choose a repository, define up to three milestones, assign distinct builder and reviewer wallets, then fund the escrow.

Builder

Open the assigned milestone, attach up to five public evidence links, add a note, and sign the evidence hash on chain.

Reviewer

Compare the criteria and evidence, optionally request the advisory report, attest to reading the work, then sign Approve or Hold.

Settlement

Release is a separate reviewer signature. A sponsor can refund an eligible overdue milestone; an approved payment can also be claimed by its builder.

State changes are final on the deployed contract.Criteria are hashed before creation, evidence is hashed at submission, and a released payment cannot be undone. Review before signing.

03 · Trust model

The AI is outside the money path

The advisory package reads bounded public evidence only when a reviewer asks for it. It returns a structured score, checklist, links and missing information. The report is stored off chain with a content hash and always has binding: false.

Can do

Read credential-free public evidence.
Produce a validated advisory report.
Suggest Ready for Review or Revision Suggested.

Cannot do

Import Stellar SDK or signing code.
Approve, Hold, release, claim or refund.
Change milestone state or access private repositories.

See the 100/100 boundary proof · Security model

04 · Evidence integrity

Documents are identified by their hashes

Criteria and evidence are canonicalized and SHA-256 hashed. The exact hash is stored in the milestone. The reviewer screen asks the server to retrieve the matching document and recompute the hash before enabling a decision.

Criteria: Written before creation; bound by the criteria hash in create_engagement.
Evidence: Written by the builder; bound by the evidence hash in submit_evidence.
Report: Keyed by engagement, milestone and evidence hash; an old report cannot silently follow a new submission.
Activity: Transaction hashes are read back from RPC and decoded before the public index accepts them.
Evidence version: Each submit_evidence call anchors its own hash; the activity index preserves every past one, not only the current.

Approval and release example · Hold and refund example · Public Proof page · Full evidence pack

05 · Reference

Configuration and endpoints

Environment

Variable	Purpose
`NEXT_PUBLIC_APP_URL`	The public deployment URL. Required before writing evidence on chain.
`BLOB_READ_WRITE_TOKEN`	Vercel Blob token for criteria, evidence, reports and activity.
`OPENAI_API_KEY`	Optional advisory report and milestone-plan generation.
`NEXT_PUBLIC_STELLAR_RPC_URL`	Optional testnet RPC override.
`GITHUB_TOKEN`	Optional higher rate limit for public repository scans.
`NEXT_PUBLIC_NETWORK_MODE`	"mainnet" or unset/testnet. Refuses to start in mainnet mode until deployment.mainnet.json is fully filled in.
`NEXT_PUBLIC_TREASURY_ADDRESS`	Where a SprintOS Plus or Pro payment is sent. Unset means this deployment does not sell either tier.

HTTP surface

Method	Path	Purpose
`GET`	`/api/health`	Non-secret deployment diagnostics, including which network this deployment is on.
`POST`	`/api/criteria`	Validate and store acceptance criteria by hash.
`POST`	`/api/evidence`	Validate and store a builder evidence bundle by hash.
`POST`	`/api/advisory`	Run a requested, non-binding advisory report — Standard or Deep, metered against the caller's Free/Plus/Pro entitlement.
`GET`	`/api/advisory`	Read a stored report and verify its hash.
`GET`	`/api/activity?engagement_id=2`	Read indexed, network-verified transactions.
`GET`	`/api/account?address=G...`	A wallet's Free/Plus/Pro plan and remaining reviews this period.
`POST`	`/api/account/activate`	Activate Plus or Pro after a payment in an accepted asset is confirmed on the network.
`GET`	`/api/policy?engagement_id=2`	The multi-reviewer approval threshold a sponsor configured, if any.
`POST`	`/api/policy`	Set that threshold. Sponsor only.
`GET`	`/api/attestation`	A milestone's reviewer attestations for one evidence version, and the tally against the threshold.
`POST`	`/api/attestation`	Record one reviewer's attestation. Never itself moves funds — see /evidence/ai-boundary.
`POST`	`/api/v1/review`	The public Review API for platforms outside a SprintOS engagement. Bearer key required — see docs/REVIEW-API.md.

The deployed MVP is pinned to Stellar testnet. The settlement contract is CBOC76VCX3BR2UYOWQQNHRPKG27PSPE7X42YAQEDI3ZTKNL53U2CYGS6 and the asset is the testnet USDC SAC CAR6QZIC7NTQ4PFLOTD2434YZ6PRDHVJHL5GZIRT62VAJJBRL5IYUIU3.

06 · Verification

Reproduce the claims

These checks require the repository but no wallet, secret key or API token.

cargo test --package sprintos-settlement
pnpm test
pnpm typecheck
pnpm lint:boundaries
pnpm evidence:doc

AI boundary evidence Setup and usage Architecture Stellar contract

Mainnet settlement is deliberately not enabled in this release. It belongs to the second month scope and must be delivered with a separate mainnet deployment, a small explicit fund cap, manual wallet signatures, and public transaction evidence.

Following the trail