From 2b24b0de31648cf4152a6ff03d44dd9ba7bdb4ba Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Sat, 20 Jun 2026 08:41:16 -0700 Subject: [PATCH] docs: warn about keeping compiler versions consistent across upgrades --- documentation/guides/program_upgradability.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/documentation/guides/program_upgradability.md b/documentation/guides/program_upgradability.md index fe13cda8b6..bee5f7a02e 100644 --- a/documentation/guides/program_upgradability.md +++ b/documentation/guides/program_upgradability.md @@ -134,6 +134,25 @@ constructor: position end; ``` +### Warning: Keep Compiler Versions Consistent + +Checksum-governed upgrades are bytecode-sensitive. Do not assume bytecode is stable across Leo compiler versions: different compiler versions can produce different bytecode for identical source, which can cause a checksum-governed upgrade to fail. + +Pin the Leo compiler version used for the initial deployment and all subsequent upgrades. Before deploying or approving an upgrade, check the local toolchain: + +```bash +leo --version +``` + +To inspect the source currently deployed on the network, query the program. Use `--edition ` when you need to inspect a specific edition: + +```bash +leo query program +leo query program --edition +``` + +The query returns deployed source; it does not print the compiler version. Use it with your pinned toolchain record and rebuild with the same Leo version to avoid bytecode drift. + ### Pattern 4: Custom Logic (Time-lock Example) **Goal:** Enforce a time delay before an upgrade is allowed. No pre-defined mode is available for this so we'll have to write our own upgrade policy