Skip to content

feat(provenance): pin build toolchain via source.yaml image (run build in Docker)#21

Merged
Agusx1211 merged 1 commit into
masterfrom
feat/provenance-build-image
Jun 30, 2026
Merged

feat(provenance): pin build toolchain via source.yaml image (run build in Docker)#21
Agusx1211 merged 1 commit into
masterfrom
feat/provenance-build-image

Conversation

@Agusx1211

Copy link
Copy Markdown
Member

What

Adds an optional image field to source.yaml provenance entries. When set, Catapult runs the entry's build command inside docker run <image> instead of on the host.

type: source
build_info:
  "./stage1.json":
    repo: "https://github.com/0xsequence/wallet-contracts-v3"
    commit: "0d9061f229da73edae890e6fdd1fbf753028df6d"
    image: "ghcr.io/foundry-rs/foundry:v1.5.1"   # <-- new
    build: "forge build --build-info"

Why

provenance verify compares the entire normalized build-info JSON, including compiler settings such as settings.evmVersion. So the rebuild must use the same toolchain that produced the committed file — otherwise a drifting default fails the compare. (Concretely: Foundry's default EVM target moved pragueosaka between stable and nightly, which silently broke a verify whose committed artifact was prague.)

Until now the only way to pin the toolchain was to bake the whole docker run … invocation into each entry's build string — verbose, easy to get the mount/user/HOME flags wrong, and duplicated across every entry. The toolchain is really a property of the build, so Catapult should own that plumbing.

Behavior

When image is set, the build runs in a container with:

  • the checkout bind-mounted at /workspace (also the working directory and $HOME, so toolchains that cache to $HOME — e.g. solc downloads — write into the disposable checkout);
  • the build string executed via sh -c (entrypoint overridden, so it's image-agnostic);
  • on POSIX hosts, --user <uid>:<gid> so generated build-info is owned by the caller and the temp checkout can be read back and cleaned up.

This keeps the toolchain pinned per entry (different build-info files can use different images), leaves the host/runner untouched, and requires only that Docker be installed and running. image is also honored in per-contract contracts overrides. When image is omitted, behavior is unchanged (build runs on the host shell).

Changes

  • types/source: image?: string on SourceProvenance + SourceProvenanceOverride
  • parsers/source: validate image as a string field (also in contract overrides)
  • provenance: runBuild() dispatches to runDockerBuild() when image is set; image added to the build cache key
  • Tests (parser: parse / validate / override-merge) + README section

All 676 existing tests pass; the new docker path is intentionally not exercised in unit tests (would require Docker on the runner) — it's validated end-to-end against a real project.

…`image`

Provenance compares the entire build-info JSON (including compiler settings like
evmVersion), so the rebuild must use the same toolchain that produced the
committed file. Previously the only way to pin that was to bake `docker run ...`
into each entry's `build` command, which is verbose, easy to get wrong, and
mutates nothing-on-host only if the author remembers the right flags.

Add an optional `image` field to source provenance (and per-contract overrides).
When set, Catapult runs the build command inside `docker run <image>` with the
checkout bind-mounted at /workspace (also workdir and $HOME), the command run via
`sh -c`, and — on POSIX — the container as the caller's uid:gid so output is
owned by the caller and the temp checkout cleans up. The toolchain is pinned per
entry (different build-info files can use different images) and the host/runner
is untouched.

- types/source: add image to SourceProvenance + SourceProvenanceOverride
- parser: accept/validate image as a string field (also in contract overrides)
- provenance: runBuild() wraps build in runDockerBuild() when image is set;
  include image in the build cache key
- tests + README
@Agusx1211 Agusx1211 force-pushed the feat/provenance-build-image branch from e0c9969 to 2164347 Compare June 30, 2026 11:37
@Agusx1211 Agusx1211 merged commit d2b8abb into master Jun 30, 2026
7 checks passed
@Agusx1211 Agusx1211 deleted the feat/provenance-build-image branch June 30, 2026 11:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant