Contract Verification Registry API

[fnando]

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

Note

This SEP proposal it's meant to standardize only the consumer-facing response shape so tools like Lab, explorers and Stellar CLI can read any verifier's results. It should not constrain how teams build their service.

PR: #1944

It defines a read-only HTTP API for asking a verification service whether a smart contract's wasm has been reproduced from its source, and for reading the build and source metadata behind each result. A client looks a wasm up by its hash and receives the verifications one or more verifiers have recorded for it.

The proposal standardizes the API surface for the Contract Source Verification Service RFP. With a common interface, any verification service can implement the API and any client can consume verification results interchangeably, regardless of which service produced them.

It builds directly on SEP-58, reusing its build and source vocabulary verbatim — this SEP is a transport for SEP-58 results and adds no vocabulary of its own.

Feedback welcome on the API shape, the status object schema, and the error model.

[tupui]

Why do we not serve this information onchain instead?

We have here a perfect example of what a blockchain can be used for with all its guarantees in terms of availability, auditability and immutability. Hence I would define a smart contract API instead of a REST API. Of course one does not prevent the other, I would just encourage to not have the data itself in a private DB. Also if onchain that opens many possibilities with cross contract calls.

We can also define some metadata to be stored on IPFS alongside if we needed.

[tupui]

I think we should hold off here. There is an open RFP to do exactly this. Making a PR now with something is giving a constraint too early IMHO

https://stellar.gitbook.io/scf-handbook/scf-awards/build-award/rfp-track

[fnando]

The SEP only aims to draft the API structure, mostly focusing on the response. Implementation details is up to submissions.

Fwiw, we're already talking to people submitting proposals and it was mentioned that the API design would be SEP-based, and they were welcome to give feedback and help design the best solution possible. The problem is constrained in nature (exposing findings), so final solutions wouldn't deviate completely from the SEP proposal anyway.

It's worth mentioning the SEP doesn't talk anything about the verification process itself (infrascture, data persistance, etc); only attempts to normalize how they will be exposed to consumers.

[tupui]

FYI I am one of the RFP proposer and with Aha we are also making a proposal to address it (in collaboration with another team.)

The RFP is ambiguous on the term API. Here you assumed REST API and are already making design choices with verification semantics. In the delegate discussions I personally pushed that a SEP could/should be one of the deliverables and here as well we have some ambiguity on the verifier API SEP.

[fnando]

The REST API is our requirement because we want to simplify interfaces like the Lab. That said, it doesn't void any other response implementations, just documents the one we care about.

This SEP is up for discussion to avoid making the wrong assumptions. Help us think this through and we'll update it with something that works better. This is not set in stone.

[tupui]

As long as this does not get merged before the RFP itself quicks off I am personally fine.

Because in practice I don't thinks it's that easy to adjust a SEP even if still in draft and discussions tend to stop.

(I will try to make some feedback in case but I am writing this while on a leave. I was afraid of being too late to raise my voice if I did not do it now.)

[gchacon011]

Hello Tupui, Our team created this for this RPF : https://stellar-contract-verification.vercel.app/ Does this seem like a step in the right direction? We could really use your feedback.

[leighmcculloch]

Regarding out_of_band (reviewing 72ec853):

| out_of_band | boolean | (optional) When true, this verification was established outside SEP-58's reproducible-build mechanisms (e.g. a custom or non-allowlisted build image, or private source). The result is not independently reproducible from the recorded SEP-58 fields; consumers SHOULD weigh it accordingly. Absent or false means a standard reproducible SEP-58 verification. |

The out_of_band field is ambiguous. Being true can mean a variety of things that have significantly different implications. For example, custom build image vs meta field missing from the wasm.

Anything with that much ambiguity would be difficult to use well, so I think the field should be removed.

It leaves too open the definition of what is a verified contract. This in my opinion should be narrowly defined as:

A contract has been verified if the verifier has built its source into a Wasm file that when sha256 hashed matches the claimed hash.

