feat: use cargo install for Agave 4.1+ docker images (#339)

## Summary
- Agave 4.1.x uses `cargo install cargo-build-sbf` instead of the full
CLI
- Older Agave versions keep the existing install path
- New release trains need an entry in `AGAVE_CARGO_INSTALL_MAP` or the
script fails

## Why
Anza is splitting build tooling from the CLI. Verifiable builds only
need `cargo build-sbf`, and 4.1.x should use platform-tools v1.54.

Author: meumar-osec

generate_dockerfiles.py

@@ -29,6 +29,19 @@
 SOLANA_VERSION_PLACEHOLDER = "$SOLANA_VERSION"
 AGAVE_VERSION_PLACEHOLDER = "$AGAVE_VERSION"
 INSTALL_SHA256_PLACEHOLDER = "$INSTALL_SHA256"
+CARGO_BUILD_SBF_VERSION_PLACEHOLDER = "$CARGO_BUILD_SBF_VERSION"
+PLATFORM_TOOLS_ARGS_PLACEHOLDER = "$PLATFORM_TOOLS_ARGS"
+
+# Agave trains that install cargo-build-sbf from crates.io (not the full CLI).
+# One map entry per minor line, bump cargo_build_sbf_version when the train moves to a new crate.
+AGAVE_CARGO_INSTALL_MAP = {
+    (4, 1): {
+        "cargo_build_sbf_version": "4.1.0",
+        "platform_tools_args": "--tools-version v1.54",
+    },
+}
+
+missing_cargo_install_trains = set()
 
 _INSTALL_SHA256_CACHE = {}
 
@@ -89,14 +102,14 @@ def with_pinned_installer(url: str, install_path: str = "/tmp/solana_install.sh"
 CMD /bin/bash
 """
 
-# Dockerfile template for Agave
+# Dockerfile template for Agave (CLI install)
 base_dockerfile_agave = f"""
 FROM --platform=linux/amd64 rust@{RUST_VERSION_PLACEHOLDER}
 
 RUN apt-get update && apt-get install -qy git gnutls-bin curl ca-certificates
 {with_pinned_installer(f"https://release.anza.xyz/{AGAVE_VERSION_PLACEHOLDER}/install")}
 ENV PATH="/root/.local/share/solana/install/active_release/bin:$PATH"
-# Call cargo build-sbf to trigger installation of associated platform tools
+# Call cargo build-sbf to trigger installation of platform tools
 RUN cargo init temp --edition 2021 && \\
     cd temp && \\
     cargo build-sbf && \\
@@ -106,6 +119,23 @@ def with_pinned_installer(url: str, install_path: str = "/tmp/solana_install.sh"
 CMD /bin/bash
 """
 
+# Dockerfile template for Agave (cargo install path)
+base_dockerfile_agave_cargo_install = f"""
+FROM --platform=linux/amd64 rust@{RUST_VERSION_PLACEHOLDER}
+
+LABEL agave.version="{AGAVE_VERSION_PLACEHOLDER}"
+RUN apt-get update && apt-get install -qy git gnutls-bin curl ca-certificates
+RUN cargo install cargo-build-sbf --version {CARGO_BUILD_SBF_VERSION_PLACEHOLDER} --locked
+# Call cargo build-sbf to trigger installation of platform tools
+RUN cargo init temp --edition 2021 && \\
+    cd temp && \\
+    cargo build-sbf{PLATFORM_TOOLS_ARGS_PLACEHOLDER} && \\
+    rm -rf temp
+WORKDIR /build
+
+CMD /bin/bash
+"""
+
 # Skipping these because the are not valid releases or where yanked or not released for mainnet
 SKIPPED_VERSIONS = {
     "v1.15", "v1.14.0", "v1.10.0", "v1.10.16", "v1.10.18",
@@ -158,12 +188,27 @@ def get_release_info(version_tag):
         }
     #Everything after we need to get from anza 
     elif (major == 1 and minor == 18 and patch >= 24) or major >= 2:
-        return {
-            "base_dockerfile_text": base_dockerfile_agave,
+        agave_info = {
             "version_placeholder": AGAVE_VERSION_PLACEHOLDER,
             "url": f"https://raw.githubusercontent.com/anza-xyz/agave/{version_tag}/rust-toolchain.toml",
-            "install_url": f"https://release.anza.xyz/{version_tag}/install"
+            "install_url": f"https://release.anza.xyz/{version_tag}/install",
         }
+        train = (major, minor)
+        if train in AGAVE_CARGO_INSTALL_MAP:
+            cfg = AGAVE_CARGO_INSTALL_MAP[train]
+            agave_info["base_dockerfile_text"] = base_dockerfile_agave_cargo_install
+            agave_info["cargo_build_sbf_version"] = cfg["cargo_build_sbf_version"]
+            agave_info["platform_tools_args"] = cfg.get("platform_tools_args", "")
+        elif train >= (4, 1):
+            missing_cargo_install_trains.add(train)
+            print(
+                f"ERROR: {version_tag} needs an AGAVE_CARGO_INSTALL_MAP entry for Agave {major}.{minor}.x",
+                flush=True,
+            )
+            return None
+        else:
+            agave_info["base_dockerfile_text"] = base_dockerfile_agave
+        return agave_info
 
     return None
 
@@ -273,20 +318,34 @@ def process_releases(releases):
             RUST_VERSION_PLACEHOLDER, RUST_DOCKER_IMAGESHA_MAP[rust_version]
         ).lstrip("\n")
 
+        if "cargo_build_sbf_version" in release_info:
+            platform_tools_args = release_info.get("platform_tools_args", "").strip()
+            if platform_tools_args:
+                platform_tools_args = f" {platform_tools_args}"
+            dockerfile = dockerfile.replace(
+                CARGO_BUILD_SBF_VERSION_PLACEHOLDER,
+                release_info["cargo_build_sbf_version"],
+            ).replace(
+                PLATFORM_TOOLS_ARGS_PLACEHOLDER,
+                platform_tools_args,
+            )
+
         if os.path.exists(path):
             if not args.update_existing:
                 # Only generate Dockerfiles for new releases
                 continue
 
-        sha = fetch_install_script_sha256(release_info["install_url"])
-        if not sha:
-            print(f"Warning: failed to fetch installer checksum for {release}; leaving {path} unchanged")
-            continue
+        # Only templates with the install script need a checksum
+        if INSTALL_SHA256_PLACEHOLDER in dockerfile:
+            sha = fetch_install_script_sha256(release_info["install_url"])
+            if not sha:
+                print(f"Warning: failed to fetch installer checksum for {release}; leaving {path} unchanged")
+                continue
 
-        dockerfile = dockerfile.replace(INSTALL_SHA256_PLACEHOLDER, sha)
+            dockerfile = dockerfile.replace(INSTALL_SHA256_PLACEHOLDER, sha)
 
-        if INSTALL_SHA256_PLACEHOLDER in dockerfile:
-            raise Exception(f"Checksum not injected for {release}")
+            if INSTALL_SHA256_PLACEHOLDER in dockerfile:
+                raise Exception(f"Checksum not injected for {release}")
 
         stripped = release.strip("v")
         if os.path.exists(path):
@@ -315,6 +374,12 @@ def process_releases(releases):
     process_releases(solana_releases)
     process_releases(agave_releases)
 
+if missing_cargo_install_trains:
+    trains = ", ".join(f"{m}.{n}.x" for m, n in sorted(missing_cargo_install_trains))
+    raise Exception(
+        f"Missing AGAVE_CARGO_INSTALL_MAP entries for Agave release trains: {trains}"
+    )
+
 print(RUST_DOCKER_IMAGESHA_MAP)