Skip to content

docs: warn about keeping compiler versions consistent across upgrades #29547

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

Open
mvanhorn wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: warn about keeping compiler versions consistent across upgrades #29547

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
19 changes: 19 additions & 0 deletions documentation/guides/program_upgradability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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.
Comment on lines +137 to +154

@mohammadfawaz mohammadfawaz Jun 22, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@IGI-111 IGI-111 Jun 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW I think we should commit to constructor stability at some point. Not being able to migrate contracts to a new version without a migration is not really tenable. Irrelevant to this change however.


### 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
Expand Down