Contract Source Verification using Docker without Attestation

[leighmcculloch]

Context: Existing standards and previous discussions about contract build and source verification:

• Contract Source Validation SEP #1573
• SEP-55 Contract Build Verification with Attestation
• Contract Source Verification after Deployment without Attestation #1802

👋🏻 Conversations have arisen from time to time about finding a method for verifying contracts without having completed attestation. A previous discussion and experiment (#1802) was much along those lines. This thread is to discuss the possibility of using Docker / Containers like other blockchains do.

Below is a rough prototype introducing docker into the stellar contract build command so that by when building contracts they are reproducible, and a stellar contract build verify command that can replay a build with an identical environment as the original to reproduce an exact binary. It's intended to be complementary to the existing build verification process defined in SEP-55.

The implementation is here: stellar/stellar-cli#2525. It is a wip under active development and may change significantly.

You can try it out with:

cargo install --locked --git https://github.com/stellar/stellar-cli --branch feat/reproducible-builds-via-docker

Then build your contract:

stellar contract build --backend docker

Then verify the build:

stellar contract build verify --wasm contract.wasm

The tl;dr is the stellar contract build kicks off the stellar/stellar-cli docker image and writes enough meta to reproduce it in the same environment with the same tools. During stellar contract build verify that meta is used to replicate the original build environment.

The cornerstone is the meta which is captured in this very rough draft spec: draft-specification.md

There's a contract wasm on mainnet that used the build process and passes with the verify process:
e7089d989d23d43e03b169b5be9649bc4f67c67685b8bc042da0adac21a4eb08 (meta.json)

As an example of how verification could run, I've created a repo with a ci workflow that gets all mainnet contracts and attempts to verify them all on a schedule, and you can see the contract wasm above is verifiable:
e7089d989d23d43e03b169b5be9649bc4f67c67685b8bc042da0adac21a4eb08.json (GitHub Actions Run)

I'm sharing all of the above while it is still very raw, rough, and not particularly polished. But, I wanted to share this early to get early feedback. Other than general feedback, I'm specifically interested in what people think about the meta that gets stored.

[tupui]

Great complement to SEP-55 👍 Random stuff:

On --backend, do you have plans for more backends? E.g. podman or container. That might be worth generalising the naming. (I tried container, the macOS one, a while ago and could run the Quickstart image.) In general it would be nice to not have to pick Docker.

Do we keep the attestation generation outside of this? Would make sense if we look at the Build L2 from SLSA I guess. Still would be nice to consider being able from the CLI to check a wasm with an attestation. Tangentially, do we care at all about SBOM for building WASM. Attestations and SBOM go together usually.

[fnando]

I just used podman and it worked (notice that I have Docker Compatibility enabled). Supporting podman may be just a matter of searching the proper sock path.

[tupui]

yeah pretty sure it's just a matter of allowing users to use the tool they want with a config and that should be it.

[leighmcculloch]

It's named docker for familiarity, but it's really just general container support and doesn't use any docker specific functionality.

[fnando]

With this proposal, why should we care about SEP-55? I understand they have different goals, but what we always wanted was Source Verification to begin with. I think Source Verification should deprecate Build Verification for new contracts, but Lab and explorers can (are recommended to) support Build Verification status as a fallback.

[tupui]

These are the pilar of SLSA https://slsa.dev we are not giving the same information and guarantees with source verification and build verification.

[tupui]

To clarify a bit, with this SEP you would only be proving that you have the same wasm. There is no provenance information nor guarantee. To me that puts you at most at a L1 level on the Build track of SLSA. Now if you combine this and SEP-55, you can claim L2 and why not L3 though that needs a bit more attention (things you can guard if you craft correctly an action, e.g. caching poisoning.)

[mootz12]

I agree we should keep supporting attestations for contracts. If we need to make SEP-55 look a little different once this is closer to finalized, I'd prefer that over deprecating it.

[orbitlens]

Agree, this SEP should be either merged with SEP55 or substitute it.

[tupui]

Sharing this here, an recent audit on some Python packages which involved an audit of their compliance with SLSA. P56

I think that's informative to see in practice concrete examples of bad (Request) and good (urllib3) implementation of the standards.

https://7asecurity.com/reports/pentest-report-requests-urllib3-cachecontrol-RC1.3.pdf

[mootz12]

Thanks for opening this discussion! I think this is a necessary step towards getting repeatable/verifiable contract builds. Left comments on the CLI PR, but overall agree with the direction.

[mootz12]

Question - is it worth considering adding some form of signed message from a reported build account so the metadata reported here is verified by at least some public key?

This could be optional, but might allow a company to attest that they in fact generated this metadata.

e.g.:

bld_pubkey: GABC...
bld_sig: 0xabc...

Where bld_sig is a signature of all the meta_entries, excluding itself and bld_pubkey or something.

This pubkey could then be reported as an account on a companies TOML.

Conversely, a hosted service like stellar expert could report one of their keys as the bld_pubkey thus providing proof that they built the WASM.

[tupui]

Interesting idea, sort of GPG signing (a tangent, sort of what I wanted to do with Tansu and putting commits on-chain to close the loop). I am wondering if that would fit better here or on the attestation side??

@prempador the whole topic could interest you maybe 😃

[mootz12]

I suppose this would be the extension for SEP-55 (or replacement of) in response to this work.

But I agree this does not need to be defined in this discussion or work. It's probably a better discussion to have once this is finalized.

However, it will impact the CLI's build and verify workflows to both generate this signature and verify it.

[orbitlens]

Looks like a very solid proposal backed by a serious research 🧐 👏

My primary concern here is the simplicity. It should be dead simple to use and almost impossible to make mistakes with, otherwise we'll see a lot of complaints about the building process and incompatibility (if you open even a tiny hole for the users to make mistakes, they will definitely use it).

E.g. build parameters can be simplified significantly if we assume some defaults.

• cliver - I don't see any practical need in working with nightly builds of Stellar CLI here, so we can assume that it's always a tagged revision. So corresponding container images can be produced automatically every time a new version of Stellar CLI is published. This way cliver can be a unique identifier of the environment and substitute bldimg.
• rsver - People will be working with this in production, preparing their contracts for on-chain deployments. So we can always use the latest available stable Rust release at the moment of new CLI tagged version release. So we can skip it.
• bldimg - Not needed. cliver should uniquely identify the image.
• bldopt_profile - Not needed. Should be always release (adequate default setting for on-chain deployed smart contracts).
• bldopt_optimize - Not needed. Should be always true (adequate default setting for on-chain deployed smart contracts).

I also think that defining different "classes" makes this proposal irrelevant. What's the real value in having classes B and C if they can't be reliably and unambiguously reproduced in the future? There's literally zero value in the verification process that results a smart contract be marked as verified in some wallets but non-verified in explorers or vice versa?

Lastly, agree with @fnando. This SEP should be either merged with SEP55 or substitute it.

[leighmcculloch]

bldimg - Not needed. cliver should uniquely identify the image.

It's unclear to me if it will hold true that there will only ever be one image per cli version. Pinning to the build image with its full sha256 digest, rather than pinning to a cli version, is a simple way we can keep this decision open. It can be optimised in the future down to cli version if it does hold.

One example for why there might be multiple images: we offer amd64 and arm64 stellar-cli images, and we could allow people to build with either so as to preserve fast build times and increase the diversity of who can deploy contracts because not all container build systems ship with emulation.

💡 Lets remove cliver from the spec and keep bldimg. cliver is redundant.

💡 @mootz12 identified at stellar/stellar-cli#2525 (comment) that it will be important for verifiers to have an allowlist of trusted images so that bldimg doesn't open a
can of worms while still being flexible as the community needs it to be.

rsver - ...we can always use the latest available stable Rust release...

👀 I'm seeing teams do their source code audits before doing their final builds. Rust releases frequently, every 6 weeks at minimum, and so it's possible for audits to start and finish when latest rust has changed. I think we need to keep it so teams can build and verify with the version of rust they audited on, while using newer cli tooling that might be required if a protocol vote has occurred.

However, the current spike uses a single image and auto-installs the specified Rust version using Rustup. I'm not sure that will guarantee reproducibility. Ideally the bldimg pins the cli version and a rust version which would eliminate the need for rsver.

bldopt_profile, bldopt_optimize - Not needed...adequate default setting...

We should spec and setup the tooling so the meta fields have adequate default values and if those defaults are in use, they don't need storing in the contracts. I'll add defaults and leave them in for now while more feedback is collected because I don't think eliminating them has a significant gain and it is simpler to say all supported build options get recorded, similar to how other chains do.

The bldopt list will grow too. For example, we need to add bldopt_features as @mootz12 pointed out at stellar/stellar-cli#2525 (comment).

Ideally we make the default for optimize to be on, so I've opened stellar/stellar-cli#2565.

...defining different "classes" makes this proposal irrelevant.

👍🏻 Classes make the spec longer without a lot of value, and I think we can restructure how it is written to eliminate the need for them while still allowing a verifier to validate with information not within the contract.

[leighmcculloch]

@orbitlens I've simplified the specification by removing all the differnent bldopt_* fields in favour of one repeating field: #1923 (comment), so it is just bldimg and bldopt now.

[Chupsy]

Thanks for sharing this early, the approach looks solid.

A couple of practical concerns from our perspective:

• Post-deployment verification: Contracts that are already deployed without the new metadata fields can't be made verifiable without a full redeployment, since Soroban contracts are not upgradeable. This is a non-trivial operational cost for any team with live contracts.

• Source delivery flexibility: Not all teams build from a public GitHub repository, and some may prefer to submit source for verification separately rather than embedding a repository URL in the deployed bytecode, especially when repositories might change while the contract is immutable.

The updated draft spec covers both via Class C and the verification registry pattern in Appendix A.3, this is exactly what's needed. We'd just want to make sure this path remains a first-class citizen in the final spec and that explorer integrations support registry-verified contracts alongside self-verified ones.

Happy to provide more feedback on the registry interface as the discussion evolves.

[orbitlens]

Post-deployment verification can be carried out only manually by the infra providers (e.g. explorer) since most of the wallets and other clients won't be performing the verification themselves (too costly, especially class B and C) -- they will be using third-party APIs instead. That's why I think class B and C verifications shouldn't be in the SEP at all, they require manual verification and cannot be automated.

Not all teams build from a public GitHub repository, and some may prefer to submit source for verification separately rather than embedding a repository URL in the deployed bytecode

My personal opinion on this -- only contracts with public repository (maybe we should allow other providers alongside GitHub later) should be able to use the verification routine described in this SEP. Because if the source code is verified, but nobody can see it (or cannot prove it independently), what's the point of the verification at all?

especially when repositories might change while the contract is immutable.

SEP points to a specific commit hash (source_rev param) instead of just using the repo URL itself. It's immutable.

[tupui]

I think support for closed source models is relevant because lots of financial institutions won't want to have their code out there even on things like smart contracts. Still, they could be required to follow e.g. DORA and provide such guarantees to an auditor who would have access.

+1 on allowing multiple providers. We should always push for more decentralization. What are we doing here otherwise 😉. This aside, with everything happening on GitHub I would be cautious on setting any strong dependencies there. There has been a few teams moving to Codeberg and even saw some move to Radicle (myself considering the move to it as well.)

[tupui]

@willemneal @chadoh I think we should keep an eye on this for what we are building with https://rgstry.xyz/

For context here. We are working with a few community partners on a contract registry. This project is also getting some support from SCF.

[chadoh]

Thanks for pulling me into this conversation, @tupui. Some ideas of how Registry could integrate with this standard:

1. Information Surfacer: Given that we aim to have Registry be a primary site of Stellar contract discovery, we can surface the bldimg / bldopt / source_repo / source_rev / tarball_url / tarball_sha256 information, as available for each Wasm
2. Post-deploy bldimg source-of-truth: to @Chupsy's point that already-deployed contracts would have difficulty adding this bldimg / source_repo / etc information, if it's only stored in contractmetav0: Registry can also allow Wasm owners to add this information at the level of the Registry contract. (The exact mechanics here need to be considered carefully, as we don't want to introduce attack surfaces. For Wasms tracked by the root registry, this information would probably need to go through Registry Security Council review on Tansu, just as adding new contracts to the root Registry does.)
3. Open-source verifier: for wasms with open source source_repo / tarball_url, Registry can run a cron job on our side to pull & verify that the source & bldopt result in the correct wasm_hash. Registry will show some sort of checkmark or warning sign, as appropriate. (I understand that verifying builds is its own science, as highlighted in a thread below started by @chan-lz. We on the Registry team have not yet started designing this verification feature; it may make more sense to integrate with & highlight another verifier's checks instead.)
4. Trusted auditor verifications for closed-source repositories: To address @Chupsy's request that this standard support closed-source repositories while acknowledging @orbitlens's point that this information is of little utility without a trusted auditor in the loop, Registry can allow trusted auditors to mark the source_repo / bldimg / etc information as verified (that is, to certify that the information surfaced in this standard does, in fact, correspond to the Wasm's actual hash). This requires two steps:
   1. Building on the named G-addresses we have planned for this quarter, we can add a way to identify some G-addresses as trusted auditors (using the existing subregistry system, this could look like auditor/certora / auditor/runtime-verification / etc, but the exact implementation details do not need to be decided now). The key here is that getting added to this list of "trusted auditors" would require going through the same Tansu-powered Registry Security Council review process as getting a contract added to the root registry.
   2. Once we have a pool of trusted auditors, we can gate certain contract calls based on membership in this pool. The Registry can provide a verify_source method (exact name TBD), only callable by trusted auditors. The value stored in the Registry contract here would be a Option<bool>, starting out as None, to indicate that no review of the provided information has yet occurred, and then either Some(true) or Some(false) to indicate the result of the verifier's check. This could also be designed in a way to allow multiple verifiers to store independent reviews.

If this standard ships imminently, Item 1 here can be completed by the Registry team within Q2, as part of our Registry UI enhancements effort.

The rest of these items, pending more conversations with y'all to hone the exact designs, could potentially be part of our Q3 milestones.

[leighmcculloch]

4. Trusted auditor verifications for closed-source repositories

It's unclear at this point if this requirement has an immediate use case so I don't think it is worth investing a lot of time into it until a use case appears. My understanding of the closed source issue being discussed at #1923 (comment) is that the closed nature of the source is temporal, and rather that the deployment won't occur from a publicly accessible repo, and instead the source will be made public through some alternative means such as a separate public repo that just receives release snapshots.

@Chupsy please correct me if I've misunderstood.

[tupui]

For the private sources. We have a precedent of a client (can't really name here but could share on Slack) where the contract won't be made public and there is no indication that this would change.

Traditionally all the finance sector is not sharing information publicly unless strictly necessary even if there is no "secrets." I.e. we should keep this in mind to work with this constraint.

[Chupsy]

We also work with partners who are unlikely to make their contract source code public, or to create a separate public repository containing release snapshots. In that sense, I agree with @tupui that this is a constraint worth keeping in mind.

Some partners may still be willing to provide source bundles to a trusted verification provider so that the deployed contracts can be verified. In that model, the verifier could confirm that the provided source, build image, and build options reproduce the deployed Wasm, and potentially expose only the verification result and relevant metadata.

However, requiring a publicly fetchable source repository or tarball would likely exclude some of these use cases.

[leighmcculloch]

Hi all, the feedback has been very helpful.

I have revised the draft specification to incorporate feedback, reduce the number of unique meta that needs to be stored, remove unnecessary concepts like classes, and focus on the build environment information that's required to succeed at reproducing a .wasm build from source, since that seems like the most critical component to validate and agree on. And the spec continues to keep the implemenation options open to a variety of setup: open automation, closed verification registries, pre and post deployment verification, etc.

• https://github.com/stellar/stellar-cli/blob/4ace4a83c192a5c899d9249c0fd2bf9abc50227b/draft-specification.md

The specification is now less prescriptive about how tooling functions and just describes the basic mechanism of using docker/containers to replay that build environment information.

The mechanism describe in the spec can be automated by cli tooling, explorers, and verification registries.

Does this seem sufficient to everyone?

[mootz12]

Gave this a review, and it looks good to me. Good additions on the tarball/hash source code options!

[chan-lz]

Hi, wanted to share a deployer's perspective on bldimg. The spec already flags this in Security Concerns, but I think it deserves stronger treatment than a SHOULD.

A verifier that replays whatever bldimg is embedded in the wasm is, by construction, trusting the deployer — the same party whose code they're trying to independently verify. Two practical failure modes:

1. Opaque images. Many teams build inside a CI image that is publicly pullable but whose own Dockerfile / build pipeline is not public. A digest pin guarantees the verifier gets the same bytes the deployer got, but it doesn't let them audit how those bytes were assembled — what base layers, what toolchain install steps, what patches were applied. From a third-party auditor's standpoint the build environment is still a black box.
2. Hostile images. Even with a public image, nothing prevents it from shipping a modified rustc / wasm-opt that deterministically rewrites bytes. The rebuild matches, the verifier reports ✅, but the wasm doesn't correspond to the source. "Reproducible" ≠ "faithful to source."

Both are inherent to letting bldimg be a free-form field, not tooling bugs.

[leighmcculloch]

👍🏻 In much the same way with SEP-55 that an auditor must thoroughly review a workflow and it's logs, an auditor for this proposal must review all of the dependencies up to some boundary they trust.

Verifiers SHOULD restrict bldimg to an allowlist of independently vetted images rather than trust arbitrary digests.

I use the term SHOULD in the specification (ref) because it depends what guarantees a verifier is providing. If a verifier is providing a guarantee that the build replays, then a user of that verification service would need to review all the dependencies. If a verifier is providing a guarantee that certain trusted images have been used, then a user may not need to review those components if they trust the verifier.

Both are inherent to letting bldimg be a free-form field, not tooling bugs.

There are many points in a Rust projects build process that become a free-form input into the final artifact. The crate could inject code via proc-macros, build.rs scripts, or innocent appearing transitive dependencies. The build image is one more. This should be motivating for contract developers to use publicly auditable images and image build processes.

I think it's reasonable that there might be a service that provides insight into a build in similar ways that other security analysis products do in addition to a 'verified' stamp. For example, socket.dev doesn't provide a simple yes / no, they provide a multi-dimension signal that auditors can use. I am imagining dimensions like "build image with pubicly viewable build and attestation," and a columns about dependencies:

Ref: stellar/rs-stellar-strkey#112 (comment)

[chan-lz]

That makes sense to me. I agree the verifier's guarantee matters: replaying a build and asserting use of a trusted build environment are different claims.

The concrete outcome I'd like to see is for the Stellar/Soroban team to publish official recommended build images, with the image build process itself public, attested, and auditable: Dockerfiles/pipelines, provenance, pinned bases, SBOMs, signatures, etc.

Then bldimg can remain flexible, while verifiers can report stronger signals around the image: arbitrary deployer image, publicly auditable image, or Stellar-maintained trusted image. That feels similar to the socket.dev-style model you mentioned: not just yes/no verification, but a multidimensional trust report.

There is also a social trust component here. For most auditors and users, an image maintained and attested by the Stellar team is a much stronger trust boundary than an arbitrary digest supplied by the deployer.

[leighmcculloch]

👍 I agree that is the ideal outcome.

[orbitlens]

Thanks @leighmcculloch for rewriting the spec based on the feedback.

Something that isn't clear to me is who will be the users of custom build images. From my point of view, SDF should be the only entity providing standard minimalistic images that can be further used in the release purpose and code verification. We are ready to employ this standard for the automated source code verification in StellarExpert, yet we will never use arbitrary images published by someone except for SDF or our company. First of all, it's potentially not safe for the host env (recent CVE-2026-31431 and CVE-2025-31133 showed that container isolation might be not as bulletproof as people think). Ultimately, it's not safe by nature -- running arbitrary code (even in the container) not a good idea, it can lead to all sort of attacks (third-party DDoS, resource exhaustion, Monero mining, spam/virus re-distribution, etc.) And since we plan to automatically execute the verification procedure for all contracts that get uploaded to the ledger, it poses a significant security threat for us. I think the same applies to any other explorer/indexer/wallet/app that is going to automatically perform the verification either triggered by on-chain events or on-demand.

Regarding multiple container images for different architectures or with different compiler toolchains. I still think that there should be only one image per Soroban SDK version (automatically assembled with the latest stable Rust toolchain upon the new SDK release) -- not entirely convinced that people really need arm64 image for this particular purpose. Because this release mode with containerized compilation will likely be used only a few times per project since people will not be using it during development or for running tests -- it's simply not needed for any other situation, contract compilation before publishing on the Mainnet is the only use-case for it. And for such rare occasions they can survive the inconvenience of using a single standard amd64 image instead of one optimized specifically for their architecture.

Lastly, regarding custom pipelines or verifying contracts without a public repo (classes B and C in the original notation). I'll reiterate on this -- only contracts with public repository can be verified automatically using routines described in this SEP. Everything else should be outside of the scope. @tupui pointed out on DORA and other requirements that may imply executing verification over the closed source. But what is the practical impact for the ecosystem in this case? StellarExpert won't display any verification status for such a contract (as we cannot automatically verify it), the same goes for any other ecosystem apps/wallets. So it's a verification that nobody can actually validate, and therefore it's useless for wider public.

I firmly believe that any process that involves ambiguity or human in the loop should be excluded from this SEP. If a third-party auditor ready to testify that the smart contract code was compiled from a given source (and it's up to them what processes, toolchains, env varaibles do they use to verify that), they can simply sign a proof (it can be a JSON string with verification details: source, toolchain version, owner company, etc) and we will pull this data from the TOML file. This way we can establish a trust chain auditor -> source code -> binary and display something like "Source code [link] audited by [auditor company]" in the interface for our users. This can be done automatically unlike other complex verification flows prone to errors or manipulations. Also, it provides the maximum flexibility.

This is an awesome SEP that addresses a long-standing problem. I've been working on this problem for more than 2 years and really happy to see where all this is moving. Let's just make this SEP a bit more straightforward and we'll start using it right away.

[leighmcculloch]

@orbitlens This is very helpful feedback, thanks.

custom build images...we will never use arbitrary images

I think it is 100% reasonable for any verifier including Stellar Expert to have an allowlist of image sources and to only verify using images from that source. It might also be reasonable to have an allowlist of specific images, but I think an allowlist of image sources would suffice and lower the maintenance burden.

The spec won't specify that source. In much the same way that validators on the network define their own trust model, a verifier should be the one to define its trust model. The spec will just describe the mechanics, and verifiers can make the decision on what image sources to trust.

At this stage I am proposing SDF host images for stellar-cli that will be used for this purpose, and that those images get all the good stuff like attestation for their builds, and best practices so that their builds are as reproducible as possible. Like everything we do, SDF is likely to provide those images as an open source GitHub repo building on open infrastructure (GitHub Actions) so that it is fully inspectable by anyone and easily reproducible.

only one image per Soroban SDK version

The soroban-sdk can't be the driver for the images because it's not at the top of the build toolchain. The stellar-cli is the build toolchain.

I'm proposing that SDF host at least one image per toolchain (stellar-cli version + rust version). The common case will be just one per stellar-cli version that has the latest rust version at that release date (you suggested this prior and I think that makes sense), but I'd like the spec to require the wasm to reference the fully qualified docker image with it's sha256 digest so that the link between the wasm and the docker image is absolute and leaves no chance that through some attack someone swaps an image out referenced by the same stellar-cli version. Even just for the purpose of debugging I want to know for sure when we are debugging a reproducibility bug (they will happen) that the wasm was built with a specific very exact build image.

It'll also leave open the potential to ship additional images per stellar-cli version where needed. I don't expect this will be a common occurrence, but this is basically free to support if wasms reference images. I propose any additional image would be built through the same repo, the same pipeline, the same controls, everything from committed source, no human involved builds.

arm64...inconvenience of using a single standard amd64 image

I am exploring the possibility of having the stellar-cli automatically perform all builds with the docker backend if it is available. Why: One of the issues we've seen is that folks build during development and ship their contract and then later realise they should have followed an alternative flow for their final deployment. This is why I'm looking at how to keep the flow consistent for development and release. Building without the docker backend will probably output a warning about the build being unverifiable.

More experimentation is needed here though. It's possible building with arm64 and amd64 hosts results in identical .wasms at which point the architecture won't matter. It's possible the build times of emulated amd64 is not that different too in which case we can default to always using amd64.

❓ Is it feasible for verifiers to support arm64 images? @orbitlens Do you expect a verifier will encounter problems with a mix of amd64 and arm64 images? The requirements on the verifier would be similar to requirements for a developer, it'd need emulation enabled on the docker/container runtime.

If there isn't a hard technical reason not to, I'd like to avoid adding an architecture requirement to the spec and leave that aspect open. But if there is, it's reasonable to restrict that in the spec from the start.

verifying contracts without a public repo...StellarExpert won't display any verification status for such a contract

Thanks for confirming this. cc @Chupsy

we can establish a trust chain auditor -> source code -> binary and display something like "Source code [link] audited by [auditor company]" in the interface for our users

👍🏻 Something like this flow sounds good to me. @willemneal @chadoh @chadoh Since you're building an on-chain registry tracking auditors and audits might be something you have already thought about. I think wherever this flow exists, it will be largely independent of the main source code verification logic, and so we can define it as another SEP either now or at a later point once we get this first part working. The key part being as you put it there shouldn't need to be a human coordination point.

This is an awesome SEP that addresses a long-standing problem. I've been working on this problem for more than 2 years and really happy to see where all this is moving. Let's just make this SEP a bit more straightforward and we'll start using it right away.

❤️ 🚀

[leighmcculloch]

I've taken the draft specification I previously posted at #1923 (comment) and propose it be included in the stellar-protocol repo as SEP-58, still in draft for tweak during implementation:

• SEP-0058: Contract build reproducibility #1933

The only modifications I made were clarifying and filling missing guidance:

1. Following the conversation with @orbitlens here, capturing the importance that verifiers only verify contracts using image sources they trust, there is now a paragraph discussing this, along with what makes a good image source, while deferring the decision on who to trust to the verifier.
2. Following the feedback from @tupui and @chan-lz at here and here, capturing the need for images to be auditable through the suggested mechanisms (attestation, sbom, etc).
3. Adding requirements on the image setup (workdir, entrypoint) to increase compatibility.
4. Fixing some regex errors identified by PR review.
5. Reformatted using prettier to match stellar-protocol SEP formatting.

[Edit: Added point 3 and 4.]

[tupui]

Thanks! I left some suggestions there.

[tupui]

Following up the review I left here #1933 (comment) and opening up a point about schema for URL/URIs and protocols.

There is some wording in the design rational section about the SEP not prescribing this too much. Still, in the specification part we are giving examples of regex with HTTPS URLs and GitHub. I am concerned that this will lead in practice systems to only understand HTTPS + GitHub and flag all the rest.

I think we should strive to be more agnostic. As with everything, in practice that still means support tiers. A minima, I suggest that IPFS be on the same support level as HTTPS.

For GitHub, we almost don't need to mention the forge itself.

[fnando]

Details

IGNORE THIS SECTION

An internal discussion brought up an interesting point: given that we may have many vendors running verification and displaying the status (¡viva decentralization!), the file digest hash could diverge for some reason (mostly due to misconfiguration of the verification process, but could also be one of the vendors being hacked).

One of the suggested ideas was making home_domain a required meta field (also used by SEP-55, optional), so interfaces displaying the verification status can have a hint of the advertised hash. The stellar.toml could have a section linking contract ids with the digest:

[[CONTRACT_VERIFICATION_HASHES]]
C…ID="sha256:<sha>"

Then interfaces could have something like:

$ stellar contract verify --id C…ID
Publisher https://example.com advertised contract as sha256:<sha>"

[√] Verified by Stellar Expert
    https://stellar.expert/explorer/public/contract/C…ID
[√] Verified by Rgstry
    https://mainnet.rgstry.xyz/contracts/C…ID
[!] Verified by ACME — Diverged from advertised
    https://example.com/mainnet/contracts/C…ID

This also helps with contracts that have private code, because you have some indication of what's the published contract by checking the toml file.

Is this something we should consider?

Edit: This doesn't make sense, now that I think about it. It must match the deployed contract and nothing else. The flow for displaying statuses would be:

1. fetch the wasm file and generate the sha256 digest (A)
2. call vendors’ apis to retrieve the verification status (to be defined as a separate SEP) (B)
3. check (A) matches the hash returned by (B)

Anything mismatching would display an error message:

$ stellar contract verify --id C…ID
Publisher https://example.com/ advertised contract as sha256:<sha>"

[√] Verified by Stellar Expert
    [https://stellar.expert/explorer/public/contract/C…ID](https://stellar.expert/explorer/public/contract/C…ID)
[√] Verified by Rgstry
    [https://mainnet.rgstry.xyz/contracts/C…ID](https://mainnet.rgstry.xyz/contracts/C…ID)
[!] Mismatching verification by ACME
    [https://example.com/mainnet/contracts/C…ID](https://example.com/mainnet/contracts/C…ID)

[leighmcculloch]

the file digest hash could diverge for some reason

Which file digest could diverge? The wasm hash shouldn’t change, that’s the reason behind reproducible.

The verifier is there to rebuild the code to produce an identical hash to match the wasm on chain.

[fnando]

in the meeting, we came from an angle that didn't consider the uploaded wasm file. So, verifying C...ID must match the wasm hash that's uploaded to the chain.

[leighmcculloch]

Publisher https://example.com/ advertised contract as sha256:<sha>"

RPC and the network already advertise the wasm hash of a contract. A publisher role is not required for that.

Then verification should be a lookup on verifiers with the wasm-hash. That’s the ID folks should be using. Services can support lookup via Contract ID too if that makes sense but Contract ID <> wasm hash relationship is temporal and anything that relies on that being stable could be exploited.

[shilpachittara]

Hi everyone,

We've been following this thread closely and wanted to share where we've landed, since we're putting together a proposal for the contract source verification RFP and the build-environment details being worked out here directly shape what we're building.

For context, we have a working prototype: a rebuild-based verifier for Soroban. Someone submits their source, we rebuild it inside a pinned container, and we check whether the resulting Wasm hash matches the bytecode on the ledger. Results go out through a free, open API so explorers, wallets, and Lab can show a "source verified" badge without rebuilding anything themselves. It's open source and self-hostable, no KYC.

A few things specific to the discussion here:

On image trust. We're aligned with the direction this thread has been converging on, that a verifier defines its own trust model. Ours only rebuilds using SDF-sourced, digest-pinned images from an allowlist; we don't run arbitrary deployer-supplied images, for the safety reasons orbitlens raised earlier. We report the image trust signal alongside the match result (e.g. "built with an SDF-maintained image" vs "image not on our allowlist"). If SDF publishes official stellar-cli images with attestation and SBOMs, that fits us well: bldimg can stay free-form while verifiers still report a meaningful signal, much like the multidimensional direction chan-lz described.

On bldimg and bldopt. We read both from contractmetav0. Today bldimg selects the allowlisted image we rebuild in. Applying bldopt (passing the recorded options through to stellar contract build on replay, and recording the image digest plus options used so the result is independently reproducible) is on our near-term roadmap rather than something we run yet. Collapsing the spec to just those two fields works cleanly on our end and keeps that work small.

On already-deployed contracts. Since contracts can't be redeployed to add metadata after the fact, we also handle contracts without on-chain SEP-58 fields: source can be submitted out of band (direct upload, hosted tarball + sha256, IPFS, or hash-only) and verified against the deployed Wasm. We'd like this path to stay first-class in the final spec, alongside the registry pattern Chupsy and tupui raised for surfacing this info post-deploy. We recognize this is contested: orbitlens argued that contracts without public, independently reproducible source shouldn't be verifiable under the SEP at all, partly because that path can't be automated and falls back to manual checks. Our take is that a service layer is what makes registry-based verification of these contracts automatable in the first place, which directly addresses that concern.

On multiple verifiers disagreeing. We treat each verifier's result as a signed, attributable signal and aggregate them into a consensus view (verified, divergent, mismatch, etc.). There's deliberately no single global authority deciding what's "correct" — consumers pick which verifiers they trust. We can line this up with whatever submission and discovery shape SDF decides on, service-mediated or more on-chain.

We see rebuild verification and SEP-55 attestation as complementary signals rather than either/or, and we'll conform our API to wherever the spec lands.

Two things we'd genuinely like input on:

1. Where should post-deploy metadata live: contract meta, a registry, or somewhere else?
2. Is the plan for SDF to be the sole publisher of trusted builder images, or is there room for others?

[chadoh]

Hey @shilpachittara! Chad from The Aha Company / Stellar Registry here. Wanna reach out to me on Discord? Same username as here. We are working on our RFP submission now, and your solution would nicely complement ours. We might have a stronger submission if we work together.

[fnando]

Posted the SEP draft for the registry API. Any feedback is appreciated! https://github.com/orgs/stellar/discussions/1945

[shilpachittara]

Hi @chadoh! Let's connect on Discord to discuss this in detail. shilpachittara is my Discord username.

[ethanfrey]

I'm also looking at the RFP for contract verification and have managed to validate some deployed contracts using the image build scripts from github.com/stellar/stellar-cli-docker. (Thanks @fnando )

A question on what gets stored, since you asked for feedback there: how is bldopt meant to be read by a consumer, versus just replayed?

The spec frames bldopt as replay-only: verifiers "replay the recorded flags," entries may repeat, order isn't significant. That's clean for reproducing a build. But one thing folded into it is load-bearing as identity, not just as a build knob: which contract in the repo this is. In a workspace that selection rides in as bldopt=--manifest-path=contracts/foo/Cargo.toml (exactly as in Appendix A) — a §1 "how it was built" entry carrying a §2 "what was built" fact.

StellarExpert already treats that as first-class; its verification record surfaces package directly alongside repo and commit:

{
  "validation": {
    "status": "verified",
    "repository": "https://github.com/AquaToken/soroban-amm",
    "commit": "c4d842de3108a23a4a1107b7d54c357bae45f962",
    "package": "soroban-liquidity-pool-router-contract",
  },
}

(You can check this yourself via curl https://api.stellar.expert/explorer/public/contract/CBQDHNBFBZYE4MKPWBSJOPIYLW4SFSXAXUTSXJN76GNKYVYPCKWC6QUK )

AquaToken/soroban-amm ships 15 contracts; without that field a "verified" badge can't say which one it's for. (SEP-55 on Stellar Lab has the same gap today.)

Two concerns with leaving it inside bldopt:

1. Interpretation. To display "which contract," a consumer has to parse semantics out of a list the spec says is for replay — and the flag is optional (a default-member build omits it) and could equally be --package. There's no guaranteed, canonical place to read it.
2. It's a path, not an identity. --manifest-path is a path to a Cargo.toml; StellarExpert reports the cargo package name. Those aren't the same thing, and keying a displayed identity off a free-form, order-insignificant build flag feels fragile for something this central.

Suggestion: give "which contract" a canonical source-identification field in §2, alongside source_repo/source_rev — e.g. the cargo package name (and/or the manifest path relative to the source root). Producers would still pass --manifest-path/--package to actually build; the dedicated field just makes the selection explicit and parseable rather than something consumers reverse-engineer out of build options. This doesn't undo the collapse to a single bldopt — it just pulls out the one entry that's source identity rather than build tuning.

[leighmcculloch]

Manifest path identifying the crate does seem like something that lends itself to being first classed into its own field.

The argument I see for keeping it just in bldopt is that today bldopt is nicely divided away from the other meta in that the other meta are not build options that can be passed to the cli. If we move manifest path out of bldopt, then the build options will be found in two places, with the non-bldopt meta, and with the bldopt meta.

But I think there is strong argument for making it a field, as a derived value. Bldopt would still have it when it was necessary. So the value in bldopt would drive during a build, and the value outside bldopt would be part of the result just capturing what the manifest path was.

Would like to hear from more people, but I think ☝🏻 would work well, albeit being a little subtler than is ideal.

[ethanfrey]

I would actually suggest keeping it as a field and not in build opt, and make it clear that --manifest-path ${path} must be passed as a build opt. The same way that checking out the source repo at the given commit is essential to a reproducible build.

Having it duplicated makes it possible for a difference between that shown to the user and that run by the docker image.
Leaving it as a free-form build-opt means we need to parse and have to assume that they use this field (and not -p ${package}) to get the proper one. Also, we should enforce only one wasm binary is built - to ensure that building the full mono-repo doesn't just match without providing proper providence of which contract it was.

[fnando]

I agree the contract selection deserves to be explicit and parseable rather than reverse-engineered, but I don't think a dedicated field is the way to get there, because it'd be redundant.

Meta is set by passing stellar contract build --meta …, and the selection flags you'd build with (--manifest-path/--package) already land in bldopt. So a separate source_path/package field would just duplicate what's in bldopt, growing the wasm with no real benefit.

Given that, I'd rather require the selector in bldopt instead of adding a field:

bldopt: --package=mycontract                        # canonical identity (required)
bldopt: --manifest-path=contracts/foo/Cargo.toml    # location (optional, defaults to Cargo.toml in root)

That covers everything raised here:

• Parseable identity: mandating --package gives consumers a guaranteed place to read. It's the name StellarExpert already surfaces, readable straight from meta without fetching source.
• "Only one wasm": --package=X resolves to exactly one crate → one cdylib → one wasm, so the requirement enforces provenance directly.
• Path vs. name: --package is the identity; --manifest-path is the navigable location when present. We MAY treat --manifest-path as optional, defaulting to Cargo.toml in the root dir, so single-crate repos don't have to state it.

Since the selection already lives in bldopt either way, the clean move is to make it load-bearing there: --package required, --manifest-path optional defaulting to the root Cargo.toml, rather than restating the same selection in a redundant field.

[ethanfrey]

Okay, making those two flags as required does seem like a valid approach to me. This should be clear in the spec and clients should reject any build that does not have --package

[XxHugheadxX]

Hey @fnando — just a quick update from the CSV Verify team.

We're still actively working on this. Our current
implementation is running on testnet with the
bldimg allowlist approach you mentioned — we only
accept the official stellar/stellar-cli image,
which aligns with the trusted image boundary
discussed here.

We've been following the spec simplification
closely (just bldimg + bldopt now) and our
pipeline already reflects that structure.

More updates to share soon.

[saimeunt]

Hi everyone, we’re Walnut and just submitted a proposal for the Contract Source Verification Service RFP.

Our approach is focused on providing a registry of verified contracts rebuilt using the core verification logic and build reproducibility explained in SEP-58 Appendix A.

We plan on leveraging on-going work (#2586) on the stellar-cli to verify contracts and make sure our verifiers use a build reproducibility everyone can agree on:

• Use baked in stellar contract verify command result, embracing SEP-58 build reproducibility as single source of truth.
• Use an allowlist for trusted image sources (begin with digest-pinned stellar-cli repo on docker.io).
• Use Docker to open-source our service container responsible for scheduling isolated stateless builds.

Our public verifier API write endpoint will rebuild submitted contracts and persist verified results (both WASM-hash match) in a DB as well as SEP-58 fields and contract sources. Verified contracts results are available as cheap lookups by calling our API read endpoints.

Our approach to decentralization is to provide an open-source, easily self-hostable service to let multiple verifiers host their instance and aggregate results in a separate, dedicated endpoint. The verifiers making their way to the aggregated endpoint should be whitelisted by the SDF and anyone can apply as long as their service adhere to the upcoming verifier-API SEP.

We acknowledged retroactive verification for contracts deployed before SEP-58 adoption is mandatory and we think a correct approach would be to include an escape hatch in stellar contract verifyto enable passing SEP-58 fields in case contractmetav0 isn’t found in WASM metadata (discussed in #2586). The same verification core logic would be used just like contracts built with stellar contract build --verify and the results will be flagged accordingly as having their build environment supplied in the verification request and not read on-chain.

Any comments or feedback is appreciated!
cc @leighmcculloch (authored SEP-58) and @fnando (implemented SEP-58 reproducible builds in stellar-cli).

[fnando]

Posted the SEP draft for the registry API. Any feedback is appreciated! https://github.com/orgs/stellar/discussions/1945

[leighmcculloch]

We plan on leveraging on-going work (#2586) on the stellar-cli

• Use baked in stellar contract verify command result

I suggest using the stellar-cli docker image directly rather than the stellar-cli. Some similar discussion about this at stellar/stellar-cli#2586 too. The stellar-cli is a contract developer facing product so it'll make some decisions that don't necessarily align with being a foundational component that verification services should build on otherwise they'll be limited by what the stellar-cli will support.

The foundational component to build on is the docker image itself, and then using it with a variety of sources, both what's on chain as well as your own verification registry database, with uploaded code, meta, or code sourced from elsewhere.

[saimeunt]

@fnando Thanks for pinging me regarding the verifier-API SEP, it will be foundational to how we architecture a full verifier, I left some comments in the related discussion.

@leighmcculloch Likewise, thanks for the clarification regarding using the Docker image as opposed to leveraging work done on the stellar-cli itself, this is really helping for steering the verifier architecture in the right direction.

[fnando]

@leighmcculloch while writing this response, something came to me… the source_code+source_rev vs. tarball_url/tarball_sha256 pairing/combination is not great, imo.

Could we drop source_repo and source_rev from SEP-58 and have the tarball_url matching patterns below instead? That way we'd have just tarball_url (absent means private source code) and tarball_sha256 (could be optional for VCS-based urls).

https://example.com/archive.zip
ar://<address>
ftp://ftp.example.com/archive.zip
https://github.com/user/repo/archive/commit-hash.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

For git, only rev=commit-hash would be officially supported, so tag or branch can fail.

[fnando]

@ethanfrey the way I see, verifying contracts built without following SEP-58 is not something we can really fix. Upgradeable contracts can be redeployed if developers want to, but immutable contracts will need to go through the out-of-band verification with each verifier they care about.

Each verifier will need to have a registration ui to inform all the things needed to build the contract, like build options, env vars, etc (this also kinda answers your other comment).

[chadoh]

verifying contracts built without following SEP-58 is not something we can really fix

It's something we can fix pretty easily 😉

I'll refer you to my previous comment and the explainer video it links.

immutable contracts will need to go through the out-of-band verification with each verifier they care about

Why on earth would we design the system that way? Making the Registry a post-upload alternative is so easy. Source verification services need only ingest both wasm_upload and registry_build_info_added events and 💥 it all Just Works.

[leighmcculloch]

+1 SEP-58 was not intended to require somehow backfilling these details onto the wasms themselves, and registries, verifiers, mirrors, either onchain or offchain can be places to communicate these things after the fact.

For new contracts the tooling will embed the source_sha256 field within contracts to create even greater confidence that a source archive is the original source that produced the wasm, but for any contract without it then verifiers can follow whatever pattern they wish such as authenticating the original uploader or simply working on a first-come basis.

@chadoh nice video, it does a good job of illustrating this.

[fnando]

Source verification services need only ingest both wasm_upload and registry_build_info_added events and 💥 it all Just Works.

@chadoh so my point still stand: each verifier will run its own verification; the metadata ingestion via API or on-chain event or web UI is just an implementation detail, no?

[chadoh]

Each verifier will need to have a registration ui to inform all the things needed to build the contract, like build options, env vars, etc

I took this part of your previous comment to mean that if someone, with an immutable wasm uploaded prior to SEP 58, wishes to add their build info to Registry and have it verified, they would need to go to the UI of each individual source verification service and request such verification. Which seems really silly! Adding the info via Registry, if we go with our submission for the RFP, will be enough to trigger verification from all (vetted and approved) source verifiers. No need to go around and manually request source verification.

[gchacon011]

Hi everyone, we’re CSV Verify a Himera Consulting team. We just submitted a proposal for the Contract Source Verification Service RFP.

Our approach is focused on a public Soroban source verifier for Stellar:
it reads SEP-58 WASM metadata, rebuilds in Docker, compares to on-chain bytecode.
Live today — Vercel UI, self-hosted Rust backend, GET/POST API, and SQLite cache (not a proposal).
Developers add --meta at build, deploy to testnet, verify by Contract ID in seconds if cached.
Free for explorers, wallets, and integrators; self-hostable and aligned with SEP-58. SEP-58 Appendix A.
Post-MVP, live on Stellar testnet — full stack in production (Vercel UI + self-hosted Rust verifier on DigitalOcean), not a design doc.
We just finished participation in a local MORPHO studio hackathon where we recieved very positive feedback for our proposal. Looking forward to working with @fnando rnando

[sebasberrios-dev]

+1 from the CSV implementer side — what @gchacon011 summarized matches what we have running today on testnet: https://stellar-contract-verification.vercel.app

We’ve been verifying contracts end-to-end with the Appendix A flow (source_repo + source_rev + bldopt, rebuild in stellar/stellar-cli Docker, WASM hash compare). First rebuild is slow; cached GET lookups are instant.

Thanks @fnando for the reproducible-build work and the stellar-cli-docker scripts — that’s what got our verifier past “metadata reads fine but rebuild fails” in practice. We’re also experimenting with read endpoints shaped like the verifier-registry draft in #1945 (GET /v1/contracts/..., GET /wasms/:hash.json).

Happy to share implementer feedback on the SEP rework in the thread below.

[XxHugheadxX]

Hey everyone, I'm Will — part of the CSV Verify
team at Himera Consulting, leading the frontend
and API integration.

Wanted to add some context from the user-facing
side to complement what Sebas shared above.

The problem he describes — "metadata reads work
fine, but the rebuild fails" — was exactly what
took us the longest to sort out. Once
stellar-cli-docker stabilized the build environment,
the end-to-end flow with source_repo + source_rev

• bldopt became fully reproducible. Thanks
  @fnando for that work — it was the piece that
  unblocked everything.

From the UI side, it translates like this: user
pastes a Contract ID, we try a cached GET first
— if it's already been verified, the result
shows up in under 2 seconds. If there's no cache,
it triggers a full rebuild with an honest message:
"Rebuilding from source... This may take 2–6 minutes".

We're also aligning our read endpoints with the
verifier registry draft in #1945
(GET /v1/contracts/... and GET /wasms/:hash.json)
so explorers and wallets can integrate without
depending on POST /verify.

Happy to share more implementer feedback on
the SEP review in this thread.

[fnando]

@XxHugheadxX thanks for the update! Please give as much feedback as you can on #1945, based on the data you're gathering and exposing. Maybe we need additional info that's not covered yet.

[ethanfrey]

I have been working heavily on verifying existing untagged contracts and have had some success. While checking deployed wasm on mainnet, I noticed only about 1000 of the 3600 wasm blobs had cliver (while almost all have rsver). This could be due to a stellar-cli build with version < 23.2.0 when it was not yet added to the metadata. However, there are many older repos (from 2024 and 2025) that use cargo build --release --target=wasm32-unknown-unknown and we must also be able to support this.

I figured this could easily be supported by a slightly modified rust docker image (adding the wasm32-unknown-unknown toolchain via rustup, and setting "cargo" as the entrypoint, but I hit an issue. The current SEP-0058 spec requires passing "contract build" as hardcoded arguments, see the example:

$ docker run --rm -v "$PWD:/source" -e RUSTUP_TOOLCHAIN "$IMAGE" \
    contract build \
      --manifest-path=contracts/foo/Cargo.toml \
      --optimize

This makes it impossible to swap out a rust image there and do a cargo build. I have two potential ideas how to solve this and would love feedback:

1. Remove both arguments and bake them into the docker image. This means ENTRYPOINT ["stellar", "build", "contract"] for the stellar-cli-docker image so only the bldopt flags could be passed. The new rust image could use ENTRYPOINT ["cargo", "build"] and would be compatible.
2. Add a new bldarg field and pass that in like docker run $IMAGE $bldarg[@] $bldopt[@] This must be a new argument, as it bldopt can explicitly be reordered and repeated while these args must be passed in order and before any flags. Below is the text from the spec for bldopt:

A single shell-style flag passed verbatim as one argument to the build command, as if single-quoted in a shell (e.g. --profile=release, --features=foo,bar, --no-default-features). For flags that take a value, the = form keeps the flag and its value in one argument. The entry MAY appear multiple times, once per flag. The order of entries is not significant.

Of course this will break any existing images with the draft spec but that is an existing issue that will have to be addressed anyway and it should be pretty easy to programmatically tag these after the fact.

[leighmcculloch]

Encoding the entry point into the data may have some unintended consequences. For example I imagined we will build the stellar-cli to always assume the image is the stellar-cli, and call "contract" "build" on the image when building the contract for the first time (not replay). It'd be possible for someone to specify an image that has a custom entry point. But if we have the entry point specified by the first bldarg and assumed by the stellar-cli, it prevents that customisation and says that every image has to have the stellar command on the searchable path. That's a bit unintuitive given docker principles.

I think if we need the ability to customise the entry point then it'd be best to introduce a new meta for that.

So today we can stick with just bldarg "contract" "build", ...

Then if entrypoint customisation is needed in the future introduce a new meta for that at that time.

[ethanfrey]

If I read correctly there are three main approaches covered. All assume bldopt/bleary maintains position for flags and positional.

1. Entrypoint is one command (stellar, cargo, make, etc) fixed and bldopt adds the positional args now implicit (contract build, build, etc)
2. Entrypoint has the whole sequence (eg [stellar, contract, build] or [cargo, build] and you only add flags in bldopt
3. There is no default entrypoint in the image and bldopt starts [stellar, contract, build, —optimize, …]

While 1 stays the closest to the current format I don’t see it winning, as 2 is strongest on trusting an image (it will always be a valid stellar build command) and 3 is the most flexible (the same image can serve cargo, stellar or make (I found some using make build)

I think 3 could be a bit more confusing if you are auto-processing without human review, while 2 can be machine parsed much more easily (no custom build scripts to inspect).

I think both are valid choices, however 1 seems to have the worst of both - not enough flexibility but you could also have “contract wasm —hash xxx —rpc yyy” or such and just serve up the same hash it claims ignoring the source code entirely. This is obvious in human inspection but so are flexibility issues in 3. That said, both are pretty clear to any developer looking at the args, I guess the question is how automatic do you want this to be.

I think both have pros and cons, just want to push for either 2 or 3 rather than 1 which seems like a poor compromise.

[ethanfrey]

Thinking a bit more, this doesn’t need to be specified in Sep-58 and could be an image thing.

eg stellar/stellar-cli:<tag> will embed [stellar, contract, build] as an entrypoint and any client can very quickly validate those images in the UI and link to the code we know is the source.

and then stellar/stellar-cli-flex has no entrypoint and is flexible for all non standard use cases but you can’t directly just link to code in the explorers - you want a human to check what the build command is doing there (as they would review the code that is referenced anyway)

This would give us the security of 2 by default and opt in flexibility by swapping and image and no changes needed to clients

[fnando]

Because this image is not focused on building contracts, the official docker image's default entry point must be stellar. If we're recording just the build args (e.g. stellar *args, cargo *args), I believe the best solution for verifiers is explicitly setting --entrypoint.

For example, for contracts that used stellar contract build, that would record [contract, build, *args] and --entrypoint would be optional. For contracts built with cargo directly, that would record [build, *args] and the container would run with --entrypoint=cargo.

[leighmcculloch]

--entrypoint is only needed if using an image that has an entrypoint and the build process needs to change the entry point. I don't think we need to support that today, and if it becomes a need a meta entry can be additive to support it.

The intent with adding bldarg is so that custom images can be used that define a different entrypoint, such as cargo, and require different build arguments, such as ["build"].

I have updated #1965 so that bldarg is now additive and optional for passing arguments ahead of bldopts. If no bldargs are provided, then ["contract", "build"] is assumed.

[ethanfrey]

Another issue that came up while trying to find the source code for existing untagged repositories is the use of env! and option_env! in several of them. This means that a reproducible build environment must pass in a set of environmental variables that were used in the original compilation. This is possible with docker: (docker run -e KEY=VALUE ${IMAGE}) but is currently impossible to define in the SEP-58 format. I am unaware of any flag I can pass to stellar contract build or cargo build (see above comment) that will add env variables, they are expected to be set in the environment (or via docker run flags).

I would propose adding a bldenv section as well that allows KEY=VALUE pairs that will be appended via docker run -e flags. I am also open to other solutions. I feel some solution should exist for rebuilding those existing contracts, however you decide to implement it.

To make this more concrete, here are two examples:

• Peridot Finance - directly embeds the admin address via option_env! at build time. This ends up in the compiled wasm.
• PayD adds a user-defined BUILD_TIMESTAMP. That is recoverable from the wasm and could be replayed to reproduce the same wasm hash

If this is too complex a change, these cases could be discounted and must deploy newer contracts without env! to be SEP-58 reproducible. I only found a handful of cases that were not env! based on variables set by cargo or build.rs, but I have also not looked at every contract repo, just some samples.

I do think it is worth a discussion on how to handle these cases. However, the cargo vs stellar args issue above is a lot more common and affects maybe half the actively used deployed contracts on mainnet.

[chadoh]

@fnando that ignores the history of contracts already-deployed. Ethan is fact-finding to allow historic contracts to have on-chain (via Stellar Registry), fully-verified sources added to all contracts (or at least, many contracts), not just future contracts that implement the SEP. (Future contracts that are uploaded without the SEP metadata (whether or not they are upgradable) will also benefit from our system.)

See our full architecture for more detail or just watch my fun little explainer video:

[fnando]

I don't think I am. When I say we should not add another field (bldenv), that doesn't mean we shouldn't carry the metadata. In fact, I already have this working on the stellar contract build --verifiable and stellar contract verify draft prs. I'm carrying env vars with bldopt:--env=NAME=VALUE, as mentioned on my other comment.

$ ./stellar-cli/target/debug/stellar contract build --verifiable --image localhost:7000/stellar-cli@sha256:838ec70a26de4cebd48f8620372e3711fe30e479800b65c34b5943e0510ed644 --env A=1 --env B='this is very nice' --package hello-world --verbose

$ ../stellar-cli/target/debug/stellar contract info meta --wasm target/wasm32v1-none/release/hello_world.wasm
ℹ️ Loading contract spec from file...
Contract meta:
 • rsver: 1.95.0 (Rust version)
 • rssdkver: 26.1.0#175aa41306f383057a8cdfc84b68d931664fc34e (Soroban SDK version and its commit hash)
 • cliver: 26.1.0#1228cff8022b804659750b94b315932b0e0f3f6a
 • bldimg: localhost:7000/stellar-cli@sha256:838ec70a26de4cebd48f8620372e3711fe30e479800b65c34b5943e0510ed644
 • source_sha256: 693ca2141a7157384f9c87472336419d74f9a71f1db655c1c3e3fa0e7c29cb60
 • bldopt: --locked
 • bldopt: --package=hello-world
 • bldopt: --optimize
 • bldopt: --env=A=1
 • bldopt: --env=B='this is very nice'

$ ../stellar-cli/target/debug/stellar contract invoke --id hello-world -- show_env
ℹ️ Simulation identified as read-only. Send by rerunning with `--send=yes`.
["1","this is very nice"]

[fnando]

To complement my answer: anything that we add, will end up duplicated as a bldopt. We'd need a way of specifying the bldenv (for instance, with --env NAME=VALUE), which would end up as a bldopt as well. So instead of duplicating, we should rely on bldopt as much as possible.

[leighmcculloch]

An --env and using bldopt seems reasonable, there's also the possibility of using rustc's depinfo to automatically capture any compile-time env's that get read, and in that case a bldenv would be more convenient. We maybe should research rustc's depinfo to consider how else we may want to use, capture, or surface environmental dependencies not captured in the source.

But I don't think we should jump to either of those solutions just yet.

I'm interested to hear what else gets discovered through fact finding with other contracts because that may change the shape of what we want to do here.

[ethanfrey]

I found more contracts and noticed a few needed a custom CARGO_HOME for proper path info in the data section (paths for panics).

[leighmcculloch]

I'm posting a small update to SEP-58 that doesn't change the functional side of it, but makes part of the design rationale clearer that I realise on re-read of the proposal is not explicit:

• Clarify SEP-58 scope to common workflow #1964

This design rationale is the context behind statements I made at #1923 (reply in thread) and #1923 (reply in thread).

[saimeunt]

@leighmcculloch Thanks for clarifying SEP-58 with the common workflow, this is helpful to correctly scope the initial focus when designing a verifier.

While building a verifier prototype based on both SEP-58 and the upcoming verifier API SEP we tried to strictly follow the specs to see if they enable easy verifications for contracts strictly adhering to SEP-58 with adequate WASM metadata embedded.

Here’s what we found out:

• Producing contracts with correctly configured WASM metadata is now possible through the use of both stellar contract archive and stellar contract build --verifiable (stellar-cli#2585). These commands can be used as part of a build and release workflow to automatically produce the archive needed by SEP-58 source_uri and build a contract WASM with the appropriate metadata. Here’s an example repo implementing the aforementioned build and the resulting contract.
• Actual verification logic can be delegated to the stellar CLI with the stellar contract verify --wasm-hash WASM_HASHcommand (stellar-cli#2586). Out of band verification will need to follow a different path as verifying using the stellar-cli needs a WASM fully compliant with SEP-58 metadata (it errors when not found).
• The upcoming verifier API SEP is simple to implement (single endpoint) and versatile for multiple verification scenarios. The spec clearly outlines how to enqueue verifications using the GET /wasms/:wasm-hash.json endpoint and retrieve them when verification is settled later on.

In conclusion, the current revisions of both SEPs (SEP-58 and upcoming verifier API SEP) are mostly ready for verifiers implementations focused on contracts built/deployed with SEP-58 in mind (the common workflow). The standard path assuming SEP-58 compliant contracts is well defined while still allowing scenarios not fully covered by these SEPs (out-of-band verifications, legacy contracts, multiple verifiers, etc).

Resources:

• https://github.com/walnuthq/stellar-source-code-verification
• https://github.com/walnuthq/soroban-increment-contract
• https://walnuthq.github.io/stellar-source-code-verification

cc @fnando as it provides feedback on the stellar-cli commands you implemented and the verifier API SEP we're trying to implement in the verifier prototype.

[leighmcculloch]

@fnando One thing I'm not sure if we've quite nailed down is when verifying a contract if --meta fields should be passed or not.

For example, in SEP-58 it examples passing --meta bldopt=--optimize:

stellar-protocol/ecosystem/sep-0058.md

Lines 409 to 417 in 597d215

	$ docker run --rm -v "$PWD:/source" -e RUSTUP_TOOLCHAIN "$IMAGE" \
	contract build \
	--manifest-path=contracts/foo/Cargo.toml \
	--optimize \
	--meta bldimg="$IMAGE" \
	--meta bldopt=--manifest-path=contracts/foo/Cargo.toml \
	--meta bldopt=--optimize \
	--meta source_uri=https://example.com/my-contract-v1.0.0.tar.gz \
	--meta source_sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

There are meta fields written from:

1. Within the source, using contractmeta!(key="...", val="...").
2. Via a command line arg that had been specified explicitly, --meta.
3. Via the stellar-cli's own process, if the build occurred using a docker image.

Only meta from (2) should be repeated, otherwise multiple duplicate meta entries will appear. Even if duplicate meta entries are automatically reduced to a single entry doing so may result in the meta being encoded in a different order resulting in a different wasm hash.

Also, with regard to supporting non-stellar-cli builds such as those exampled in #1965, a --meta flag may not be supported.

How are the prototypes of the stellar-cli handling the meta in each of the three cases above?

[pabl0ramirez]

One open question listed here is how already-deployed contracts without embedded metadata get discovered and verified. A small observation from the consumer side: discovery and verification may deserve to be decoupled. Discovery (which deployed WASM hashes exist, which have any verification claim from any verifier, which have none) is a pure read problem that needs no trust decisions and could run today against the existing surface. Verification of the uncovered remainder then becomes a prioritized worklist rather than an unknown. Publishing that coverage number periodically would also give this SEP a progress metric: the fraction of live mainnet bytecode with at least one claim is currently unknown, and it is hard to improve a number nobody measures. We are looking at building exactly this census layer as a consumer of SEP-58 vocabulary and the registry API being discussed in #1945, and would welcome pointers if someone is already measuring it.

[Hollujay]

Following this thread with interest. We're building soroverify, a public verification service aimed at the SCF RFP for this same problem, and wanted to share something concrete instead of just saying "we're building this too."

On the bldimg trust question (@chan-lz's May 8 comment, and @mootz12's point on the CLI PR): we ran into this before finding this thread, landed on the same worry, and already have a working answer for it. Our verifier only replays a bldimg that's on an explicit, digest pinned allowlist. If the allowlist is empty or unset, everything gets rejected, nothing gets trusted by accident. This is built, tested (we have a test that checks zero exec calls happen for a disallowed image, not just that the response comes back as an error), and running against a real testnet contract right now. Happy to share the details if it's useful for how bldimg guidance ends up written into the spec. It's a SHOULD in the draft at the moment, and from actually building it, it didn't add much operator burden, so it might be worth being a stronger requirement.

On the sub thread between @chan-lz and @leighmcculloch about opaque or hostile build images: we don't have an answer for "the image itself is malicious" beyond the allowlist either, same gap named in the thread. But we think having several independent verifiers publish signed results for the same wasm hash helps in practice, since nobody has to trust one operator's allowlist alone. That's built into our design from the start, results are signed per verifier and keyed by wasm hash, and the API returns every verifier's result for a hash instead of assuming there's only one. Running your own verifier is meant to be a real, documented option, not an afterthought. Closer to the socket.dev style multi dimensional signal @leighmcculloch mentioned than a plain yes or no.

On @Chupsy's point about post deployment verification: this is the main thing we're solving for, not a side case. Since we verify by rebuilding submitted source against a hash that's already deployed, older non upgradable contracts work fine without any special handling. We checked this live against a contract we deployed ourselves to testnet and it just worked. Is there a writeup anywhere of the "verification registry pattern" in Appendix A.3, or is the thread and draft spec the best source right now?

On the meta spec itself: we built against an earlier version of the draft (separate bldopt_profile and bldopt_optimize fields, rsver kept apart from bldimg) and saw @leighmcculloch's May 8 update collapsing that into one repeating bldopt field and dropping cliver. We're updating our side to match. Is there a good way to get notified of future spec changes besides just watching this thread?

Repos if it helps, both have real commit history and tests behind them, not just a proposal: https://github.com/soroverify/soroverify-verifier, https://github.com/soroverify/soroverify-consume. Happy to go deeper on any of this, or open a separate thread if that's better than piling on here.

[leighmcculloch]

Is there a good way to get notified of future spec changes besides just watching this thread?

Subscribing to the stellar/stellar-protocol repo in general is the right place right now, both so that you received updates to new pull requests that modify the SEP and these discussions. Unfortunately notifications cover everything happening in this repo.

[Hollujay]

Thanks, subscribing now. Will keep tracking the spec changes and update our side as they land.