Add container build backend and build verify command by leighmcculloch · Pull Request #2525 · stellar/stellar-cli

leighmcculloch · 2026-04-27T15:53:35Z

What

Add --backend docker[=<image>] to stellar contract build (and deploy/upload) that runs the entire build pipeline inside a container whose entrypoint is stellar. Add a stellar contract build verify subcommand that reads everything it needs from the wasm's metadata, rebuilds, and reports which (if any) rebuilt artifact is byte-identical to the original. Add a mainnet warning on stellar contract deploy when the wasm is missing the meta entries needed for independent verification.

Why

Contract builds vary across host OS, architecture, and toolchain, preventing third parties from independently confirming a deployed contract was built from given source. Pinning the build to a docker image plus the rust toolchain version makes builds reproducible, recording the source repo + commit + per-package build options lets verifiers rebuild the exact same artifact, and the new verify subcommand automates the rebuild-and-compare check.

Closes #2506.

How it works

Three parts: build-time recording, deploy-time warning, and verify-time reproduction.

Build

stellar contract build --backend local                          # default; host build
stellar contract build --backend docker                         # build inside docker.io/stellar/stellar-cli@sha256:...
stellar contract build --backend docker=stellar/stellar-cli:26.0.0
stellar contract build --backend docker=quay.io/myorg/myimage@sha256:...

For all backends (including local), the build:

Detects whether the workspace is a clean git checkout. If clean and there's an origin remote, embeds source_repo (URL canonicalized to https://…), source_rev (full HEAD SHA), and per-package build options (bldopt_manifest_path relative to git root, bldopt_package, bldopt_profile, optional bldopt_optimize). The manifest path is auto-inserted whether or not --manifest-path was passed on the CLI.
If the working tree has uncommitted changes, prints a warning and omits source_repo / source_rev / bldopt_*.
If not a git repo, silently omits.

For --backend docker, additionally:

