ci: verify MAST roots on patch releases by TomasArrachea · Pull Request #3305 · 0xMiden/protocol

TomasArrachea · 2026-07-14T20:34:48Z

This PR adds a step to the workspace-release action to validate that the MAST roots are the same as the ones present on the previous release. The check is skipped on major/minor updates, only runs on patch releases. It will run on pushes to main or on a release publish.

It collects the root from the public procedures from the standards and protocol libraries and the account components. This can change to use the packages but they are yet to be added in the current release on main.

Context: #3224 (comment)

bobbinth · 2026-07-19T20:31:48Z

@huitseeker @mmagician - could you take a look at this PR?

mmagician

LGTM, happy to merge as-is once we integrate agglayer checks, and we can optimally think about the versioning follow up later.

mmagician · 2026-07-20T13:18:18Z

+edition = "2024"
+
+[dependencies]
+miden-protocol-current = { package = "miden-protocol", path = "../crates/miden-protocol" }


We should also check for roots from the agglayer crate

mmagician · 2026-07-20T13:20:07Z

+miden-standards-current = { package = "miden-standards", path = "../crates/miden-standards" }
+
+# The release wrapper rewrites these tags to the latest release tag on main.
+miden-protocol-previous = { package = "miden-protocol", git = "https://github.com/0xMiden/protocol", tag = "v0.15.4" }


So this requires manually updating the script each time to use the correct comparison version, right?

Ok for now but ideally we'd either read it from Cargo.toml or something similar

No manual updates are actually needed: the script is only run through check-masm-root-stability.sh which finds the latest release tag and rewrites the tag = "..." entries in a temp copy before running it. The tag in the script is actually a placeholder.

huitseeker · 2026-07-20T20:25:38Z