If the plan is to use this API as a way to provide visibility into more than just build-style verification, then I think this API needs to provide separate fields that capture those details.

For example, a contract that has not been verified (reproduced), but does have an attestation could be:

{
    "verified": false,
    "attestation": {
        // details about the attestation here
    },
    //...
}

Conveniently verified contracts can also use attestation then and their attestation details can be surfaced here too.

[fnando]

My initial thought was to, later on, add build_verifications, which would specifically target SEP-55. I didn't want to mix both verification types for simplicity, even though I agree having the verifications[] result aggregated is way more elegant.

[fnando]

@leighmcculloch maybe out_of_band is not the best name, but I think we should have a field to identify this state. What if we focus only on signaling that the contract was verified outside of SEP-58's mechanism (audit, etc)? What name would work for this? Would out_of_band with a more explicit description work?

[leighmcculloch]

It's fuzzy to me what that state is. SEP-58 is about communicating the parameters to successfully build/rebuild the contract. Are you saying there's a state where a verifier says a contract is verified, but the verifier has not built the contract?

Do we need to design for this case right now? What's the use case? This can be designed for at a later date if the need arises.

[ethanfrey]

Supporting retroactive verification also means providing a way for contract developers to supply SEP-58 fields as they're not embedded in contract metadata: either as query parameters to the GET endpoint surfaced by this SEP (as GET requests don't support body) to support on-demand retroactive verification or by using another POST endpoint dedicated to retroactive verification submissions, but I believe this is out of scope for this SEP.

I think this is a key part of the RFP and I have spent several days researching validating existing deployed contracts. My idea is the SEP-58 fields need to be supplied to the verifier somehow. Either from embedded wasm metadata or supplied to the verifier request. In both cases, the verifier should record all those fields along with the verification result (and potentially sign it to provide an attestation). I think this SEP should handle that case.

As I understand, this only defines the query interface to view the verifications from potentially multiple verifiers. And a GET with wasm hash makes perfect sense. How you pass in the arguments is tied to triggering the job, which is a different endpoint. In my design, the API to trigger a verification (with needs these as arguments) is a different process than the API to view the verifications (this SEP).

[XxHugheadxX]

+1 with @ethanfrey on the retroactive verification
point — this is something we see constantly in
practice. Most contracts on testnet don't have
contractmetav0 embedded yet, so having a mechanism
to supply SEP-58 fields to the verifier is key
for real-world adoption.

In our implementation (CSV Verify) we handle this
by returning an explicit verification level: if
there's no embedded metadata, the result clearly
states it can't be verified and why. Separating
the trigger endpoint from the query endpoint —
as @ethanfrey suggests — is also exactly what
we do: POST /verify to trigger,
GET /v1/contracts/... to query.

[saimeunt]

@fnando Thanks for coming up with this SEP as a quick follow-up to how verifiers should surface verifications result, I don't see major concerns expect for the ones listed in my answer to @leighmcculloch

I have one question related to source code management, one of the use-case for explorers displaying verified contracts result is to display the verified source code in their UX, and I'm not sure where it fits in the current status object schema.

I think the verifier should be responsible for storing a copy of the source code provided for the rebuild as the SEP-58 source identification fields embedded in WASM (source_repo / source_rev & tarball_url / tarball_sha256) could become unreachable after verification (source_repo deleted, tarball_url returning 404, etc.)
Source code stored by the verifier can be stored as verified_source_tarball_url and shouldn't be confused with the SEP-58 field tarball_url stored in WASM metadata. While verified_source_tarball_url and tarball_url will hold different value, verified_source_tarball_url content must hash to the same value stored in tarball_sha256.

I'm not sure where this result should be surfaced, is it one of the URL that should be returned as part of results_url or is it a result that should be enforced and always returned as a top-level field of a "verified" status verification result?

[fnando]

I like the idea of having a field to indicate the source code that was used, not necessarily the one present on the wasm. verified_source_code_uri seems like a better name as it make it unambiguous.

