Add SEP: Contract Verification Attestations

[ethanfrey]

Discussion around proposed SEP for contract verification attestations

I propose a new SEP (Draft), defining a normalized build claim, a cheap signed verification result over that claim, and a content-addressing convention for the claims, source archives, and wasm bytes involved in verifying a Soroban contract.

The SEP adds three layers on top of the build-environment vocabulary in SEP-0058:

• Build claim: a canonical XDR structure over the build-environment fields, source hash, and claimed wasm hash, whose SHA-256 is a stable identifier any verifier can recompute.
• Content addressing: wasm, source archive, and claim are each named by the SHA-256 of their canonical bytes (the wasm address being the digest the ledger and RPC already use); URLs are demoted to retrieval hints.
• Signed verification: a small record binding a claim hash to a result (match / no-match / did-not-run) and a verifier identity, signed with a Stellar key and published either out of band or via a registry contract call.

It also specifies how a verifier reconstructs a claim from a wasm's embedded meta and re-embeds that meta byte-for-byte on rebuild.

Rendered markdown of the proposed SEP

Why

SEP-0058 makes a build reproducible, but says nothing about what a verifier does with the result. Two honest verifiers have no shared identifier for "the same build", no cheap way to publish a result others can trust selectively, and no integrity guarantee on the source bytes a recorded URL points at.

This SEP closes those gaps and is complementary to SEP-55 (CI attestations) and SEP-0058 (rebuild vocabulary): a contract can carry meta supporting all three, and consumers pick whichever verification path fits their threat model.

[ethanfrey]

@leighmcculloch and @fnando I would love your feedback here, as it is an addition to your excellent work around SEP-58.

I want to make clearly reproducible claims and attestations that can be gossiped and aggregated securely.

[ethanfrey]

Any comments here? This is actually important design for a build registry system to limit on-chain data and I'd love some feedback here - even if just asking about motivations.

I am convinced we will need lots of build info available to reproduce existing contracts and a small on-chain anchor seems the best way to distribute this. However, to avoid bloat and keep TTL payments low, I would like to only push a hash, not the full JSON SEP-58 definition (which is easily over 500 bytes each time).

Also, it would be great to be able to have a standard for cryptographic signatures from different validators to view who attested to what. I think that is as important a stable API definition to query - as the different verifiers must be able to safely share and gossip their attestations in a provable way.

Or at least that is my idea of a properly decentralized solution. And if we don't really care about that, why not just stellar.expert storing it in their database, much simpler.

[chadoh]

Are you allowed to make a draft PR with your SEP so I can comment on individual lines there instead of copying and pasting them here? Assuming you cannot for now, so here I go:

two honest verifiers with the same inputs have no agreed-upon way to refer to "the same build."

Why not the wasm hash?

[chadoh]

Union the build-environment fields with any supplied externally (registry, verification service, or out-of-band)

is this why? Because the on-chain wasm hash (the claimed wasm hash) might not contain all relevant build info?

[ethanfrey]

Yes, this handles the case where all build info is not in the wasm hash itself (all existing contracts) as well as the case where the contract contains properly embedded SEP-58 build information. The final build claim is the union of the embedded data with externally supplied fields - the exact fields used to reproduce regardless of whether they came from the wasm or externally. Or most from the wasm, but one addition externally, etc.

I cover the union steps here in constructing the build claim. Happy for feedback on how to improve the process or make it more clear

[chadoh]

the fields point at retrieval channels (source_repo, tarball_url) whose contents can drift even when a commit SHA or tarball hash is recorded. URLs change, hosts disappear, and a git ref can be force-pushed.

I know that SHA128 is "broken", but is this really true? If the SEP requires use of a git SHA, is it really as unreliable as using a git REF? I have no idea how to force push and keep the SHA unchanged.

[ethanfrey]

This PR may be a bit outdated. #1954 merged and insists on sha256 of an archive. So no git ref or such.

[chadoh]

Would car files be potentially useful for the source hash? I know that this exists, but have no experience using it.

[ethanfrey]

Again, I think we should just build on #1954 this is an orthogonal concern to attestations and I will reduce the scope of this PR to only focus on a format for the build information and the signature over it.

[chadoh]

I meant for the "more research/input needed" part on how to bundle the source into a predictable state for the sake of reproducible source hashes

[chadoh]

A well-considered SEP that will make our source verification work much more straightforward. Thank you!

This restricts what verifiers can communicate about a given verification run quite severely. Especially in the VERIFICATION_DID_NOT_RUN case, I imagine it being useful to have a URL where I can visit the verifier's detail page about what they tried to do for this specific verification. I picture this looking similar to a CI info page, like a GitHub action.

That's just one example that I can think of, but it's possible that verifiers might want to include other information about a verification. Is this all outside of this SEP? Would it be worth including some mention of this?

For the CI workflow page, I could envision verifiers settling on a URL structure that embeds the claim hash.

[ethanfrey]

Good point. One issue is having arbitrary strings makes it hard for computers to determine the contents. Having concrete cases is important. That said, I do see the use of having a URL for human-readable details for debugging, which shouldn't impact how any client handles it. They just mention "didn't run" and can display debug info if requested.

I will adjust.