diff --git a/rfps/source-verification/README.md b/rfps/source-verification/README.md new file mode 100644 index 0000000..c52aaa8 --- /dev/null +++ b/rfps/source-verification/README.md @@ -0,0 +1,118 @@ +# Contract Source Verification Service + +This tracks our application for the [Contract Source Verification Service RFP](https://stellar.gitbook.io/scf-handbook/scf-awards/build-award/rfp-track#contract-source-verification-service). In case of link rot, the full text of the original RFP is pasted below: + +### Contract Source Verification Service + +*Added: Q2 2026* + +#### 1. Scope of Work + +Design and deliver a public, hosted contract source verification service for Soroban smart contracts. The service consumes the [SEP-58](https://github.com/stellar/stellar-protocol/pull/1933) metadata vocabulary (bldimg, bldopt, source\_repo, source\_rev, tarball\_url, tarball\_sha256), rebuilds submitted source in a defined environment, compares the resulting Wasm to the deployed Wasm, and exposes the result to downstream consumers (explorers, wallets, the CLI). The service must cover both public source (git repo plus commit) and private source (content-addressed via `tarball_sha256` alone, suitable for auditor-mediated rebuilds). + +This service sits downstream of an already-shipping foundation. SDF is publishing the trusted stellar-cli-docker image plus "how to build" and "how to verify" guides on a shorter timeline. Asset issuers, contract developers, and planned verifiers (OrbitLens, Aha Labs, 57B) use those directly in the near term. The hosted service this RFP funds aggregates verifications across the ecosystem and serves results to downstream tools. + +Deliverables span: + +* **Audit readiness:** threat model, security review, and audit fixes prior to production handoff. +* **Offchain service components:** a verification service that accepts source submissions (tarballs or equivalent), rebuilds the Wasm using an SDF-allowlisted trusted build image, and links the resulting Wasm digest to the source artifact. +* **Public API:** a stable, free API for querying verification status by contract ID or Wasm hash. Returns SEP-58 fields plus verification status and timestamps. +* **Integration examples:** reference integrations for explorers, wallets, and other downstream tools. +* **Developer-facing submission flow:** a CLI or web interface so contract authors can submit their own deployments. +* **Documentation:** contributor-facing docs for submitters and integrator-facing docs for consumers +* **Audit readiness:** threat model, security review, and audit fixes prior to production handoff. + +**Explicitly out of scope:** + +* **Display-layer policy decisions by individual verifiers** (e.g., whether to surface verifications for contracts without publicly retrievable source). The service may expose auditor signals or off-chain attestations if available, but is not required to define their semantics. +* **Authoring SEP-58, SEP-55.** Coordination is expected; authorship is not. +* **Producing the official trusted stellar-cli Docker images.** SDF maintains these via stellar-cli-docker. Vendors consume the SDF-published images. +* **Updates to SDF-owned tooling** (stellar-cli, Stellar Lab) beyond exposing the APIs those tools consume. SDF builds those integrations in-house. +* **Explorer UI work on any specific third-party explorer** (Stellar Expert, StellarChain), though the service must expose what they need. +* **Fully deterministic Rust compilation as a research effort.** Use the best available reproducibility today, anchored on the SDF-allowlisted trusted images. + +#### 2. Background & Context + +[SEP-58](https://github.com/stellar/stellar-protocol/pull/1933) (Draft, in active review since 2026-05-15) defines the metadata a Soroban contract embeds, or surfaces off-chain, so any verifier with the source can rebuild the Wasm and confirm the bytes match. SEP-58 is a vocabulary. It leaves the service implementation, build infrastructure, and explorer integrations to ecosystem teams. This RFP funds the service layer. + +SEP-58 complements [SEP-55](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0055.md), which uses signed CI attestations to bind a workflow run to a commit and a Wasm. SEP-55 asks "did a trusted CI compile this Wasm?". SEP-58 asks "does this source produce this Wasm?". A contract can carry meta supporting both. Verifiers pick whichever path fits their threat model. + +Soroban contracts deploy as opaque Wasm bytes. Today, an explorer can display source code linked to a contract, but the connection between that source and the deployed bytes is not protocol-level provable. SEP-58 provides the standard inputs. The remaining work is a service that performs rebuilds and serves results to downstream tools, so each tool doesn't run its own rebuild infrastructure. + +SEP-58 is mode-agnostic about source retrieval. Public repos use source\_repo + source\_rev. Hosted tarballs use tarball\_url + tarball\_sha256. Closed-source builds use tarball\_sha256 alone, committing to specific source bytes without naming a retrieval channel (suitable when only an auditor with access can rebuild). What differs between public and private source isn't the spec; it's who rebuilds and which verifiers display the result. Some verifiers (e.g., Stellar Expert) will not auto-verify contracts without publicly retrievable source. The service must support all SEP-58 source modes; downstream display decisions are out of scope. + +**Ecosystem context:** + +* **Complementary CLI work:** stellar-cli [PR #2585](https://github.com/stellar/stellar-cli/pull/2585) adds `stellar contract build --verifiable`, which runs the build inside a digest-pinned Docker container and stamps SEP-58 metadata into the Wasm. [PR #2586](https://github.com/stellar/stellar-cli/pull/2586) adds `stellar contract verify`, which reads the metadata, re-runs the recorded build, and byte-compares the result. The CLI verifies locally with no service dependency. This RFP funds the shared layer aggregating results across verifiers. +* **Trusted build images:** SDF maintains stellar-cli-docker, which publishes attested Docker images for use as bldimg values. The publish pipeline ([PR #3](https://github.com/stellar/stellar-cli-docker/pull/3)) targets a first published image in late May 2026. It covers public Dockerfiles, SLSA build provenance, SBOMs, pinned base images, and a defined release cadence. +* **Multi-dimensional trust:** reproducibility alone is not faithfulness to source. A hostile image can deterministically rewrite bytes and still pass byte-comparison. The service should treat image trust as a signal (arbitrary deployer image, publicly auditable image, SDF-maintained trusted image), not a binary. +* **Existing in-house prototype:** [stellar-experimental/contract-verifications](https://github.com/stellar-experimental/contract-verifications) is a starting point but is not production-ready. +* **Internal boundary:** SDF builds the CLI, trusted images, and Stellar Lab integrations. The hosted public verification service is a fit for external funding. + +Other ecosystems have solved this via [Sourcify](https://sourcify.dev) (EVM) and [solana-verify](https://solana.com/docs/programs/verified-builds). Stellar needs an equivalent, either adapted from existing tooling or purpose-built for Soroban. Respondents may propose either approach. + +#### 3. Requirements + +**Functional requirements:** + +* Accept source code submissions (tarball or equivalent) tied to a target Wasm hash. +* Rebuild the submitted source using an **SDF-allowlisted trusted build image** referenced via SEP-58 bldimg. Vendor describes its image allowlist policy in the proposal. +* Expose a free, public API for querying verification status by contract ID or Wasm hash. Response includes at minimum: verification status, SEP-58 fields recorded (bldimg, bldopt, source\_repo, source\_rev, tarball\_url, tarball\_sha256 as applicable), linked source artifact, build metadata, image trust signal, and verification timestamp. +* Provide a shared verification result layer that explorers, Lab, wallets, and other consumers can query without performing their own rebuilds. Verification runs once and the result is available via API. Hard requirement: solutions that force every consumer to rebuild, or that rely on a single hardcoded verifier, do not meet the bar. +* Support **multi-verifier architecture.** Each verifier reports its result against the deployed Wasm hash. Disagreement surfaces as a per-verifier signal (e.g., \[√] Verified by X, \[!] Mismatching verification by Y), not a single "correct" status. +* Support mainnet and testnet. +* Handle contracts deployed before service launch (**retroactive verification for non-upgradable contracts is a priority requirement,** since many existing deployments cannot be redeployed). +* Source retrieval must not hardcode HTTPS or GitHub. The API and rebuild flow accept all SEP-58 source identifier modes: public repo (`source_repo` + `source_rev`), hosted tarball (`tarball_url` + `tarball_sha256`), and content-addressed (`tarball_sha256` alone). **IPFS retrieval is a first-tier channel alongside HTTPS.** Vendors may propose which modes their service handles directly versus surfaces from off-chain sources; the API must distinguish modes in responses. +* Provide a CLI or developer-facing submission flow. API shaped to integrate with [stellar-cli](https://github.com/stellar/stellar-cli). +* Expose verification metadata in a form consumable by explorers (Stellar Expert, StellarChain, [Stellar Lab](https://github.com/stellar/laboratory)) and other downstream tools. +* **Coexist with SEP-55 attestations and SEP-58 rebuild verification as distinct trust levels.** The API distinguishes them. + +Conform to the forthcoming verifier-API SEP (currently unauthored, expected to follow SEP-58). Vendor commits to align the API once that spec lands. + +**Non-functional requirements:** + +* **Explain your approach** in the [SEP-58 discussion thread](https://github.com/orgs/stellar/discussions/1923) before or during proposal submission. +* **Security**: tarball storage must be tamper-evident; rebuild environment isolated from host; submitted code must not exfiltrate secrets or affect other submissions; write endpoints must have abuse and DoS protections. +* **Audit**: third-party security audit required before production launch. Scope: rebuild environment, tarball integrity, API authentication, image allowlist policy. Auditor coordinated by SDF via the audit bank. +* **UX**: a contract developer should verify a deployed contract in under 15 minutes from reading the docs to seeing the verification appear. +* **Decentralization of verification**: architecture must allow multiple independent verifier instances to publish results. Proposals describe how disagreement surfaces and how consumers pick a trusted set. +* **Performance:** verification requests complete or return queued status within 5 minutes for standard contract sizes. +* **Availability:** public query API targets 99%+ uptime. +* **Storage and retention:** vendors propose tarball and rebuild-artifact retention policy. Egress cost ownership made explicit. +* **Operational ownership post-grant:** hosting, on-call rotation, and funding tail addressed in the proposal. +* **Compliance:** operable as a public good without KYC or gated access. No user data collection beyond what's necessary for abuse prevention. +* **Openness:** codebase open-source and self-hostable. Production deployment should allow community operation over time.
+ +**Interfaces SDF will provide before contract execution:** + +* The CLI to Service interaction contract (being resolved internally). Vendors should support either a service-mediated submission flow or a decentralized on-chain result discovery model; SDF will name the shape before the design phase. +* The stellar-cli-docker image allowlist endpoint and trust criteria for adding image sources. +* Any SEP-58 amendments landing before the vendor's design phase (e.g., the home\_domain field amendment under discussion). + +#### 4. Evaluation Criteria + +* **Technical capability:** demonstrated experience building reproducible build pipelines and verification infrastructure. Familiarity with Sourcify, solana-verify, or equivalent is strong evidence. +* **SEP-58 alignment:** proposal maps to the SEP-58 vocabulary and consumes SDF-published trusted images via bldimg. +* **Display-layer design:** how downstream tools (explorers, Lab, wallets) consume verification status without running their own rebuilds, including multi-verifier divergence UX. +* **Decentralization design:** concrete architecture for running multiple independent verifier instances. +* **Image trust policy:** allowlist policy and handling of image source eviction. +* **Relevant experience:** prior work on Sourcify or equivalent services, or deep Soroban / Rust toolchain experience. +* **Security & audit history:** track record of shipping audited infrastructure; threat modeling in the proposal. +* **Ecosystem alignment:** willingness to coordinate with explorer teams (Stellar Expert, StellarChain), SDF tooling teams (stellar-cli, Stellar Lab), and ongoing SEP discussions ([SEP-58](https://github.com/orgs/stellar/discussions/1923), the forthcoming verifier-API SEP, SEP-55 evolution). +* **Ability to deliver within required timeline:** realistic milestone plan. +* **Coherent integration plan:** how explorers and other consumers adopt the service, including API stability guarantees and the path to conformance with the forthcoming verifier-API SEP. + +#### 5. Expected Deliverables + +* Verification service codebase, open-source and self-hostable. +* Public deployment for mainnet and testnet. +* Stable public API with documented schema and versioning policy. +* SDK or client library for querying verification status, designed to conform with the forthcoming verifier-API SEP once authored. +* Contract developer CLI or submission interface. +* Image allowlist policy documented, with a published mechanism for adding new image sources. +* Integration documentation for explorers and downstream tools. +* User documentation for contract developers, contributed to Stellar Developer Docs. +* Test suite covering verification logic, API, rebuild environment, and image-trust signals. +* Security audit report and resolved findings (through Audit Bank). +* Production-ready service with operational runbook, monitoring, and on-call coverage. +* At least one reference integration, ideally [Stellar Lab](https://github.com/stellar/laboratory) or a cooperating verifier (OrbitLens / Stellar Expert, Aha Labs / rgstry.xyz, or 57B). diff --git a/rfps/source-verification/full-application.md b/rfps/source-verification/full-application.md new file mode 100644 index 0000000..b261172 --- /dev/null +++ b/rfps/source-verification/full-application.md @@ -0,0 +1,146 @@ +# Project Title + +Verified Stellar Sources + +# Submission title +> Make a unique title that's different from your project name and reflects what you're asking funding for + +Source Verification Network & Hub + +# One Sentence Description +> Use less than 130 characters to describe the products/services you`re planning to build in your submission, how it works, and your target audience. This is your opportunity to capture the attention of your reader and gain buy-in! A frequently used format is: “Develops/Offers/Gives/etc. _(a defined offering)_ to help/support _(a defined audience)_ _(solve a problem)_ with _(secret sauce)_”. Read more about this format and see examples in this blog post. + +A network of Source Verification services, led by Runtime Verification. An hub for verification data, built on Stellar Registry. + +# Code URL +> Enter the URL of the relevant github page. + +https://github.com/stellar-registry + +# Video URL +> This is your elevator pitch: keep it short (<3 min), powerful, and clearly demonstrate the project's features and functionality. Upload your demo video on Youtube or Vimeo with a 16:9 aspect ratio (ideally 1920px by 1080px). + + +# Soroban + +Yes + + +# Product and Services +> Briefly describe the to be added / improved products and services by this submission. Keep it succinct, and for each feature add how Stellar is used and how the improvements will impact your project. + +We will build a network of verification services and the on-chain, public-infrastructure hub to integrate them all and surface their information. + +1. Source-verification services: following the example already provided in the [SEP precursor discussion](https://github.com/orgs/stellar/discussions/1923), these services will monitor wasms uploaded to Stellar that contain the `(source code, build image)` pair given by the SEP (the full list of possible `contractmetav0` items, which can be combined in a few valid ways, is: `bldimg` / `bldopt` / `source_repo` / `source_rev` / `tarball_url` / `tarball_sha256`). For each such wasm, these services will: + 1. Check if the `bldimg` is from a trusted source. For now, this means it must refer to a [SDF-maintained `stellar-cli` container](https://hub.docker.com/r/stellar/stellar-cli). + 2. Check that the source code is publicly available and well-formed (meaning there is a `source_rev` that matches the one given). (This proposal only covers open source repositories for now; see the Future Work section outlining a closed-source-with-auditing alternative as outlined in [Chad’s Item \#4 from the SEP precursor discussion](https://github.com/orgs/stellar/discussions/1923#discussioncomment-16882699).) + 3. If both of the above are true, pull that container, pull that source code, and run `stellar contract verify` for that source code within that container. + 4. Check if the result of `verify` confirms that the given `(source code, build image)` pair do, indeed, result in the `wasm_hash` of the uploaded wasm. + 5. Submit the result of this check to Stellar Registry (see below). +2. Stellar Registry data hub: Stellar Registry already allows adding names and semantic versions to Stellar smart contracts, turning the inscrutable trail of wasm hash uploads into a meaningful (and instrumentable) narrative. Once `(source code, build image)` information is added to the wasm metadata, Registry will also expose this data via its contract calls and UI. + + Crucially, this information will initially be shown as *unverified*. We will add a `verify_source` contract endpoint, gated to an allow-list of known Source-Verification services (item #1 above). Rather than showing a simple checkmark if a source-verification service confirms a `source code + build image = wasm hash` match, Registry will expose *which* verifiers said *what*. It will surface disagreements, allowing consumers to make their own decision about whether to trust a wasm that is source-verified by some entities but which fails source-verification for others. + + Additionally, for wasms that have already been uploaded to Stellar which lack the new `(source code, build image)` data in their `contractmetav0`, Registry will allow adding these fields via the Registry contract. It will then emit an event which can be monitored by Source Verification Services, in addition to wasm uploads, so that their source verification process can run based on both on-chain events. + +This is a joint submission by **The Aha Company** and **Runtime Verification**. The Aha Company will build the Stellar Registry data integration point. Runtime Verification will provide an initial source-verification service. All aspects, from both Aha and RV, will be open source and well-documented, providing the whole ecosystem a solid foundation for 1\. retrieving source-verification information from Stellar Registry and 2\. implementing their own source-verification system, following RV’s example. + + +# Traction Evidence +> Provide evidence of prior traction or validation. Include users, community size, partnerships, KPIs (TVL...), beta testers to demonstrate adoption, market interest, and project credibility. + +## The Aha Company + +A Stellar-focused engineering firm with a strong delivery record: major contributions to the Stellar CLI, institutional work bringing Société Générale-Forge's EURCV stablecoin onto Stellar rails, and multiple SCF-funded public goods including Moonlight and Scaffold Stellar. We support ecosystem governance and developer education (largely through hackathons). + +This project extends infrastructure we already operate, Stellar Registry, which includes: + +* [`stellar-registry-cli`](https://crates.io/crates/stellar-registry-cli) published on crates.io (\~6,400+ all-time downloads). +* Live registry browser at [https://stellar.rgstry.xyz](https://stellar.rgstry.xyz); registry contract on testnet, mainnet rollout underway. +* Active in the SEP-55 / reproducible-builds discussions (\#1573, \#1923), where this registry effort is already flagged. + +## Runtime Verification + +A leading formal-verification and smart-contract security firm. Founded in 2010 by Grigore Roșu, creator of the K framework, it has since 2018 delivered formal verification and security services to major blockchain foundations and protocols including the Ethereum Foundation, Stellar, EigenLayer, Optimism, Uniswap, Lido, Gnosis, and Morpho. RV maintains widely-used open-source verification tooling such as Kontrol and Simbolik, and its formal-verification engine now powers Immunefi's Magnus security platform. RV also has extensive experience in the Stellar and Soroban ecosystem, having provided high-quality audits to DeFi protocols deploying on Stellar for over 2 years and developed tooling for Soroban like [Komet](https://komet.runtimeverification.com/) for fuzz testing and formal verification. RV will operate an independent verifier node in the network and provide audit-grade trust signals. + +## Ethan Frey ([@ethanfrey](https://github.com/ethanfrey)) + +Creator of CosmWasm, the WebAssembly smart-contract platform that directly inspired Soroban's architecture — Wasm runtime, Rust SDK, host-function model, and contract metadata sections all overlap. Through Confio, the company he founded, and building on earlier work as a contributor to the Cosmos SDK, CosmWasm grew into the dominant smart-contract engine in the Cosmos ecosystem, deployed across 30+ independent app-chains (Osmosis, Neutron, Sei, Injective, Archway, and others) and securing billions in on-chain value. He brings direct prior art for this RFP's hardest problem: he designed and shipped [CosmWasm/optimizer](https://github.com/CosmWasm/optimizer), the deterministic, toolchain-pinned Wasm build image that essentially every CosmWasm contract verification has run through for years and the proven blueprint for this project's Soroban build pipeline, along with the hard-won lessons (`--locked` enforcement, single-architecture determinism) now feeding directly into SEP-58; and he built [cosmwasm-verify](https://github.com/CosmWasm/cosmwasm-verify), a source-verification proof-of-concept (git repo + commit → deployed Wasm hash) that is essentially the centralized version of what this proposal decentralizes for Soroban. As an advisor to [Warp Drive](https://www.warp-drive.xyz), the Stellar port of [WAVS](https://wavs.xyz), he also brings the EigenLayer-style restaked operator network that provides the multi-operator, cryptoeconomically secured attestation layer this proposal depends on. He is actively shaping the live SEP-58 / reproducible-builds design (Stellar discussions [#1923](https://github.com/orgs/stellar/discussions/1923)) and working to standardize architecture deicisions via the SEP-process, like [Stellar Protocol PR #1951](https://github.com/stellar/stellar-protocol/pull/1951), so this verifier composes with the emerging standard rather than working around it, with all work MIT-licensed and built in the open. + + +# Technical Architecture +> Add an accessible link to your technical architecture of the to be added / improved product/services. +> +> The technical architecture should go into the specifics on the Stellar integration, demonstrating you have sufficient insight to start building immediately. +> +> We invite you to explore the various tools (CLI, SDK, etc.) provided by LOAM to facilitate your integration on Stellar: https://github.com/loambuild/loam?tab=readme-ov-file +> +> Here are examples +> - https://docs.google.com/document/d/1tXGALHBpMhbATfSnPKARBqctoyGoRPuge4Ukiv8j_Hc/edit?tab=t.0 +> - https://github.com/FrankSzendzielarz/SorobanRPCSDK +> => Good one - https://drive.google.com/file/d/167c6KVuyvRo7haInUahDfeMRxkO8gya3/view" + +[technical-architecture-highlevel.md](./technical-architecture-highlevel.md) + +# SCF Build Tranche Deliverables + +> Depending on the scope of your project, importance to the ecosystem, and team, you can request up to $150K in XLM for ~6 months to cover costs directly related to development of the product itself with the final goal being to launch on mainnet. Take a close look at the to determine your total budget request. +> +> You should divide your deliverables into 3 main milestones: Minimum Viable Product (MVP), Testnet, and Mainnet. +> +> Your award will be distributed in 3 equivalent tranches. The first upon approval of the submission, the second upon deliverable review of your MVP, and the third when you launch on Mainnet. The testnet tranche will not unlock an XLM award, but will provide you with access to the Stellar LaunchKit where you can apply for credits for audits and infrastructure offers. For each tranche, include estimated dates of completion, and a budget breakdown for each deliverable. +> +> Common issues: +> 1. SCF funding may not be used for marketing or promotion. Do not include these items in your budget. +> +> 2. Audit credits are provided as part of the testnet tranche completion. Audit costs should not be included in your budget. + + +## Tranche 1 - MVP + +[Deliverable 1] + +- Brief description +- How to measure completion +- Estimated date of completion +- Budget + +[Deliverable 2] + +etc. + + +## Tranche 2 - Testnet: + +[Deliverable 1] + +- Brief description +- How to measure completion +- Estimated date of completion +- Budget + +[Deliverable 2] + +etc. + + +## Tranche 3 - Mainnet: + +[Deliverable 1] + +- Brief description +- How to measure completion +- Estimated date of completion +- Budget + +[Deliverable 2] + +etc. + + +# Budget Total +Please note: submission with budgets amounts exceeding the maximum will be denied without review. Find budget guidelines for each award in the SCF Handbook. + + + + diff --git a/rfps/source-verification/technical-architecture-highlevel.md b/rfps/source-verification/technical-architecture-highlevel.md new file mode 100644 index 0000000..6559556 --- /dev/null +++ b/rfps/source-verification/technical-architecture-highlevel.md @@ -0,0 +1,227 @@ +# Verified Stellar Sources — Technical Architecture (High Level) + +**Purpose:** a shared reference for the three-party build — Ethan Frey (technical lead / architect), Runtime Verification (verification engine), and The Aha Company (contracts + indexed query API). This describes the *boundary and shape* the parties can agree on, not the full spec; the detailed design follows in the architecture documents (Milestone 1). + +--- + +## 1. The design: event-sourced verification + +The whole architecture is one idea applied consistently: **the chain carries verification *events*, and every queryable view is materialized from them.** + +A verification is an *event* — a signed, independently re-checkable claim ("verifier V rebuilt source S in image I and got hash H"), submitted as a transaction. The chain is not used as a store of mutable state; it is the ordered, tamper-evident log of what was claimed and when. Re-verifying a contract later, or a second verifier disagreeing, is simply another event. That cleanly splits the system into a write side and a read side: + +- **Write side — produce.** Verifiers rebuild contracts and append signed claims to the log (§4). +- **Read side — materialize & serve.** An indexer (GoldSky) consumes the event stream and materializes it into queryable views served behind an API (§5). + +```mermaid +flowchart LR + subgraph RV["Runtime Verification — Verifier engine (write)"] + Orchestrator + Sandboxes + end + subgraph AHA["Aha — contracts + read"] + BReg["Build-info registry
contract"] + VContract["Verification contract
(Registry sibling)"] + API["GoldSky indexer + Query API"] + end + Chain[(Stellar ledger
event log)] + Off[(Off-chain evidence
content-addressed)] + Consumers["Explorers / wallets / CLI"] + + Orchestrator -->|submit_verification| VContract + Orchestrator -->|full signed attestation| Off + BReg -->|build-info event| Chain + VContract -->|verification event| Chain + Chain -->|materialize events| API + Off -.->|evidence_uri| API + API --> Consumers +``` + +Because every reader materializes the same base facts from the same chain, **there is no privileged server.** The chain is the single source of truth for *events*; the queryable state is derived and replaceable. The reference query service is one materialization; others can be built. + +**Why the chain as the event bus — not pure P2P off-chain?** A gossip network would force operators to trust each other's ordering and completeness (an operator could silently drop or reorder claims), which means building hash-chained logs, cursors, equivocation detection, and cycle handling — a whole distributed-systems subsystem to write and audit. The ledger already provides global ordering, tamper-evidence, and non-equivocation for free. Using it as the event bus deletes that subsystem entirely. + +**Why materialize off-chain — not just on-chain RPC queries?** On-chain storage is a poor query surface: RPC gives point lookups, not the filtering, ranking, history, and cross-contract joins consumers actually need ("unverified contracts above X activity," "all mismatches," "results by image-trust level"). It's slow under load, and Soroban persistent storage carries TTL/rent, so it can't be the durable analytic store. Forcing every explorer and wallet to RPC the contracts per query is exactly the "every consumer rebuilds / one hardcoded verifier" outcome the RFP rules out. So: **chain for the event truth and ordering; a materialized index for speed and power.** + +**Where trust lives.** What counts as "verified" is decided at the **read layer** — not by the verifier, not by the contracts. Verifiers only produce re-checkable signed claims; the contracts only record events behind an anti-spam auth gate. The query layer applies a trust policy over the same facts, so one dataset can power a strict explorer badge and a permissive developer view at once, with no change upstream (§5–6). + +--- + +## 2. Ownership boundary + +The system has a single clean seam: **the on-chain contracts.** Everything that *produces* a result is the verifier side; the contracts and everything that *serves* results is the read side. Three parties, three areas of ownership. + +| Area | Owner | Responsibility | +| --- | --- | --- | +| **Architecture & SEP process** | **Ethan Frey** | Technical lead and architect: system design and review, the interoperability spec between parties, and driving the **SEP proposal process** (SEP-58 and the forthcoming verifier-API SEP) with SDF and the community | +| **Existing-contract recovery** | **Ethan Frey** | Recovering build metadata for old contracts that predate the standard, and the processes around rediscovering and re-submitting it | +| **Verifier engine** | **Runtime Verification** | Hermetic rebuild, byte-compare, sign, and submit the claim on-chain; publish off-chain evidence; operate an independent verifier | +| **On-chain contracts** | **The Aha Company** | The build-info registry and the verification contract (Registry-family siblings); **authorization/governance for who may write to each**; event emission | +| **Indexer + Query API** | **The Aha Company** | GoldSky materialization of chain events; the query API consumers use; trust policy applied at the endpoint | + +The parties build to the contract interfaces and can develop independently against them. The contracts are the API between the halves — so the items to lock early are the write shapes, the **event schemas**, and the off-chain evidence format (these are the Milestone 1 deliverables). + +--- + +## 3. The on-chain surface (event-first) + +Consumers never query the chain directly at scale; everything is materialized from events. There is one contract that **records verification claims**, and there are **two ways a verification run gets triggered**. + +### Two triggers for a verification run + +**Trigger A — native SEP-58 metadata in the wasm (the end state).** Any wasm uploaded to the network is checked. If it already embeds sufficient SEP-58 build metadata (`bldimg`, `bldopt`, source identifiers), that upload itself is enough: verifiers pick it up directly from the wasm and run verification immediately, with **no registry contract involved**. This is the steady-state path — a wasm that ships with proper metadata is verifiable the moment it lands. + +**Trigger B — build-info registry (the bridge from today).** Many already-deployed wasms carry no metadata, and not every future upload will embed it. The build-info registry covers them. Keyed by `wasm_hash`, it lets build info be submitted for a wasm that lacks it on-chain. Writing it **emits a build-info event** verifiers pick up, exactly as native metadata would. For **existing contracts** that predate the standard, build info is recovered off-chain and written here by an **authorized manager key** — the original wasm uploader or an Aha-governed manager, *not* anyone, so the registry can't be spammed with junk build info. This contract is the bridge between the current state (most contracts unverifiable) and the end state (metadata native in the wasm). + +Either trigger leads to the same downstream flow. + +### The verification contract + +Holds the signed claims. A verifier that has reproduced a `wasm_hash` submits `(wasm_hash, verifier, result, image_trust, evidence_uri, timestamp)`. Writing it **emits a verification event** that the indexer materializes and the API surfaces. + +```mermaid +sequenceDiagram + participant Up as Uploader / Manager key + participant Chain as Stellar (wasm uploads) + participant BReg as Build-info registry + participant V as Verifier (RV) + participant VC as Verification contract + participant IX as GoldSky indexer + API + + alt Trigger A — native SEP-58 metadata in wasm + Chain-->>V: wasm upload event (has build metadata) + else Trigger B — build-info registry (bridge) + Up->>BReg: submit build info for wasm_hash + BReg-->>V: build-info event + end + V->>V: build info well-formed? reproduce? + V->>VC: submit signed claim (result, image_trust, evidence_uri) + VC-->>IX: verification event + IX->>IX: materialize into queryable view +``` + +Authorization — who may register build info, who may submit claims, manager-key governance — is owned by Aha. The claim shape and event schemas are fixed in Milestone 1 so all parties build against a stable interface. + +--- + +## 4. Verifier engine (write side — Runtime Verification) + +A **control plane** plus **disposable sandbox workers**, deliberately separated across machines. + +```mermaid +flowchart TB + subgraph CP["Control plane (holds signing key)"] + Watch["Watch chain:
new wasms + build-info events"] + Queue["Work queue"] + Sign["Collect result → sign → submit claim on-chain + publish evidence"] + end + subgraph Workers["Sandbox workers (separate machine/s, no keys)"] + W1["hermetic docker rebuild
network-isolated"] + W2["..."] + Wn["..."] + end + Watch --> Queue --> Workers + Workers -->|result + computed hash| Sign +``` + +Key design choices: + +- **Sandboxes run on a different machine from the control plane.** The worker executes untrusted build logic (a contract's `build.rs` can do anything), so it must be isolated from the host and, critically, from the signing key. The worker returns only a result and a computed hash; it can never sign or submit. Hermetic, network-isolated rebuild is the defense against build-time exfiltration — not source scanning. +- **Elastic in the bootstrap phase.** During the initial back-verification crunch the engine fans out to many ephemeral workers to attempt thousands of candidate blobs (and, for metadata-absent blobs, multiple `version × flag × arch` combinations) in parallel. This is where most of the day-one coverage is produced. +- **Down to one isolated worker in steady state.** Once the corpus is processed, ongoing verification of new deployments needs only a single isolated worker. An operator who wants lower ops overhead can run the worker on the same machine as the control plane — an explicit security-for-simplicity tradeoff, not a default. +- **Image trust as a gradient.** The engine records `arbitrary → auditable → sdf_trusted` rather than a binary, anchored on the SDF-allowlisted trusted images. +- **All SEP-58 source modes**, with IPFS retrieval as a first-tier channel alongside HTTPS and content-addressed (`tarball_sha256`-only) builds. + +--- + +## 5. Indexer + Query API (read side — Aha, via GoldSky) + +The read side materializes chain events into queryable views. The reference implementation uses **GoldSky** as the materializer; because the views are derived from the event log, the materialization layer is replaceable without touching the contracts or the verifier. + +```mermaid +flowchart LR + Chain[(Stellar Ledger

build-info, wasm upload,
& verification events)] + subgraph Node["GoldSky indexer + Query API"] + Mat["Materialize events
+ fetch evidence_uri
+ verify signatures"] + Views[(Materialized views)] + Ends["Query endpoints
(trust policy applied HERE)"] + end + Cons["Explorers / wallets / CLI"] + Chain -->|events| Mat --> Views --> Ends --> Cons +``` + +**How it gets data.** GoldSky subscribes to the build-info and verification events emitted by the two contracts, as well as all wasm uploads with `img`/`src` info, and materializes it all into query-optimized views. For each verification event the pipeline can fetch the off-chain evidence by `evidence_uri` and verify the verifier signature. Because the source of truth is the event log, a view can be rebuilt by replaying history — there is no fragile mutable state to corrupt. + +**How it serves data.** Rich endpoints over the materialized views, shaped to conform to the forthcoming verifier-API SEP: + +- lookup by `contract_id` or `wasm_hash` → verification status, recorded SEP-58 fields, build metadata, image-trust signal, per-verifier history, and surfaced disagreement; +- list / filter / rank queries that on-chain RPC cannot serve — unverified-but-high-activity contracts, all mismatches, results filtered by image-trust level, history over time. + +**Variable trust at the endpoint.** Trust policy is a gradient, not a binary, which is tunable *here*, by consumers at query time. Never upstream. A request can specify its trust parameters in multiple ways: + + - **Trust Set**: specific verifier keys it honors ("all contracts trusted by Runtime Verification") + - **Named Policy**: `sdf_trusted`, say, to return all wasms/contracts trusted by SDF + +The API returns results that match that policy and surfaces divergence rather than collapsing it. Different endpoints can apply different rules to the same underlying facts. + +**Future work — alternative materializers.** The reference path is GoldSky. Because everything downstream is derived from chain events, an independent party could materialize the same events into a self-hosted store (e.g. a SQLite materializer) and serve the same API. This is proposed as future work to pursue if there is demand for fully self-hosted, GoldSky-independent query nodes; it is not required for launch. + +--- + +## 6. Trust, end to end + +Three distinct decisions, each made in exactly one place — none of them in the verifier or "in the contracts" as a verdict: + +- **Write admission (anti-spam) — at the contracts.** Authorization gates who may register build info and who may submit claims, governed by Aha. This is a spam/DoS floor, *not* a claim that an authorized verifier is correct. +- **What "verified" means — at the read layer.** Consumers pick a trust set of verifier keys at the API endpoint. Sybil-resistance is by curation, not by counting. +- **Disagreement — surfaced, never resolved.** Two claims on one `wasm_hash` with different results are shown per-verifier (`[✓] X`, `[!] Y`), with a summary for the common all-agree case. No staking, no slashing, no consensus — integrity comes from reproducibility, and any claim can be independently re-run. + +--- + +## 7. Back-verification & corpus (the differentiator) + +Verifying fresh, SEP-58-complete contracts is the bare minimum. What really differentiates this proposal is the effort into verifying the **existing deployed corpus**, most of which predates the standard. Because results key on `wasm_hash`, a small number of high-impact blobs cover a large share of activity. + +**Findings from mainnet deployment analysis.** The distribution is extremely concentrated, which is exactly what makes `wasm_hash`-keying powerful: + +- **100k+ active contracts** on Soroban mainnet. +- **~70% resolve to a single wasm hash** — the rain-crossmint smart-account/factory implementation. Reproducing that **one blob** covers ~70% of all active contracts in a single verification. +- The remaining ~30% map to **~3,600 distinct wasm hashes**. +- Of those 3,600, **970** carry both a `cliver` and a stable `rsver`, making them directly reproducible *if the source can be located*. + +So the corpus is really "one dominant blob + a few thousand long-tail hashes," not 100k independent problems — a handful of rebuilds reaches majority coverage on day one. + +**Activity-weighted ranking.** Before we try to dig through all 970 contracts, we will map on-chain *activity* of contracts to wasm hashes, so blobs are prioritized by real usage rather than raw count. A hash with heavy transaction volume matters more than a rarely used one. This ranking drives both the back-verification work order and the headline figure below. + +These feed the headline launch figure — **"verified [X]% of deployed contracts and [Y]% of on-chain activity at launch"** — finalized once the corpus pass and activity ranking complete. Schedule buffer belongs here, since the metadata-absent long tail is the one open-ended slice. Recovering build metadata for these existing contracts is Ethan's workstream. This analysis work has already started, but the deliverable will only be required for milestone 4 as it is the most open-ended research segment rather than pure engineering. + +--- + +## 8. Milestones + +Each milestone has a single lead responsible for driving it; the other parties contribute, but ownership is unambiguous. + +**Milestone 1 — Architecture & specs (lead: Ethan).** Architecture documents, SEP proposals (SEP-58 and the verifier-API SEP), and the high-level interoperability specification defining the formats and interfaces between the three parties. At least a spec the others can build against, evolved further with their feedback. + +**Milestone 2 — Verification engine (lead: Runtime Verification).** RV implements the verification side: the hermetic rebuild engine, signing, and claim submission, tested end-to-end. Aha provides **stub contracts** for the build-info trigger and claim write path (minimal — just enough to exercise the flow). Ethan guides the design where needed. + +**Milestone 3 — Contracts, indexer & query engine (lead: Aha).** Finalize the two contracts, build the GoldSky indexer and the query API. In parallel, ongoing recovery of existing contracts' build metadata and verification of the flow at scale. + +**Milestone 4 — Integrate & launch on mainnet (all three parties).** Connect every component end-to-end and launch on mainnet — the final goal. A significant corpus of existing contracts is recovered and uploaded; SEPs, RFCs, and the API spec are settled; protocols finalized. This milestone is shared: by this point the parties have built the trust and experience to deliver it together. + +--- + +## 9. Explicitly out of scope + +Producing the trusted Docker images (the verifier consumes SDF's); authoring SEP-55 (coordinate, not author); deterministic-Rust compilation as research (use best-available, anchored on trusted images); explorer UI work; republishing artifacts to IPFS (consume IPFS source and content-address it, no operated storage). + +--- + +## 10. To agree on (Milestone 1 detail) + +1. **Contract write interfaces** — the build-info submission shape and the `submit_verification` shape, including the `result` / `image_trust` enums. +2. **Event schemas** — the fields each event carries, so any materializer can derive the full view from chain history alone. +3. **Off-chain evidence format** — schema and content-addressing scheme behind `evidence_uri`. +4. **Authorization model** — who may register build info, who may submit claims, and the manager-key governance for recovering existing contracts. +5. **Query API trust surface** — named policies vs. a `trust_set` parameter, and the default policy for an un-parameterized request. +6. **Sequencing** — aligning the corpus-recovery work and contract-live dates against Aha's Registry mainnet timeline.