Possible values could be:

https://example.com/archive.zip
ar://<address>
ftp://ftp.example.com/archive.zip
git+https://github.com/user/repo?rev=commit-hash
git+ssh://git@github.com/user/repo.git
svn+https://svn.example.com/repo?rev=1234

I think we can use vcs+url pattern to be to handle source_repo + source_rev in a single string.

[leighmcculloch]

Keeping all the information in a single field for how to get to the source will simplify a few things, even if it pushes some complexity onto clients.

Small note that it should be verified_source_code_url, l not i, because the intent is for the uri to be a location, not any type of identifier. Wdyt?

[ethanfrey]

I like the idea of the git urls with rev as argument.

Do clients need to support all of those? I mean does anyone use svn for Soroban development?

I would make a subset for what is actually used and force all clients to support those, and make future SEP to support more if really needed. It shouldn’t be open ended.

My vote would be to support:

https
git+https
git+ssh
ipfs

For https and ipfs, you also need to specify the format. Tarball with gzip encoding? Tarball with bzip2? Normal zip archive?

Verifiers will need to have software that can run all of them so it should be a clearly scoped set of formats.

[ethanfrey]

I wonder about making sure a clear spec upfront rather than allowing an open discussion with those who win the RFP. It seems like a critical design issue. I do agree that if multiple teams win the RFP, they should work with @fnando and the rest of stellar core team to define a consistent API. It just seems rushed to push the discussion into a few days as people prepare specs.

[fnando]

RFPs don't need to implement this API from day 1. We just want to get the conversation started so we think things through.

[tupui]

Putting my hat of RFP delegate. The team(s) selected to engage on this RFP is expected to interact with the community and SDF very closely throughout the years. I say years here as there is a strong expectation on maintainability and sustainability of what is developed. This is a valid remark for all RFPs. RFPs as it stands are similar to public goods: we want to build dependable infrastructure.

I said earlier I do think it's too early to have a PR up as we must all brainstorm together and that can only come from a clean slate. We are also breaking the process here as the PR for a SEP should only be proposed after a discussion period.

[fnando]

The PR can be be used for brainstorming. Don't like something? Make a suggestion, and if it fits, we can change. Case in point, https://github.com/orgs/stellar/discussions/1945#discussioncomment-17218331.

[tupui]

@fnando Part of the funding that teams are requesting is to dedicate proper working time to work on this topic. This is important because we, the delegates and SDF who green lighted the project, want to get the input from skilled teams. Most people only have a few hours there and there to dedicate to open source and volunteering work. Here it's about security and the topic is important enough considering the current supply chain context that we do things right.

If there is a reason to shortcut the process (which we are doing as per the instructions on how to raise a SEP), please raise this internally so that we are made aware of it on the delegate side.

In general, it would be good if you were to join the discussions we have with delegates on RFP. You would bring valuable input and perspective to the table.

[ethanfrey]

I also want to note that many decisions need to go hand-in-hand with some implementation and real-world testing before they are finalized.

I just submitted stellar/stellar-cli-docker#23 which brings up a very non-obvious issue that only shows up when I am trying to build docker images to verify existing mainnet contracts.

I think this is a very important conversation to have and should definitely have multiple parties with time involved in it (stellar core devs, anyone working on the contract verification RFP, and teams working on explorers)

[ethanfrey]

One example where I think we need more discussion is my comment here: https://github.com/orgs/stellar/discussions/1923#discussioncomment-17190066

I really think we need to define either package or manifest path as a separate field, same visibility as source_repo rather than some buildopt. Also, ideally standardizing. I explain better on the linked comment, but that would affect this API as well as SEP-058

[ethanfrey]

For the multiple verifiers example, it seems hard to trust. If server A says they verified the source, then the trust is on them. If server A says validator B verified the source, I am trusting server A and get no more security from the verification from B (as it is only based on this server A say so)

