Architecture & roadmap doc (docs/ARCHITECTURE.md) for the contract source verification service

README.md

@@ -12,9 +12,11 @@ is byte-for-byte the published source — by independently **re-compiling** the
 source on neutral infrastructure and comparing hashes, not by trusting a build
 provenance attestation.
 
-This is the SCF RFP **MVP tranche**: a single pinned toolchain, a chain reader,
-and a verify-by-contract-ID CLI. Registry API + UI, multi-toolchain selection,
-and explorer badge integration are later tranches (see [Roadmap](#roadmap)).
+This repo is the working MVP of the service: a single pinned toolchain, a
+chain reader, and a verify-by-contract-ID CLI. The full design — the hosted
+multi-verifier service, `/v1` public API, UI, multi-toolchain selection, and
+explorer integrations — is specified in
+**[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** (see [Roadmap](#roadmap)).
 
 License: **Apache-2.0**.
 
@@ -31,14 +33,16 @@ So source verification reduces to one question:
 > **Can we rebuild a candidate source repo into a WASM whose SHA-256 equals the
 > hash the ledger reports for this contract?**
 
-Today's tooling (stellar.expert's build workflow, the in-progress Contract Source
-Validation SEP — [SEP-0055], formalized from [discussion #1573]) relies on GitHub
-Attestations, which only attest that *a GitHub Action ran and produced a WASM*.
-The official Stellar Lab Contract Explorer is explicit that its "Build Verified"
-badge "only means that the GitHub Action run has attested to have built the Wasm,
-but does not verify the source code." Soroscan Verify adds the **independent,
-neutral, reproducible-build** layer those approaches lack — the Soroban analogue
-of [Sourcify]'s bytecode-match model for Ethereum (full match vs. partial match).
+Today's tooling (stellar.expert's build workflow, the Contract Build
+Verification SEP — [SEP-0055], formalized from [discussion #1573]) relies on
+GitHub Attestations, which attest that *a GitHub Action ran and produced a
+WASM*. The official Stellar Lab Contract Explorer is explicit that its "Build
+Verified" badge "only means that the GitHub Action run has attested to have
+built the Wasm, but does not verify the source code." Soroscan Verify adds the
+complementary **independent, neutral, reproducible-build** layer ([SEP-0058])
+— the Soroban analogue of [Sourcify]'s bytecode-match model for Ethereum (full
+match vs. partial match). SEP-55 answers "did trusted CI build this?"; the
+rebuild layer answers "does this source produce these bytes?".
 
 ## Architecture (data flow)
 
@@ -49,27 +53,28 @@ The diagram uses the SDK method names as they actually exist on
 
 ```mermaid
 flowchart TD
-    Dev[Developer / Auditor] -->|contract ID or wasm hash + source repo| UI[Verification UI - React/Next - later tranche]
-    UI -->|POST /verify - later tranche| API[Registry API - TypeScript - later tranche]
-    API -->|enqueue job| Q[Build Queue - later tranche]
+    Dev[Developer / Auditor] -->|contract ID or wasm hash + source repo| UI[Verification UI - React/Next - roadmap]
+    UI -->|POST /v1/verifications - roadmap| API[Public API - /v1 - roadmap]
+    API -->|enqueue job| Q[Build Queue - roadmap]
     API -->|fetch on-chain wasm| Reader[Chain Reader - stellar-sdk RPC - MVP]
     Reader -->|getContractWasmByContractId / getContractWasmByHash| RPC[(Stellar RPC - ContractCodeEntry - SHA-256 hash)]
-    Reader -->|SEP-46 contractmetav0 - rsver rssdkver source_repo| API
+    Reader -->|SEP-46 contractmetav0 - SEP-58 bldimg bldopt source_repo source_rev| API
     Q --> Worker[Reproducible Build Worker - pinned Docker - MVP]
     Worker -->|pull pinned image by digest| Docker[(Docker image - toolchain - MVP)]
-    Worker -->|clone repo@commit or local source| Git[(Source - GitHub/GitLab/tarball)]
+    Worker -->|clone repo@commit or local source| Git[(Source - repo / tarball / content-addressed)]
     Worker -->|stellar contract build --locked - target wasm32v1-none| WASM[Rebuilt WASM + SHA-256 - MVP]
     WASM -->|compare hash and section diff| Match{Match verdict - MVP}
-    Match -->|full / metadata-only / none| DB[(Postgres - verdict repo commit - later tranche)]
-    DB -->|mirror artifacts| IPFS[(IPFS pin - later tranche)]
-    DB --> Badge[Badge endpoint - GET /badge/id.svg - later tranche]
-    Badge --> Explorer[Soroban-First Block Explorer + Stellar Lab Contract Explorer - later tranche]
-    DB --> Query[GET /verification/wasmHash - GET /contract/id - later tranche]
+    Match -->|full / metadata-only / none| DB[(Verification registry - ed25519-signed results - roadmap)]
+    DB -->|mirror artifacts| IPFS[(IPFS pin - roadmap)]
+    DB --> Badge[Badge endpoint - GET /v1/badge/id.svg - roadmap]
+    Badge --> Explorer[Explorers - Stellar Expert / Stellar Lab Contract Explorer - roadmap]
+    DB --> Query[GET /v1/wasm/hash - GET /v1/contract/id - roadmap]
     Query --> UI
 ```
 
 Pieces labeled **MVP** are implemented and tested in this repo. Pieces labeled
-**later tranche** are scoped but not built here.
+**roadmap** are specified in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) but
+not built here.
 
 ## Stack (plain English)
 
@@ -200,11 +205,17 @@ test/integration.testnet.test.ts`.
 
 ## Roadmap
 
-| Tranche | Scope |
-|---------|-------|
+The full roadmap is in [docs/ARCHITECTURE.md §11](docs/ARCHITECTURE.md); in
+summary:
+
+| Phase | Scope |
+|-------|-------|
 | **MVP (this repo)** | Single pinned toolchain, chain reader, verify-by-ID CLI, deterministic hash-match proof on testnet. |
-| Testnet | Registry API (`POST /verify`, `GET /contract/{id}`, `GET /verification/{wasmHash}`, `GET /badge/{id}.svg`), React/Next UI with diff viewer, multi-toolchain selection via SEP-46 `contractmetav0`, IPFS mirroring. |
-| Mainnet | Production hardening, explorer badge integration (Soroban-First Block Explorer; Stellar Lab Contract Explorer fallback), docs + maintenance plan. |
+| 1 — Self-hostable verifier core | ed25519 result signing, image allowlist + trust tiers, all three SEP-58 source modes, IPFS retrieval, sandboxed rebuild workers. |
+| 2 — Audit + hosted deployment | Independent security audit; public **testnet + mainnet** deployment; retroactive (off-chain metadata) submission path. |
+| 3 — Stable `/v1` API + SDK + docs | `GET /v1/contract/{id}`, `GET /v1/wasm/{hash}`, `POST /v1/verifications`, `GET /v1/verifiers`; client SDK; allowlist policy doc; under-15-minute walkthrough. |
+| 4 — Integrations | Badge endpoint (`GET /v1/badge/{id}.svg`), explorer embed, stellar-cli interaction, partner reference integration. |
+| 5 — Production operations | Runbook, monitoring, on-call, peer-operator support. |
 
 ## References
 
@@ -213,12 +224,14 @@ test/integration.testnet.test.ts`.
 - Retrieve a contract code ledger entry (LedgerKeyContractCode / getLedgerEntries)
 - `@stellar/stellar-sdk` `rpc.Server` API reference (method names)
 - [SEP-0046] Contract Meta (`contractmetav0` / SCMetaEntry)
-- [SEP-0055] Contract Source Validation (formalized; alongside [discussion #1573])
+- [SEP-0055] Contract Build Verification (GitHub-Attestation provenance; alongside [discussion #1573])
+- [SEP-0058] Contract Build Reproducibility for Verification (`bldimg`, `bldopt`, `source_repo`, `source_rev`, `tarball_url`, `tarball_sha256`)
 - [Sourcify] — Ethereum source verification (full vs partial match) prior art
 - OpenZeppelin `stellar-contracts` (Rust Soroban library)
-- SCF Build Award handbook (tranche model: 10% award / 20% MVP / 30% Testnet / 40% mainnet+UX)
+- Service design & roadmap: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 
 [SEP-0046]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0046.md
 [SEP-0055]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0055.md
+[SEP-0058]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0058.md
 [discussion #1573]: https://github.com/orgs/stellar/discussions/1573
 [Sourcify]: https://github.com/ethereum/sourcify

docker/toolchain-manifest.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Pinned toolchain manifest for the MVP single-toolchain reproducible-build image. The on-chain WASM hash is reproducible only against THIS exact toolchain. For the Testnet tranche, image selection becomes automatic via SEP-46 contractmetav0 keys (rsver, rssdkver).",
+  "$comment": "Pinned toolchain manifest for the MVP single-toolchain reproducible-build image. The on-chain WASM hash is reproducible only against THIS exact toolchain. In the full service (docs/ARCHITECTURE.md), image selection is driven by the SEP-58 bldimg digest recorded in contractmetav0 or submitted off-chain.",
   "image": "soroscan-verify-builder:rust-1.91.1-cli-26.1.0",
   "baseImage": "rust:1.91.1-bookworm",
   "baseImageDigest": "TODO: pin via `docker buildx imagetools inspect rust:1.91.1-bookworm` and record the sha256 here",