fix(agglayer): enforce canonical zero padding on leaf data

[Fumuran]

Summary

Closes #2985.

The bridge leaf is a 113-byte keccak preimage stored as 32 felts: 29 data felts followed by 3 trailing padding felts. pack_leaf_data folds padding[0]'s low 3 bytes into the unused tail (byte positions 113-115) of the final packed u32. The keccak precompile truncates the hash to 113 bytes, so padding never changes LEAF_VALUE, but it requires that tail to be zero - and only enforces it implicitly, via a generic InvalidPadding failure. padding[1] and padding[2] are never read by the packer or the hash at all, so nothing checked them.

On the bridge-in/CLAIM path the leaf data is piped verbatim from the prover-supplied advice map, so the padding felts were never explicitly validated.

Fix

Make the requirement explicit and total in the shared helper. pack_leaf_data now calls a new assert_padding_is_zero helper (under a HELPER PROCEDURES section) that asserts all 3 trailing padding felts are zero before packing, panicking with ERR_LEAF_PADDING_NOT_ZERO otherwise. Because the check lives in the shared helper, it also covers bridge-out (which already zeros these felts) and any future caller, and it yields a clear bridge-specific error instead of the generic precompile padding failure.

This is defense-in-depth: it does not change LEAF_VALUE or the claim nullifier (the nullifier is derived from the leaf index and source network, not the leaf preimage).

Changes

• crates/miden-agglayer/asm/agglayer/bridge/leaf_utils.masm
  • New error const ERR_LEAF_PADDING_NOT_ZERO.
  • PADDING_OFFSET derived from PACKED_DATA_NUM_ELEMENTS so it stays coupled to the packing loop bound.
  • New private assert_padding_is_zero helper; called from pack_leaf_data before the loop. Docs on pack_leaf_data / compute_leaf_value updated.
• crates/miden-agglayer/asm/agglayer/bridge/bridge_in.masm
  • get_leaf_value advice-map doc updated to state padding must be zero (and why).
• crates/miden-agglayer/asm/agglayer/bridge/bridge_out.masm
  • No logic change (already zeros padding); PADDING_OFFSET now derived from METADATA_HASH_OFFSET + 8; comment/doc updated.
• crates/miden-agglayer/SPEC.md
  • CLAIM storage padding row and bridge_in::claim Panics row updated.
• crates/miden-testing/tests/agglayer/leaf_utils.rs
  • New pack_leaf_data_rejects_non_zero_padding test exercising all three padding offsets (29/30/31).

Testing

cargo test -p miden-testing --test lib agglayer:: - all 61 agglayer tests pass, including the new negative test.

🤖 Generated with Claude Code

[mmagician]

I'm wondering how easy would it be to add a regression test for what the original issue describes:

a malicious prover can change LEAF_VALUE - and thus the CGI chain hash the AggLayer side must reproduce - without changing any real leaf field.

This would probably require some manipulation of the data loaded in the advice provider, but I haven't thought too much how the exact attack would look like.

[Fumuran]

I'm wondering how easy would it be to add a regression test for what the original issue describes

I'm not sure that we can assert the CGI chain hash if the leaf data is changed, we never actually read the CGI chain hash value. Or maybe I just misunderstood the idea

Edit: I think implicitly we check it during the existing test: we change the padding values and make sure that this change is caught and will not result in the CGI hash chain corruption

[mmagician]

I think the fix for the stated problem "enforce canonical zero padding on leaf data" is correct, but I wonder whether this is a real issue in the first place, now that I deep dive into this.

It's true that a malicious prover could provide non-zero padding and we're not checking these values explicitly.
But if they do so, then the computed LEAF_VALUE will not be verifiable against any GER that is stored in the bridge, so the CLAIM will be rejected.

So the CGI hash will never be updated with a malicious LEAF_VALUE' because the updating of cgi hash chain is conditional on the verification against GER in the first place:

proc verify_leaf_bridge
    # get the leaf value. We have all the necessary leaf data in the advice map
    exec.get_leaf_value
    # => [LEAF_VALUE[8], PROOF_DATA_KEY]

    # duplicate the leaf value to use it later during the CGI chain hash computation
    movupw.2 dupw.2 dupw.2
    # => [LEAF_VALUE[8], PROOF_DATA_KEY, LEAF_VALUE[8]]

    # delegate proof verification
    exec.verify_leaf  <----------- this will fail if the prover provided non-zero padding
    # => [LEAF_VALUE[8]]

    # update the CGI chain hash 
    exec.update_cgi_chain_hash <------------ if the verification against GER fails, we won't get to updating the CGI chain hash
    # => []
end

[Fumuran]

Indeed! It turned out that we actually return an error in case the padding is not zero, we do this check in the keccak precompile (here, we return the non-zero padding byte 0x1 at byte position 113 error message). So the execution will fail even before we will try to verify the leaf, it will fail during the computation of this leaf. The only advantage of a new code is that we will be able to return more user friendly error message, but I'm not sure that this forth it to create another helper procedure and to further complicate our code for that.

[mmagician]

The only advantage of a new code is that we will be able to return more user friendly error message, but I'm not sure that this forth it to create another helper procedure and to further complicate our code for that.

Agreed, the advantage is not big enough IMO and I'd probably skip the helper, then