To securely surface multiple verifiers, you need cryptographically signed attestations. Those can be handled off-chain but validated to a signature registered on chain, or they can be tied to an on chain transaction signed by a given verifier identity.

I think this would be great to support in a real API that exposes multiple verifiers and is a much larger design surface than a simple JSON schema. I would love to have a longer conversation on this and can share two alternatives here I am considering.

[fnando]

Given this seems to address the aggregation aspect of the proposal, I've decided to withdraw that use case for now. We can amend the initial proposal or draft a new one if we come to the conclusion that this is indeed required.

[jia57b]

Thanks for the draft SEP. I agree with the direction of keeping the base API small and keyed by wasm hash.

From an implementation and downstream UI perspective, there are a few areas where more structure, or at least future-compatible extension points, would help:

1. Aggregator transparency
   For an aggregator response, it would be useful to distinguish “this verifier returned unverified” from “this verifier could not be reached / timed out / returned an invalid schema”. A consumer UI should not treat those the same. An aggregator shape would benefit from something like queried_verifiers and failed_verifiers or equivalent metadata.

2. unverified reason
   The unverified could cover different reasons, such as pending, source unavailable, unsupported build environment, policy rejection, build failure, and other cases. For UI and troubleshooting, an optional machine-readable reason or detail_status would be useful while keeping status as verified | mismatched | unverified.

3. Out-of-band semantics
   The current out_of_band boolean seems to cover several different concepts: private source, custom/non-allowlisted image, trusted attestation, manual/internal checks, etc. These have different trust implications. It may be better to split this into more explicit fields, such as verification method, source visibility, and reproducibility level, instead of one boolean.

4. Source visibility and long-term viewability
   The SEP-58 source fields identify the source, but they do not always tell a UI whether the source is publicly viewable. A private/hash-only source, a deleted repo, and a temporarily unavailable tarball should not be displayed the same way. An optional source_visibility or source reference type could help consumers explain what users can and cannot inspect.

5. Evidence artifact references
   results_urls is useful as an escape hatch, but as an opaque URI list it does not tell clients what each URL points to or how to verify the referenced artifact. It may be worth allowing structured evidence references with fields such as url, sha256, type/purpose, and possibly archive references. This would still leave the full artifact format implementation-specific.

6. Future trust signals
   If SEP-55 attestations or build-image trust are added later, I think they should be represented as distinct trust signals or sibling result groups rather than folded into source-code rebuild status. A SEP-58 rebuild match, a SEP-55 attestation, and “rebuilt with an SDF-trusted image” are related but separate claims.

[leighmcculloch]

1. For an aggregator response, it would be useful to distinguish “this verifier returned unverified” from “this verifier could not be reached / timed out / returned an invalid schema”. A consumer UI should not treat those the same. An aggregator shape would benefit from something like queried_verifiers and failed_verifiers or equivalent metadata.

These are some great points, and a hint that an aggregator API should be a separate API with an real test case to validate. It'd keep this API simpler if it's hyper-focused on a single verifier, and a narrow clear definition of what it means to be verified: the contract has been built by the verifier and arrived at the same binary hash.

[saimeunt]

I agree the aggregator API could be scoped out of this SEP and we should only focus on the single verifier path, while keeping in mind that a verifier results should be easy to aggregate, eg. by providing a single top-level verifications array in the status object with a status field to differentiate all different types of verifications (by source from SEP-58 fields, by attestation from SEP-55 fields, by source from fields supplied directly to the verifier, by source not publicly accessible, etc.)

The aggregator API should be responsible for maintaining a list of trusted verifiers queried against and can optionally filter in/out some results it's not interested in (eg. discard verifications not strictly adhering to SEP-58 verifiable builds).
The aggregator API could be run by an authoritative entity such as the SDF (at the expense of centralization) or each explorer could run their own aggregator API with their own list of trusted verifiers to enable further decentralization.

[fnando]

I'll update the pr, removing the aggregation aspect. If we come to the conclusion that something like this is required, then we can draft a separate SEP or amend the initial one.

