Contract Verification Results (draft SEP)

[jia57b]

This thread is to discuss a new draft SEP: Contract Verification Results.

Draft: https://github.com/jia57b/stellar-protocol/blob/sep-contract-verification-results/ecosystem/sep-contract-verification-results.md
PR: #2038

Note

This standardises only what a verifier publishes and the read routes that serve it, so Lab, explorers, wallets and the Stellar CLI can read any verifier's results with one reader. It does not constrain how a verifier performs a verification or who may request one.

It builds on the Contract Verification Registry API draft by @fnando (#1944) and the discussion in #1945, and carries SEP-58's build vocabulary unchanged. A companion proposal, Contract Verification Aggregation, covers combining several verifiers into one view, in its own thread: https://github.com/orgs/stellar/discussions/2039 (PR #2040).

In one paragraph. A verifier publishes static JSON under a result root, and the root's URL is its identity. wasms/{wasm_hash}.json is a stellar-verification-status document: the verdict (verified, mismatched or unverified), the SEP-58 recipe that produced it, where the recipe came from (recipe_source), how far the build image can be trusted (image_trust_level), and hash-anchored links to the report and its archive copies. GET /v1/wasms/{hash}.json serves the same bytes and adds 202 while a verification is in flight. GET /v1/wasms streams the corpus for indexers. Every non-2xx response uses one error envelope.

Decisions worth challenging

1. No signatures in 1.0. The result can be re-run (recipe and source hash are published), and sha256 on every results_urls entry gives offline integrity for mirrored reports. A signature would mostly re-assert what TLS to the result root already gives. Is there a threat this misses?
2. A verified result is not displaced by a later mismatch for different source (§3.4 row 3). It stops third parties from defacing a verified contract by submitting source that does not build.
3. The identity is the result-root URL, with a stated normalisation rule (§2). name is display only.
4. Consumers must tolerate unknown vocabulary values in every enum-like field (§7), not only status.
5. Off-chain, read-only HTTP. On @tupui's question in Contract Verification Registry API #1945: this does not rule out an on-chain registry. It defines the document such a registry, or an explorer, would point at. Is anything here hostile to an on-chain anchor later?

Out of scope (deliberately): submission, aggregation across verifiers (the companion proposal), signatures, verifier internals.

Implementation. The proposal is implemented, and every example body in the draft is one that implementation emits. Its source will be published once an external security audit completes.

Feedback from anyone who would consume this (Lab, StellarExpert, StellarChain, CLI, wallets) is especially useful: does one reader per this shape cover what you need to display?