Resolves the requested image. Default is docker.io/stellar/stellar-cli@sha256:cb2fc3116a6ace37a77ca6bb88afb4bee57fc746cd556a4373f2c3ee95d4e917 — pinned by digest so the recorded bldimg is reproducible from day one and we sidestep the longstanding Apple Silicon docker quirk where pulling a multi-arch tag with --platform=linux/amd64 leaves RepoDigests empty after pull.
Pulls the image (skipping the pull if it's already locally present, since digest-pinned references are immutable).
Bind-mounts on the container:
- <git_root or workspace_root> → /source (rw, source — also where cargo writes its target dir, shared with the host)
- host ~/.cargo/registry → /usr/local/cargo/registry (rw, cached crate downloads)
The container runs as the host uid:gid, so files written to the bind mount are readable/writable by the host user.
Overrides the image's entrypoint to invoke stellar directly, bypassing the official image's entrypoint.sh (which launches dbus + gnome-keyring and trips when running under a host UID with no /etc/passwd entry — see Docker image's entrypoint dbus init fails when run as non-root UID #2543). contract build doesn't use the keyring, so the wrapper is irrelevant here.
Runs stellar contract build --manifest-path /source/<rel> --profile <p> --locked --meta bldimg=<digest> [forwarded args] inside the container. The args use only flags that exist in published stellar/stellar-cli images today; no new flags are added, and --backend local is deliberately not passed (it's a flag added in this PR and isn't recognized by published images).
The in-container cli does cargo + meta injection + spec filtering + optional wasm-opt itself; the host only orchestrates and copies outputs to --out-dir if requested.

The wasm's contractmetav0 custom section is populated with up to nine entries:

key	value	regex (validation)	injected by
`cliver`	`26.0.0#abc1234…` (CLI version + git rev)	`^\d+\.\d+\.\d+(-[A-Za-z0-9.+-]+)?#([0-9a-f]{40}(-dirty)?)?$`	stellar-cli
`bldimg`	`docker.io/stellar/stellar-cli@sha256:…`	`^[^@\s]+@sha256:[0-9a-f]{64}$`	stellar-cli (this PR; only with `--backend docker`)
`rsver`	`1.83.0` (resolved rustc version)	`^\d+\.\d+\.\d+(-[A-Za-z0-9.+-]+)?$`	soroban-sdk
`source_repo`	`https://github.com/user/repo` (clean repo's origin)	`^https?://\S+$`	stellar-cli (this PR)
`source_rev`	full 40-char HEAD SHA	`^[0-9a-f]{40}$`	stellar-cli (this PR)
`bldopt_manifest_path`	e.g. `contracts/foo/Cargo.toml` (relative to git)	`^([^/\s]+/)*Cargo\.toml$`	stellar-cli (this PR)
`bldopt_package`	cargo package name being built	`^[A-Za-z][A-Za-z0-9_-]*$`	stellar-cli (this PR)
`bldopt_profile`	cargo profile (e.g. `release`)	`^[A-Za-z][A-Za-z0-9_-]*$`	stellar-cli (this PR)
`bldopt_optimize`	`true` (only present when `--optimize` was used)	`^true$`	stellar-cli (this PR)

The presence of bldimg is what distinguishes a docker build from a local one — there's no separate bldbkd field. For full reproducibility from day one, pin to a specific image with --backend docker=<name>@sha256:… and commit before building.

--backend and --docker-host are also exposed on stellar contract deploy and stellar contract upload (which auto-build when no --wasm / --wasm-hash is given), so the same flags work end-to-end.

Deploy

stellar contract deploy against mainnet now warns when the wasm is missing any of cliver, bldimg, rsver, source_repo, source_rev, bldopt_manifest_path, bldopt_package, bldopt_profile:

⚠ the wasm being deployed is missing reproducibility meta entries: ["bldimg", "source_repo", "source_rev", "bldopt_manifest_path", "bldopt_package", "bldopt_profile"]. The deployed wasm may not be independently verifiable. To make it reproducible, build with `stellar contract build --backend docker` in a clean git repository.

The check is mainnet-only (matches network passphrase against Public Global Stellar Network ; September 2015); on testnet/futurenet/local the wasm deploys silently.

Verify

verify is a subcommand of build — it lives at stellar contract build verify, and works on multi-contract workspaces by rebuilding and finding the match.

stellar contract build verify --contract-id CXXX… --network mainnet
stellar contract build verify --wasm-hash <hash>  --network mainnet
stellar contract build verify --wasm contract.wasm

Fetches the original wasm (file path, hash, or contract id, same flags as contract info).
Reads cliver, bldimg (optional), rsver, and bldopt_* (optional, best-effort) from the wasm's meta. Missing bldopt_* entries trigger a warning rather than an error and the build falls back to its defaults — verify still runs, just with the caveat that the rebuild may not be reproducible.
Picks the rebuild backend from the meta:
- bldimg present → Backend::Docker { image: bldimg }. The image's pinned digest pulls the same in-container cli that produced the original.
- bldimg absent → Backend::Local. Best-effort rebuild on the host.
Forwards the wasm's rsver to the rebuild as RUSTUP_TOOLCHAIN (in-container) or cargo +<rsver> (local). For docker the toolchain inside the image is fixed by whoever built it; passing RUSTUP_TOOLCHAIN lets rustup-managed cargo switch toolchains if the image carries multiple ones.
Resolves bldopt_manifest_path against the cwd's git top-level (via git rev-parse --show-toplevel) so verify works from anywhere inside the checkout.
Hashes every rebuilt artifact and looks for a match against the original. Prints ✅ on match (with the matching crate's name); ⚠ + non-zero exit on mismatch (with each rebuilt artifact's name + hash).

The user is responsible for checking out the matching commit before running verify; verify rebuilds from the working tree. (source_repo and source_rev are embedded in meta to help users find the right commit, but verify itself doesn't clone — that would add a separate trust path.)

End-to-end example

$ stellar contract build --backend docker
ℹ Pulling from stellar/stellar-cli
   Digest: sha256:cb2fc3116a6ace37a77ca6bb88afb4bee57fc746cd556a4373f2c3ee95d4e917
   Status: Image is up to date for stellar/stellar-cli@sha256:cb2fc3...
ℹ contract build --manifest-path /source/contracts/foo/Cargo.toml --profile release --locked --meta bldimg=docker.io/stellar/stellar-cli@sha256:cb2fc3...
   Compiling foo v…
    Finished `release` profile [optimized] target(s) in 1.09s
ℹ Build Summary:
   Wasm File: target/wasm32v1-none/release/foo.wasm (907 bytes)
   Wasm Hash: 9f86d081…
✅ Build Complete

$ stellar contract info meta --wasm target/wasm32v1-none/release/foo.wasm
cliver=26.0.0#abc1234
bldimg=docker.io/stellar/stellar-cli@sha256:cb2fc3...
rsver=1.83.0
source_repo=https://github.com/user/my-contract
source_rev=abc1234567890abcdef…
bldopt_manifest_path=contracts/foo/Cargo.toml
bldopt_package=foo
bldopt_profile=release

# Later, on a different machine, with the matching commit checked out:
$ stellar contract build verify --wasm-hash <hash> --network mainnet
ℹ Loading contract from network...
ℹ Loading meta from contract...
   Original wasm hash: 9f86d081…
   stellar-cli version: 26.0.0#abc1234
   rust version: 1.83.0
   Docker image: docker.io/stellar/stellar-cli@sha256:cb2fc3...
   Manifest path: contracts/foo/Cargo.toml
   Package: foo
   Profile: release
ℹ contract build --manifest-path /source/contracts/foo/Cargo.toml --profile release --locked --meta bldimg=docker.io/stellar/stellar-cli@sha256:cb2fc3...
   Compiling foo v…
✅ Build Complete
✅ Verified: rebuilt foo wasm matches 9f86d081…

The host CLI's version is irrelevant for verifying a docker-built wasm — whatever cli is in the image is what built (and rebuilds) the wasm.

Notes

Communication with the daemon: bollard's HTTP API over the docker socket (/var/run/docker.sock, or whatever --docker-host / DOCKER_HOST points at). Same connect_to_docker helper used by stellar container start/stop/logs, with the same Docker Desktop fallback ($HOME/.docker/run/docker.sock). No shell-out to the docker CLI. A podman socket exposing the Docker API would also work (untested).
Default image is digest-pinned: --backend docker (no =...) defaults to docker.io/stellar/stellar-cli@sha256:cb2fc3..., not stellar/stellar-cli:latest. Recording a digest immediately makes builds reproducible day one and avoids the Apple Silicon RepoDigests-after-cross-platform-pull quirk. Bumping the default is a single-line const change in build.rs (see comments there for the recipe). Users who want a different image specify --backend docker=....
Entrypoint override: the official stellar/stellar-cli image's entrypoint runs entrypoint.sh, which launches dbus + gnome-keyring. That setup fails when the container runs as a host UID without an /etc/passwd entry — see Docker image's entrypoint dbus init fails when run as non-root UID #2543. We override the entrypoint to point straight at the stellar binary, which is fine because contract build doesn't touch the keyring.
Caching: the bind-mount of host ~/.cargo/registry lets the container reuse crate downloads the host already has.
Wasm target installation: deferred to the image. The official image has wasm32v1-none pre-installed for its default toolchain; if RUSTUP_TOOLCHAIN selects a different one (verify on a wasm built with another rust version), the cli/cargo handle target installation themselves.
Toolchain pinning: verify sets RUSTUP_TOOLCHAIN=<rsver> inside the container (and cargo +<rsver> for local rebuilds) so the rust version matches whatever the original build used.
Image fully-qualified: bldimg is normalized to <registry>/<path>@sha256:<digest> (e.g. stellar/stellar-cli:latest → docker.io/stellar/stellar-cli@sha256:…) so verify can resolve it without relying on the local registry config.
Source URL canonicalization: source_repo is normalized to https://… form (e.g. git@github.com:user/repo.git → https://github.com/user/repo).
Build options auto-recorded: bldopt_manifest_path is recorded relative to the git repo root regardless of whether --manifest-path was passed on the CLI. Verify resolves it against the cwd's git top-level so the command works from anywhere inside the checkout.
No new in-container flags: the host invokes stellar contract build inside the image with only flags that exist in published stellar/stellar-cli images today (--manifest-path, --profile, --locked, --meta, --package, --features, --all-features, --no-default-features, --optimize). bldimg is forwarded via --meta bldimg=<digest>, not a new flag.
No bldbkd field: presence of bldimg is the only signal needed to distinguish a docker build from a local one.
Aborted container runs: may leave a stopped container; clean with docker container prune.

Performance/runtime caveats

Building inside an amd64 container on a non-amd64 host (Apple Silicon, Linux/arm64) runs under emulation. For small contracts the difference is negligible; for workspaces with heavy dep trees the emulated build can be substantially slower than a native host build. Container runtimes that don't ship qemu/binfmt support won't run amd64 containers on arm64 hosts at all. See #2506 (comment).

Related issues

Normalize stellar-cli version rendering in stellar version and cliver meta #2535 — normalize cliver rendering across install paths so it's a single shape.
Docker image's entrypoint dbus init fails when run as non-root UID #2543 — the official stellar/stellar-cli image's entrypoint.sh fails under non-root UIDs, motivating the entrypoint override here.

Status

This is an experiment in validating the ideas in #2506. May or may not be destined for merging — at this moment it's an experiment in validating the approach.

… bldimg

leighmcculloch · 2026-05-01T13:10:11Z

Opened an issue about dbus creating problems with using the image for the build for the verification step:

Docker image's entrypoint dbus init fails when run as non-root UID #2543

fnando · 2026-05-01T17:05:46Z

@leighmcculloch I just tried this, but I'm getting a warning, even though there are no unstaged files.

$ git status
On branch main
nothing to commit, working tree clean

$ stellar contract build --backend docker
⚠️ git working tree has uncommitted changes; source_repo/source_rev/bldopt_* not embedded in contract metadata. Commit changes for a reproducible build.

mootz12 · 2026-05-05T14:30:56Z

+        }
+
+        let backend = match bldimg {
+            Some(image) => build::Backend::Docker { image },


bldimg needs some form of allowlist, e.g. docker.io/stellar/stellar-cli@sha256:*, otherwise I can inject a docker image that bypasses verification

mootz12 · 2026-05-05T14:40:24Z

+            }
+        });
+
+        let build_cmd = build::Cmd {


Do we need feature flags here? While not extremely common, I have used them in the past to reduce code duplication between similar contracts. Ref -> https://github.com/script3/soroban-governor/tree/main/contracts/votes

mootz12 · 2026-05-05T14:42:44Z

+    // - The official `stellar/stellar-cli` image's stock entrypoint is a
+    //   wrapper script that launches dbus + gnome-keyring before exec-ing
+    //   `stellar`; that setup is irrelevant for `contract build` and dbus
+    //   refuses to start when the container runs as a host UID with no
+    //   `/etc/passwd` entry. Skipping it keeps the host UID mapping intact.


This was cleaned up in a recent PR. Does this simplify anything?

mootz12 · 2026-05-05T14:58:23Z

+        attach_stdout: Some(true),
+        attach_stderr: Some(true),
+        host_config: Some(HostConfig {
+            binds: Some(binds),


Have we considered removing the host bind mounts? Given verify will build untrusted code, it might be best if we keep the build artifacts within the container, then just extract the WASM file out.

We could consider having two configurations docker-build and docker-verify, where build keeps mounts to help speed up repeated builds and verify is more black-box to provide a bit more protection.

mootz12 · 2026-05-05T15:00:05Z

+        let cliver = find_meta(&spec.meta, "cliver").ok_or(Error::MissingMeta("cliver"))?;
+        let bldimg = find_meta(&spec.meta, "bldimg");
+        let rsver = find_meta(&spec.meta, "rsver").ok_or(Error::MissingMeta("rsver"))?;
+        let bldopt_manifest_path = find_meta(&spec.meta, "bldopt_manifest_path");
+        let bldopt_package = find_meta(&spec.meta, "bldopt_package");
+        let bldopt_profile = find_meta(&spec.meta, "bldopt_profile");
+        let bldopt_optimize = find_meta(&spec.meta, "bldopt_optimize").is_some();


we should enforce the regex here

leighmcculloch added 4 commits April 27, 2026 14:14

add --docker build flag and verify command

c903c42

fix path remap; pass docker-host to verify; tests

f135de0

minimise diff against main

77225ef

update path mounts to workspace

3108cae

github-project-automation Bot added this to DevX Apr 27, 2026

github-project-automation Bot moved this to Backlog (Not Ready) in DevX Apr 27, 2026

leighmcculloch added 24 commits April 28, 2026 01:53

Merge branch 'main' into feat/reproducible-builds-via-docker

b989282

remove network mode setting

b860a4f

add rustup toolchain to build command

144ad93

rustfmt

663f136

use cargo +toolchain to pin rust version on verify

aaccd73

bind-mount cargo registry and rustup state from host

c002c91

rename --docker to --backend with local|docker[=image]; fully-qualify…

b06473f

… bldimg

remove docker image override on verify

e5bba0e

verify: print cliver/rsver/bldimg from meta

956487a

verify: 'wasm sha256' -> 'wasm hash'

79c5bb3

verify: friendlier labels for meta values

d63894c

refactor build backend handling to use container logic

554c10c

verify: indent meta lines; drop blank line after build complete

527bf05

build: blank line between successive contract builds

ab6b9b3

container: emit cargo output raw, force CARGO_TERM_COLOR=always

0022b2d

container: re-add info prefix on docker pull progress lines

18332ef

container: emoji on first pull line, blankln continuations

1adb2b2

verify: add 'Loading meta from contract' header

7ff2f48

update logging messages for contracts

b285a68

container: always install wasm target before build

216fed1

container: allow too_many_arguments on run_in_container

1f168b6

update build container commands

0455f17

verify: use Print for verdict lines

af097d1

verify: enforce single contract per invocation; pre-check workspace

0b886a6

leighmcculloch added 3 commits May 1, 2026 12:42

add tar and http-body-util dependencies

edc5397

update crate git revision handling

42351b1

stream build output directly

c5e982a

This comment was marked as outdated.

Sign in to view

leighmcculloch added 11 commits May 1, 2026 16:00

refactor verify to use backend metadata

c8a1000

docker backend: run stellar inside stellar-cli image

8c08643

revert files unrelated to docker backend

7970c1d

Merge branch 'main' into feat/reproducible-builds-via-docker

60cec82

record bldbkd; forward via --meta from docker host

237557e

pin default docker image to digest

e9b6ca0

skip pull if image already local

d3be20c

drop bldbkd meta; bldimg presence signals docker

890de29

tolerate missing bldopt_* meta in verify

47e4900

use image's stellar entrypoint, drop wasm target preflight

8ae04b9

override entrypoint to stellar to skip dbus init

5adb3d4

leighmcculloch mentioned this pull request May 1, 2026

Docker image's entrypoint dbus init fails when run as non-root UID #2543

Closed

leighmcculloch added 5 commits May 2, 2026 00:07

document reproducibility via build metadata

9fe17bc

forward source/bldopt meta from host on docker builds

cd443d2

entrypoint installs wasm target before stellar

0006b28

update rust target add command

3a2b587

rename contract verification to draft specification

68d8325

leighmcculloch added 5 commits May 4, 2026 14:27

make source_repo/source_rev optional, add registry example

362c626

allow externally-supplied build params for legacy wasms

357ae59

registry source delivery is flexible (meta or upload)

8df560d

introduce source upload flexibility

821cc88

mark which meta entries are required per class

7c876a9

mootz12 reviewed May 5, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add container build backend and build verify command#2525

Add container build backend and build verify command#2525
leighmcculloch wants to merge 71 commits intomainfrom
feat/reproducible-builds-via-docker

leighmcculloch commented Apr 27, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

leighmcculloch commented May 1, 2026 •

edited

Loading

Uh oh!

fnando commented May 1, 2026

Uh oh!

mootz12 May 5, 2026

Uh oh!

mootz12 May 5, 2026

Uh oh!

mootz12 May 5, 2026

Uh oh!

mootz12 May 5, 2026

Uh oh!

mootz12 May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

leighmcculloch commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How it works

Build

Deploy

Verify

End-to-end example

Notes

Performance/runtime caveats

Related issues

Status

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

leighmcculloch commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fnando commented May 1, 2026

Uh oh!

mootz12 May 5, 2026

Choose a reason for hiding this comment

Uh oh!

mootz12 May 5, 2026

Choose a reason for hiding this comment

Uh oh!

mootz12 May 5, 2026

Choose a reason for hiding this comment

Uh oh!

mootz12 May 5, 2026

Choose a reason for hiding this comment

Uh oh!

mootz12 May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

leighmcculloch commented Apr 27, 2026 •

edited

Loading

leighmcculloch commented May 1, 2026 •

edited

Loading