Would it still be useful to keep verification as a list? I don't see a reason for it, now.

[fnando]

@jia57b thanks for you comment!

My deliberate stance is that this endpoint answers one narrow question: is this wasm reproduced from its source, by whom, with what verdict. The richer, verifier-specific detail lives on the verifier's own service, reachable from a report link. The shape also evolves additively (new optional fields, new sibling arrays, open enumerations), so deferring detail now costs nothing later. That "no breaking change required to add it" property is the spine of most of what follows.

2. unverified reason

I'm keeping status as verified | mismatched | unverified with no reason field for now. A machine-readable reason is genuinely useful for an integration audience ("why did this fail on verifier X?"), but that's not this endpoint's job. And that audience is exactly who follows the report link to the verifier's own service. For a display UI, the contract is unverified either way, and a help text can enumerate the common reasons (pending, source unavailable, unsupported build environment, policy rejection, build failure, etc.). If real demand shows up, an optional reason is additive and non-breaking, so nothing is lost by waiting.

3. Out of band semantics

I'd keep this a single boolean. From the consumer's standpoint the cases collapse to one relevant bit: can I independently recheck this from the recorded SEP-58 fields, or not? Splitting it into method × source-visibility × reproducibility multiplies the combinations a verdict-display UI has to reason about, for detail that belongs on the verifier's page.

4. Source visibility and long-term viewability

I'm not convinced distinguishing these states is useful. "Source unavailable" already subsumes "private source" from the consumer's standpoint: in both, you can't inspect it here. The distinction is explanatory, not verdict-changing, so it belongs in help text and the verifier's report; not having the source available is evidence enough for lack of verification.

A consumer that wants to confirm also gets the answer for free: it already has source_repo / tarball_url and learns "private / deleted / down" by trying to resolve them.

5. Evidence artifact references

I like the sha256 addition. What would be the possible types that must be documented by the SEP? Covering all cases is not feasible. Some examples:

• report: a web-redable url
• other: open purpose

{
  "result_urls": [
    {"type": "report", "url": "https://verify.example.com/stellar/<hash>"},
    {
      "type": "provenance",
      "url": "https://verify.example.com/wasms/cb2fc3a1/provenance.intoto.jsonl",
      "sha256": "1f2e3d4c5b6a79887766554433221100ffeeddccbbaa99887766554433221100"
    },
    {
      "type": "attestation",
      "url": "ar://AbCdEf0123456789AbCdEf0123456789AbCdEf0123456789ABC"
    },
    {
      "type": "sbom",
      "url": "https://verify.example.com/wasms/cb2fc3a1/sbom.spdx.json",
      "sha256": "0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9"
    },
    {
      "type": "audit",
      "url": "https://audits.example.com/my-contract-2026-05.pdf",
      "sha256": "778899aabbccddeeff00112233445566778899aabbccddeeff001122334455667"
    }
  ]
}

6. Future trust signals

Fully agree, and that's precisely why results live under a named source_code_verifications array rather than flattened onto the wasm. A SEP-55 attestation claim is a separate claim, so it arrives later as a sibling array (e.g. build_verifications); additive, no rename or move of any SEP-58 field, no break for existing consumers.

---

More broadly: verifiers should enrich their verifications with as much data as possible, and surface that on their own service. The report entry is the intended link from a consumer back to that fuller record.

[XxHugheadxX]

Hey, chiming in as an implementer — we've been
building CSV Verify against this API shape for
the past few weeks and have it running on testnet.

On the on-chain question: we thought about this
early on. The problem is latency. A contract
verification involves cloning a repo, running a
Docker build, and comparing hashes — that's
2–6 minutes of compute. Putting that result
on-chain makes sense for permanence, but you
still need an off-chain service to produce the
result in the first place. The REST API is what
bridges the gap between the verification compute
layer and the consumers (explorers, wallets, Lab).