+    pub fn collect_roots() -> Roots {
+        let mut roots = Roots::new();
+
+        let protocol = ProtocolLib::default();


ProtocolLib::default() covers assets/protocol.masl, but the kernel roots are generated separately from tx_kernel.masl into TransactionKernel::PROCEDURES.

A patch release could change a $kernel public procedure root and this check would still pass.

Added the check in ce8b64a

huitseeker · 2026-07-20T20:25:38Z

+        let standards = StandardsLib::default();
+        collect_library(standards.as_ref(), &mut roots);
+
+        collect_library(&agglayer_library(), &mut roots);


This covers the aggregate AggLayer library, but not the bridge/faucet component wrappers or the account code commitments generated from them.

A patch could change BRIDGE_CODE_COMMITMENT or FAUCET_CODE_COMMITMENT by changing the wrapper exports or companion component set while all agglayer_library() roots stay the same.

Added the check in ce8b64a

huitseeker · 2026-07-22T15:10:43Z

        ./scripts/check-msrv.sh

+    - name: Check MAST root stability
+      if: ${{ inputs.mode == 'dry-run' && github.ref == 'refs/heads/main' }}


This only runs for dry-runs on main, so the new check is skipped by workspace-publish.yml (mode: publish) and by dry-run pushes to release/**.

That leaves a path where a patch release from a release branch, or a direct published release, can publish without this MAST root gate.

Should this condition key off the release line check inside check-masm-root-stability.sh instead of github.ref == 'refs/heads/main'? If worried about this check blocking release, you can add an escape hatch similar to 0xMiden/miden-vm@c10619f

Good catch. I changed it so the step now runs in both modes on every ref, and the gating is done by the script. It skips itself when there is no baseline tag or when the version change is a patch release.

On the escape hatch: unlike miden-vm, here the publish workflow only triggers on release: published, so there is no dispatch where we can set the input. So, instead, I added a check on a SKIP_MASM_ROOT_CHECK repository variable, so it can be set to true to skip the check if needed.

bobbinth · 2026-07-24T01:04:06Z

@huitseeker - could you take a look through this again?

igamigo · 2026-07-27T18:55:47Z

+fn run() -> Result<(), String> {
+    let previous = previous::collect_roots();
+    let current = current::collect_roots();
+    compare_roots(previous, current)


I think we also want to compare the kernel commitment, which does not directly get covered by the library because of the dynamic invocation.

igamigo

Looks good! I think the only remaining points I have are:

Would be great to smoke test various scenarios with this somehow, but it seems like it could be hard to do self-contained. Maybe we can open a PR to test out different sequences (bumping patch version and changing methods, etc).
I think this PR will not enable additions, even when they might make sense. For example, there might be good reasons to backport a new standard or something like that, and I think some of these changes would not allow that (unless I'm mistaken). Is this the case? And is there something we want to do about it?

TomasArrachea · 2026-07-29T16:38:32Z

I think this PR will not enable additions, even when they might make sense. For example, there might be good reasons to backport a new standard or something like that, and I think some of these changes would not allow that (unless I'm mistaken). Is this the case? And is there something we want to do about it?

Addressed this on 832f454. Now the check does not fail if a new procedure is added, is only shown as a warning. However, adding a procedure to any account component or to the tx kernel would fail since the set of procedures is also checked as a whole.

igamigo

LGTM! I think the current state covers most cases. I do wonder if we should really add all procedure roots of an account component and also the commitment (the commitment should be enough). Maybe in terms of code organization it would be worth separating every scenario and filter accordingly: backporting standards should be allowed, adding procedures to kernel/account code/note scripts should be breaking, anything else should remain stable.
I also still think we should ideally test this so let's create an issue or see if we can reproduce this in a discard PR

bobbinth · 2026-08-03T06:15:18Z

I haven't reviewed this in detail yet - but would be good to document the exact logic we are using here (maybe in a Markdown file somewhere).

TomasArrachea · 2026-08-04T13:57:28Z

I haven't reviewed this in detail yet - but would be good to document the exact logic we are using here (maybe in a Markdown file somewhere).

Added a scripts/README.md file that describes the script behaviour.

Also rebased this PR to next, since we are soon releasing the v0.16 and so probably won't be necessary to merge #3224 to main to make a patch release for v0.15.

ci: check MASM roots

f146113

TomasArrachea added the no changelog This PR does not require an entry in the `CHANGELOG.md` file label Jul 14, 2026

fix: cargo-deny

6ce653c

TomasArrachea force-pushed the tomasarrachea-check-roots branch from bdedf8b to 6ce653c Compare July 14, 2026 20:44

TomasArrachea changed the title ~~ci: verify MASM roots on patch releases~~ ci: verify MAST roots on patch releases Jul 14, 2026

chore: comments

2f81fa7

TomasArrachea marked this pull request as ready for review July 14, 2026 22:25

TomasArrachea mentioned this pull request Jul 14, 2026

feat: migrate protocol and standards to Package #3224

Open

1 task

bobbinth requested review from huitseeker and mmagician July 14, 2026 22:28

mmagician approved these changes Jul 20, 2026

View reviewed changes

TomasArrachea added 2 commits July 20, 2026 15:59

review: check roots for miden-agglayer

4ff91f8

review: clarify tag comment

0739f33

huitseeker reviewed Jul 20, 2026

View reviewed changes

review: verify agglayer account code commitments and tx-kernel

ce8b64a

huitseeker reviewed Jul 22, 2026

View reviewed changes

TomasArrachea added 2 commits July 22, 2026 18:22

review: run the check on all modes and refs

1c007d2

chore: skip on pre-release

f21d9ce

igamigo reviewed Jul 27, 2026

View reviewed changes

TomasArrachea force-pushed the tomasarrachea-check-roots branch from cf51d1f to f21d9ce Compare July 27, 2026 20:03

review: add missing commitments verification

b71e2e2

TomasArrachea requested a review from igamigo July 27, 2026 21:54

igamigo reviewed Jul 28, 2026

View reviewed changes

TomasArrachea added 2 commits July 29, 2026 12:17

feat: expose code for AccountSchemaCommitment component

97080a0

review: do not fail on added procedure

832f454

igamigo approved these changes Jul 29, 2026

View reviewed changes

feat: check kernel programs commitment

a0823f7

TomasArrachea added 3 commits August 3, 2026 17:33

review: add scripts/README.md with check specs

4e58edb

Merge branch 'next' into tomasarrachea-check-roots

fdca64c

feat: update check to v0.16

9543d2c

TomasArrachea changed the base branch from main to next August 3, 2026 21:24

Uh oh!

Conversation

TomasArrachea commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bobbinth commented Jul 19, 2026

Uh oh!

mmagician left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobbinth commented Jul 24, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

igamigo left a comment

Choose a reason for hiding this comment

Uh oh!

TomasArrachea commented Jul 29, 2026

Uh oh!

igamigo left a comment

Choose a reason for hiding this comment

Uh oh!

bobbinth commented Aug 3, 2026

Uh oh!

TomasArrachea commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

TomasArrachea commented Jul 14, 2026 •

edited

Loading