Skip to content

Add --verifiable flag to stellar contract build #2585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
fnando wants to merge 21 commits into
base: main
Choose a base branch
from
Draft

Add --verifiable flag to stellar contract build #2585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
ce9e15e
Add --verifiable flag to stellar contract build.
fnando May 21, 2026
7890d82
Record every build-affecting flag as bldopt.
fnando May 21, 2026
eecf56f
Remove duplicate 'contract build' in container error hint.
fnando May 21, 2026
5270c89
Probe container cli version for --optimize syntax.
fnando May 21, 2026
8a79f63
Add SEP-58 source-id flags to --verifiable.
fnando May 21, 2026
e2ab0ea
Move --locked info banner after validation.
fnando May 21, 2026
cb0d34a
Group --docker-host under Verifiable on contract build.
fnando May 22, 2026
9ea1395
Plumb verbose flag through run_in_container.
fnando May 22, 2026
bb8efd4
Capitalize info and warn messages on verifiable build.
fnando May 22, 2026
5a0d227
Rewrite docker pull status lines for clarity.
fnando May 22, 2026
abc9d82
Anchor verifiable build bind-mount to git root or cwd.
fnando May 22, 2026
4910384
Pull bldimg when --image is set.
fnando May 22, 2026
e78536c
Avoid duplicate Image prefix in pull status.
fnando May 22, 2026
ebe0861
Factor enforce_hardened_tree out of fix_config_permissions.
fnando May 22, 2026
3681fdf
Generate source archive for verifiable builds.
fnando Jun 17, 2026
eb250a5
Record each contract's package in verifiable builds.
fnando Jun 17, 2026
f699cfd
Document reproducible source archive guarantees.
fnando Jun 17, 2026
1cb6979
Add stellar contract archive command.
fnando Jun 17, 2026
d0831dc
Add --env to set build environment variables.
fnando Jun 17, 2026
1780110
Pin the rust toolchain in verifiable builds.
fnando Jun 18, 2026
2200ab0
Build source archives from the working directory.
fnando Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1,681 changes: 801 additions & 880 deletions Cargo.lock
View file
Open in desktop

Large diffs are not rendered by default.

34 changes: 25 additions & 9 deletions FULL_HELP_DOCS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ Tools for smart contract developers
- `asset` — Utilities to deploy a Stellar Asset Contract or get its id
- `alias` — Utilities to manage contract aliases
- `bindings` — Generate code client bindings for a contract
- `archive` — Generate the reproducible source archive used by verifiable builds
- `build` — Build a contract from source
- `extend` — Extend the time to live ledger of a contract-data ledger entry
- `deploy` — Deploy a wasm contract
Expand Down Expand Up @@ -343,6 +344,17 @@ Generate PHP bindings

**Usage:** `stellar contract bindings php`

## `stellar contract archive`

Generate the reproducible source archive used by verifiable builds

**Usage:** `stellar contract archive [OPTIONS]`

###### **Options:**

- `-o`, `--out-file <OUT_FILE>` — Where to write the gzipped tarball. Required unless `--dry-run` is used
- `--dry-run` — List the entries that would be archived and the computed source_sha256, without writing any file

## `stellar contract build`

Build a contract from source
Expand Down Expand Up @@ -383,6 +395,7 @@ To view the commands that will be executed, without executing them, use the --pr
If ommitted, wasm files are written only to the cargo target directory.

- `--locked` — Assert that `Cargo.lock` will remain unchanged
- `--env <ENV>` — Set an environment variable for the build (repeatable), e.g. `--env NAME=VALUE`. It's set on the build process; for a verifiable build it's passed to the container and recorded as a `bldopt`, so avoid secrets there
- `--optimize <OPTIMIZE>` — Optimize the generated wasm. Enabled by default; pass `--optimize=false` to disable. Requires the `additional-libs` feature

Default value: `true`
Expand All @@ -393,6 +406,14 @@ To view the commands that will be executed, without executing them, use the --pr

- `--print-commands-only` — Print commands to build without executing them

###### **Verifiable:**

- `--verifiable` — Build inside a trusted Docker container and record SEP-58 metadata (`bldimg`, `source_uri`, `source_sha256`, `bldopt`) so the resulting WASM can be reproduced and verified by third parties. Implies `--locked`. Requires a clean git working tree
- `--image <IMAGE>` — Override the auto-selected container image used by `--verifiable`. Must be digest-pinned, e.g. `docker.io/stellar/stellar-cli@sha256:...`. Tag-only refs are rejected because SEP-58 requires content addressing
- `--source-sha256 <SOURCE_SHA256>` — SEP-58 source identification: SHA-256 of the source archive (recorded as the `source_sha256` meta entry). Optional with `--verifiable`: the archive is always generated and its SHA-256 computed for you. When supplied it's treated as a pin — the build fails if it doesn't match the generated archive
- `--source-uri <SOURCE_URI>` — SEP-58 source identification: URI where the source can be obtained, e.g. `https://example.com/src.tar.gz` (recorded as the `source_uri` meta entry). Optional; when set it must accompany `--source-sha256`
- `-d`, `--docker-host <DOCKER_HOST>` — Override the default docker host used by `--verifiable`

## `stellar contract extend`

Extend the time to live ledger of a contract-data ledger entry.
Expand Down Expand Up @@ -480,6 +501,7 @@ Deploy a wasm contract
Default value: `false`

- `--alias <ALIAS>` — The alias that will be used to save the contract's id. Whenever used, `--alias` will always overwrite the existing contract id configuration without asking for confirmation
- `--env <ENV>` — Set an environment variable for the build (repeatable), e.g. `--env NAME=VALUE`. It's set on the build process; for a verifiable build it's passed to the container and recorded as a `bldopt`, so avoid secrets there
- `--optimize <OPTIMIZE>` — Optimize the generated wasm. Enabled by default; pass `--optimize=false` to disable. Requires the `additional-libs` feature

Default value: `true`
Expand Down Expand Up @@ -854,6 +876,7 @@ Install a WASM file to the ledger without creating a contract instance

Default value: `false`

- `--env <ENV>` — Set an environment variable for the build (repeatable), e.g. `--env NAME=VALUE`. It's set on the build process; for a verifiable build it's passed to the container and recorded as a `bldopt`, so avoid secrets there
- `--optimize <OPTIMIZE>` — Optimize the generated wasm. Enabled by default; pass `--optimize=false` to disable. Requires the `additional-libs` feature

Default value: `true`
Expand Down Expand Up @@ -917,6 +940,7 @@ Install a WASM file to the ledger without creating a contract instance

Default value: `false`

- `--env <ENV>` — Set an environment variable for the build (repeatable), e.g. `--env NAME=VALUE`. It's set on the build process; for a verifiable build it's passed to the container and recorded as a `bldopt`, so avoid secrets there
- `--optimize <OPTIMIZE>` — Optimize the generated wasm. Enabled by default; pass `--optimize=false` to disable. Requires the `additional-libs` feature

Default value: `true`
Expand Down Expand Up @@ -4145,7 +4169,7 @@ Encode a transaction envelope from JSON to XDR

Decode and encode XDR

**Usage:** `stellar xdr [CHANNEL] <COMMAND>`
**Usage:** `stellar xdr <COMMAND>`

###### **Subcommands:**

Expand All @@ -4158,14 +4182,6 @@ Decode and encode XDR
- `xfile` — Preprocess XDR .x files
- `version` — Print version information

###### **Arguments:**

- `<CHANNEL>` — Channel of XDR to operate on

Default value: `+curr`

Possible values: `+curr`, `+next`

## `stellar xdr types`

View information about types
Expand Down
Loading
Loading