On the timing concern: from where we sit, having
this API shape defined early actually helped.
We aligned our GET /v1/contracts/{id}/verifications
and GET /wasms/:hash.json endpoints to the draft
in #1944 before our MVP was complete. That meant
when fnando reviewed our approach, there was
already a shared vocabulary. Without the SEP
draft, every implementer would ship a different
response shape and clients would have to support
N integrations instead of one.

The SEP not touching the verification process
itself (infrastructure, persistence, how the
rebuild happens) is exactly right in our view.
That's where implementations should compete —
on reliability, speed, and coverage. Not on
what the JSON looks like.

Happy to share more on what we've learned
implementing this end-to-end.

[fnando]

Thank you! That's valuable feedback.

[orbitlens]

Since all verification efforts gradually converged into a fully centralized service with an API, I think this service itself should be an ultimate source of truth. So from my point of view, the verifier field can be present in the response, but it provides zero information to end users, and might even be harmful (in a sense that it can provide a false feeling of security).
We are planning to integrate this API into StellarExpert once we understand that we have a reliable registry provider, but we are not going to display any verifier details. If we pull the data from, say, https://api.verifier-registry.com, then we'll be displaying something like "Contract source: <github.com/repo> verified by api.verifier-registry.com". Therefore, if users lose their funds and come to us asking why we marked the contract source as verified, we'll point to the "verifier-registry.com" as an ultimate centralized service responsible for the verification, not to some random verifier that I never met.

To me the whole idea of verifying source code tarballs without publishing the source code itself looks absolutely bizarre. I also have some other security concerns that I shared in other threads. Since SEP standards allow this, there should be a clear responsible business entity that might be investigated by law enforcement agencies at some point. It's probably not a very pleasant part of this conversation, but as someone who had to talk to officers from a dozen countries and provide information regarding dozens of criminal cases (this automatically comes as a bonus with StellarExpert), I'm very cautious about any claims in our user interface. Based on this logic, the verification registry provider should either employ its own team to verify all smart contracts (regardless automatically or manually) or fully trust a verifier, taking risks on their behalf.

One technical request from our side: please add a bulk-load API endpoint for verification results to this SEP. It would allow third-party apps to pull the data from the verifier service without bombarding it with hundreds of requests to /wasms/:wasm_hash every second. We need to store verification metadata on our side (it is required for proper contracts scoring on sorting), other API consumers might find it also useful.

Proposed format: GET /wasms.json
Query parameters:

• order (asc|desc) - sorting order (sorted by the verification timestamp)
• limit (1-200) - page size
• cursor(string) - paging cursor

The results should be sorted by the verification timestamp (updated_at field in the SEP notation). Since there is a chance of a collision (two verifications with identical timestamps), the cursor can be formatted like {timestamp}-{wasm_hash} (e.g. 1783908375971-cb2fc3a1b4d5e6f7081928374655647382910abcdef0123456789abcdef01234) – this will ensure that all verification updates can be processed sequentially without loosing any records on timestamp collision.

It’s a scalable approach that will allow API consumers to load all data retrospectively and monitor updates by periodically pulling this endpoint. It also guarantees that downstream systems will not end up using stale data (for example, if any verification record gets discarded/removed from the registry later on after the review).

[fnando]

Hey @orbitlens!

Thanks for your feedback.

To me the whole idea of verifying source code tarballs without publishing the source code itself looks absolutely bizarre

I'm with you on that but, unfortunately, some partners won't release the source code. Even SDF personnel had a hard time being onboarded and getting access to source code, having to go through NDAs, clearance, etc.

please add a bulk-load API endpoint for verification results to this SEP

I'll update the draft with this.

[tupui]

I think Orbitles meant more that having a service claiming to have "verified source" without having access is strange.

Good points on the compliance part and the wording there 👍 Probably we could make some recommendations regarding TOS and service provided to help there. If we could get some help from legal folks at SDF that would be very helpful I think.

[fnando]

@tupui That's exactly what I read. I gave an example on how having access to source code can be a problem even for SDF personnel, and how we need to support it anyway.