docs: warn about keeping compiler versions consistent across upgrades#29547
Open
mvanhorn wants to merge 1 commit into
Open
docs: warn about keeping compiler versions consistent across upgrades#29547mvanhorn wants to merge 1 commit into
mvanhorn wants to merge 1 commit into
Conversation
Comment on lines
+137
to
+154
| ### 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 <N>` when you need to inspect a specific edition: | ||
|
|
||
| ```bash | ||
| leo query program <NAME> | ||
| leo query program <NAME> --edition <N> | ||
| ``` | ||
|
|
||
| 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. |
Collaborator
There was a problem hiding this comment.
Keeping the compiler version stable is important for more than just checksum-governed upgrades. Constructors, for example, can't change between upgrades and some features may change (and even break) between compiler versions. So really this whole section should be more general purpose I think.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The program upgradability guide does not warn that the Leo compiler version used to deploy a program should match the version used for later upgrades. Different compiler versions can emit different bytecode for identical source, which can break checksum-governed upgrades since those compare an on-chain checksum against the program's code. This adds a short callout next to the
@checksumpattern explaining the risk, recommending that maintainers pin the Leo compiler version across the initial deploy and all upgrades, and showing how to check versions withleo --versionand how to inspect a deployment's source withleo query program <NAME>(and--edition <N>).The guidance stays conservative: it does not assert an exact bytecode-stability guarantee, only that you should not assume stability across compiler versions and should pin to be safe.
Fixes #29383
Test Plan
Documentation-only change to
documentation/guides/program_upgradability.md.npx markdownlint-cli2 documentation/guides/program_upgradability.md-> 0 errorsgit diff --check-> no whitespace errorsleo query programaccepts an--editionflag (crates/leo/src/cli/commands/query/program.rs), and there is no flag that prints a compiler version, which the callout states explicitly.Related PRs
None.
AI was used for assistance.