Contract build verification

1. Inspect a deployed contract

Open the contract in the Atlas explorer and choose Check build. To confirm a specific release, open Verify my build and enter the full commit and Wasm SHA-256. For automated checks, use the contract C-address with the provenance endpoint. This checks signed build provenance. Use the Reflector DAO Mainnet contract below as a reference with a published attestation.

curl -q --include --fail-with-body --connect-timeout 5 --max-time 60 \
  'https://api.stellaratlas.io/v1/contracts/CBQSUF57OYX4RIMCZV62DKN6JFOTEKPHIZASMJYOUOCNHGNG2P3XQLSE/provenance'

The Reflector DAO v1.1.0 release has Wasm SHA-256 f60d33ec57eecee04b52d048c1c079983ff1b3834c8195fea811b025fb889361 and an attestation for source commit ac9740f12a50a81c1b96d1e8d929a6066d2d00a8. Compare the response’s wasmSha256 before using that reference. For the same digest, a verified result should name that commit in build.record.commit. The contract can be upgraded and the lookup can return an unresolved result.

Replace the address with your contract. Save networkPassphrase, observedLedger, checkedAt, wasmSha256, build.status and ledgerEvidence (if present) together. The observed ledger may not be the current network head. An upgrade can change the executable and digest.

ledgerEvidence set to configured_rpc_observation identifies a configured RPC observation, not an independent ledger-state proof. Native responses may omit this field. An absent or unrecognized value does not establish independent proof. Read build.status separately for the attestation outcome.

2. Make a build discoverable

Publish a GitHub artifact attestation from a publicly readable repository. Atlas looks up the signed evidence by the repository embedded in the deployed Wasm and the deployed Wasm’s SHA-256.

1. Embed source_repo=github:YOUR_ORG/YOUR_REPO in the Wasm metadata before building the artifact you deploy. This checker accepts that repository form, without a branch or commit suffix. See the contract metadata specification.
   ExampleCopy code

   stellar contract build --meta source_repo=github:YOUR_ORG/YOUR_REPO

2. Use the repository’s GitHub Actions build to publish artifact provenance for the final Wasm bytes, including any optimization and metadata. Grant the job id-token: write and attestations: write, and give the attestation step the final Wasm as its subject-path. Deploy that same file. The Reflector DAO reference workflow run produced the published attestation used above.
   ExampleCopy code

   # Run with the final artifact from the release workflow
   gh attestation verify path/to/final.wasm -R YOUR_ORG/YOUR_REPO
   sha256sum path/to/final.wasm

3. The supported bundle uses in-toto Statement v1, SLSA provenance v1 and GitHub workflow build provenance. Repository, source commit, workflow identity, certificate and transparency evidence must match. The source commit comes from verified provenance, not a metadata claim alone.
4. After publication, open Verify my build on your contract page. Paste the full commit from the workflow run and the SHA-256 printed above, then select Verify build. Atlas reports a match only if it validates signed evidence for both values. Use Check again after correcting or publishing evidence. Native contract observations can be retained for one minute, and build outcomes for up to thirty minutes. Repeated requests do not force a fresh build check.

3. Handle verified and unresolved results

HTTP 200 means an evidence response was returned. Read build.status before displaying a verification badge. The API has no separate mismatch or unverified status; preserve the specific result below.

HTTP 400 with invalid_contract requires a valid C-address. HTTP 503 with verification_busy or contract_evidence_unavailable is a request failure; honor Retry-After before a deliberate retry. It is different from a successful response containing build.status=unavailable. A client timeout is also unresolved, not evidence of an invalid contract.

4. Keep the trust boundaries visible

For verified, follow build.record.sourceUrl to the exact commit and workflowUrl to its build workflow. runUrl can be null; attestationUrl locates the repository’s evidence for the digest. Other build outcomes have a null record. Embedded repository and home-domain metadata remain developer-supplied claims.

Build attested means the provenance check accepted the signed build for the observed Wasm. For a source-to-Wasm match, rebuild with pinned inputs and compare the complete output bytes. The offline recipe below uses a separate historical fixture. Contract safety and ledger-state inclusion require separate evidence. securityAudit remains not_assessed.

5. Reproduce a controlled build offline

This historical example uses existing Cargo and Stellar tools. It requires no hosted executor or GitHub Actions. Build attested describes accepted signed provenance; independently reproduced describes a separate byte comparison. The provenance API does not run this recipe or return a reproduction status.

Prepare and identify the inputs

Obtain the Stellar CLI source at commit 067b5a7c6084fdcd7900f2bf5d8af85df3898cae, preserving its upstream Apache-2.0 licensing. Use package test_hello_world 21.3.0 at cmd/crates/soroban-test/tests/fixtures/test-wasms/hello_world. Keep the upstream contract, its manifest, the tracked .cargo/config.toml and the test-wasms profile unchanged. The SDK is pinned to soroban-sdk =21.2.0.

In this repository, examples/contract-build-reproduction/ supplies the exact derived root Cargo.toml, Cargo.lock and wasm-target.sha256. Replace only the upstream root manifest and lock with these files. The derived workspace selects this fixture alone; 154 external dependency identities retain their original versions, sources and checksums. It is a deliberately narrowed recipe, not an unchanged CLI workspace build.

# In the prepared upstream source root, after replacing the two files:
printf '%s  Cargo.toml
%s  Cargo.lock
' \
 'cd8cc44a5c0b8cd814fe572db1ee2e13d5900576266091aa4fa8e35d8d329cb0' \
 'a9322ef77cbd1b45e6aea5e71474dcdd02ef6058d605c4895f8fa1d2fec88954' | sha256sum --check

Prepare a standard Cargo registry cache against this lock before disconnecting. The measured normal/build graph used 59 registry packages, including native build scripts and procedural macros; another 79 packages supported offline resolution/metadata, not the compiled feature graph. Keep package archives, extracted sources and registry index records. Check archive checksums against the lock. Do not fetch the unrelated full CLI workspace or replace registry sources with a different vendor configuration.

Use Linux amd64 and the image digest below. Its native compiler is GCC 12.2 with GNU ld 2.40. The image does not include the Wasm target: supply the matching Rust 1.80.1 wasm32-unknown-unknown target separately and check all 27 files with sha256sum --check wasm-target.sha256 from its root. Supply the exact Stellar optimizer binary separately. These retained binary hashes identify the tested tools; rebuilding the same version string alone does not establish identical tool bytes.

docker.io/library/rust@sha256:883df89a3ed53fb0e0f6a67d79cfebf72906d97f9d816379fdf941af969be1b5

The optimizer is Stellar CLI 21.3.0 with the opt feature, embedding wasm-opt 0.114.2, aggressive size optimization and convergence, with MVP, MutableGlobals and SignExt. This CLI build does not accept modern contract build --locked or --image flags. Use the frozen Cargo step followed by the final optimizer below.

Build only from prepared inputs

For each attempt, start a fresh isolated container from the pinned image, with an empty target directory and fixed paths. Mount source read-only at /source, the prepared registry read-only at /deps/registry, and the optimizer read-only at /tools/stellar. Mount the checked target read-only at /usr/local/rustup/toolchains/1.80.1-x86_64-unknown-linux-gnu/lib/rustlib/wasm32-unknown-unknown. Make /build a fresh writable, executable 4 GiB tmpfs; native build scripts and procedural macros execute there.

Run as UID/GID 1000:1000 with a read-only root filesystem, network disabled, private IPC, all capabilities dropped, no-new-privileges and the default seccomp policy. Limit each attempt to one CPU, 4 GiB memory with no additional swap, 128 PIDs and 15 minutes; cap logs at 8 MiB and the final artifact at 1 MiB. Mount no credentials, Docker socket, reference artifact or previous output. Review source before allowing its build scripts to execute.

The following are commands inside that prepared sandbox. Stop on any nonzero exit. Apply the displayed clean environment to both processes; unset ambient Rust flags, compiler wrappers and toolchain overrides. The tracked Cargo configuration remains active because the working directory is /source. Do not install tools, pull images or download dependencies during this phase.

set -eu
mkdir -p /build/home /build/tmp /build/cargo-home /build/final
ln -s /deps/registry /build/cargo-home/registry
cd /source
run_clean() { env -i \
 PATH=/usr/local/rustup/toolchains/1.80.1-x86_64-unknown-linux-gnu/bin:/usr/bin:/bin \
 HOME=/build/home TMPDIR=/build/tmp CARGO_HOME=/build/cargo-home \
 CARGO_TARGET_DIR=/build/target CARGO_NET_OFFLINE=true CARGO_BUILD_JOBS=1 \
 RUSTC=/usr/local/rustup/toolchains/1.80.1-x86_64-unknown-linux-gnu/bin/rustc \
 CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=/usr/bin/cc \
 SOURCE_DATE_EPOCH=1723217212 TZ=UTC LANG=C "$@"; }
run_clean /usr/local/rustup/toolchains/1.80.1-x86_64-unknown-linux-gnu/bin/cargo rustc \
 --frozen --offline \
 --manifest-path=/source/cmd/crates/soroban-test/tests/fixtures/test-wasms/hello_world/Cargo.toml \
 --package=test_hello_world --crate-type=cdylib \
 --target=wasm32-unknown-unknown --profile=test-wasms

# Only after Cargo exits successfully, under the same clean environment:
run_clean /tools/stellar contract optimize \
 --wasm=/build/target/wasm32-unknown-unknown/test-wasms/test_hello_world.wasm \
 --wasm-out=/build/final/test_hello_world.optimized.wasm

Compare the final bytes

Export the final optimized file before removing each container. Save the source, recipe, tool and dependency identities with the output. Compare the entire final files, including metadata and custom sections; a digest is a useful identity check, while cmp performs the full-byte comparison.

# Export final optimized bytes only after each successful build.
sha256sum reference.wasm rebuilt.wasm
cmp --silent reference.wasm rebuilt.wasm
# cmp: 0 = exact match; 1 = mismatch; >1 = comparison error.
# Check its exit status; do not strip or normalize either file.

A and B were actual separate clean builds on the same operator’s host. C changed only the first symbol_short!("Hello") literal to symbol_short!("Hallo") before another successful build. The last row appended an empty custom section to A without another build. All four outputs passed WebAssembly structural/type validation; no Soroban host loading or contract invocation was tested.

A is a newly authored local reference, not a publisher artifact or a deployed contract. B matching A demonstrates repeatability under these controlled inputs. It does not establish independent operators, source authenticity, compiler correctness, safe behavior or a security audit. Fresh-machine bootstrap, current-network compatibility, publisher attestation and deployed identity were not tested.

Record not_run when a required input is missing, the recipe is invalid, a build or optimizer fails, or a timeout prevents a final comparison. Only successful final outputs can yield a match or mismatch; a mismatch alone does not establish malicious behavior. If exact historical inputs cannot be obtained, retain not_run for this recipe and qualify a different pinned recipe with its own reference.