starknet_committer: define StarknetForestProofs serde

[ArielElp]

No description provided.

[reviewable-StarkWare]

This change is 

[ArielElp]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• apollo_committer: add new request handler #14003
• starknet_committer: delete patricia paths on reverts #14002
• starknet_committer,apollo_committer: add timers for fetch patricia paths #14189
• starknet_committer: underlying logic of the new read witnesses and commit endpoint #14001
• starknet_committer: extract metadata construction to a function #14000
• starknet_committer: extract commit plan to commit_or_load #13999
• starknet_committer: read and write patricia paths to index db #13998
• starknet_committer: db keys for proofs and accessed keys digest #13997
• apollo_committer_types: add patricia proofs request and response types #13996
• starknet_committer: add patricia paths forest reader/writer traits #13995
• starknet_committer: define StarknetForestProofs serde #13994 👈 (View in Graphite)
• starknet_committer: compute and store accessed keys digest #13993
• starknet_committer: add utility that returns sorted leaf indices #13992
• starknet_committer: abstract fetch_all_patricia_paths #13991
• starknet_patricia_storage: two layer storage #13990
• starknet_committer: move fetch_patricia_paths tests #13960
• starknet_committer: fetch patricia paths tests #13959
• starknet_committer: support both layouts in fetch_patricia_paths #13958
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Medium Risk
Touches state-commitment witness encoding for the OS; wire-format mistakes could break prover input, though scope is feature-gated and covered by round-trip tests.

Overview
Adds bincode serialization for StarknetForestProofs behind the os_input feature so Patricia Merkle witnesses can be written to and read from DbValue for OS-input flows.

serialize / deserialize flatten classes trie nodes, contract trie nodes and leaves, and per-contract storage trie preimages into a fixed four-part bincode tuple, using the same binary/edge Felt encodings as existing commitment facts and OS Patricia hints. Deserialization rebuilds PreimageMaps and rejects duplicate node hashes, contract leaves, or storage witnesses.

ContractsTrieProof and StarknetForestProofs gain Debug and PartialEq; extend is now public. Round-trip tests cover several witness shapes when os_input is enabled in tests.

^{Reviewed by Cursor Bugbot for commit 7b294f1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[ArielElp]

@ArielElp made 1 comment.
Reviewable status: 0 of 5 files reviewed, 1 unresolved discussion (waiting on yoavGrs).

---

a discussion (no related file):

Previously, yoavGrs wrote…

For each object, test that deser(ser(object)) == object.

Done.

[yoavGrs]

@yoavGrs reviewed 5 files and all commit messages, made 6 comments, and resolved 1 discussion.
Reviewable status: all files reviewed, 6 unresolved discussions (waiting on ArielElp).

---

crates/starknet_committer/src/patricia_merkle_tree/starknet_forest_proofs_serialization_test.rs line 128 at r2 (raw file):

}

#[template]

Why do you need the template?

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 97 at r2 (raw file):

    /// 3. Contract trie leaves — `Vec<(ContractAddress, (Nonce, HashOutput, ClassHash))>`, sorted
    ///    by contract address.
    /// 4. Storage trie inner nodes — `Vec<(ContractAddress, Vec<(HashOutput, encoded_preimage)>)>`,

?

Suggestion:

tries

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 113 at r2 (raw file):

            .leaves
            .iter()
            .map(|(addr, s)| (*addr, (s.nonce, s.storage_root_hash, s.class_hash)))

Full names, please

Suggestion:

addr, state)

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 120 at r2 (raw file):

        for (addr, m) in &self.contracts_trie_storage_proofs {
            storage.push((*addr, sorted_encoded_preimage_map(m)?));
        }

In Rust, it's idiomatic to create a vector by iter().map().collect().

Code quote:

        let mut storage: Vec<(ContractAddress, Vec<(HashOutput, Vec<u8>)>)> = Vec::new();
        for (addr, m) in &self.contracts_trie_storage_proofs {
            storage.push((*addr, sorted_encoded_preimage_map(m)?));
        }

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 167 at r2 (raw file):

            {
                return Err(DeserializationError::KeyDuplicate(format!(
                    "duplicate storage trie witness key {addr:?}"

Suggestion:

address

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 270 at r2 (raw file):

) -> Result<Vec<(HashOutput, Vec<u8>)>, SerializationError> {
    let mut v = Vec::with_capacity(m.len());
    for (h, p) in m {

Give full names, please

Suggestion:

for (hash, preimage) in m

[ArielElp]

@ArielElp made 6 comments.
Reviewable status: all files reviewed, 6 unresolved discussions (waiting on yoavGrs).

---

crates/starknet_committer/src/patricia_merkle_tree/starknet_forest_proofs_serialization_test.rs line 128 at r2 (raw file):

Previously, yoavGrs wrote…

Why do you need the template?

Removed

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 97 at r2 (raw file):

Previously, yoavGrs wrote…

?

Done.

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 113 at r2 (raw file):

Previously, yoavGrs wrote…

Full names, please

Done.

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 120 at r2 (raw file):

Previously, yoavGrs wrote…

In Rust, it's idiomatic to create a vector by iter().map().collect().

Done.

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 270 at r2 (raw file):

Previously, yoavGrs wrote…

Give full names, please

Done.

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 167 at r2 (raw file):

            {
                return Err(DeserializationError::KeyDuplicate(format!(
                    "duplicate storage trie witness key {addr:?}"

Done.

[yoavGrs]

@yoavGrs reviewed 2 files and all commit messages, and resolved 6 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on ArielElp).

[dorimedini-starkware]

@dorimedini-starkware reviewed 3 files and all commit messages, and made 4 comments.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on ArielElp).

---

crates/starknet_committer/src/patricia_merkle_tree/starknet_forest_proofs_serialization_test.rs line 52 at r5 (raw file):

        class_hash: ClassHash(Felt::from(class_hash)),
    }
}

can you ask claude if similar test utils exist in the patricia/committer crates? seems like duplication to me, I vaguely recall similar stuff

Code quote:

fn binary_preimage(node_hash: u128, left: u128, right: u128) -> (HashOutput, Preimage) {
    (
        HashOutput(Felt::from(node_hash)),
        Preimage::Binary(BinaryData {
            left_data: HashOutput(Felt::from(left)),
            right_data: HashOutput(Felt::from(right)),
        }),
    )
}

fn edge_preimage(node_hash: u128, bottom: u128, path: u128, length: u8) -> (HashOutput, Preimage) {
    (
        HashOutput(Felt::from(node_hash)),
        Preimage::Edge(EdgeData {
            bottom_data: HashOutput(Felt::from(bottom)),
            path_to_bottom: PathToBottom::new(
                EdgePath(U256::from(path)),
                EdgePathLength::new(length).unwrap(),
            )
            .unwrap(),
        }),
    )
}

fn contract_state(nonce: u128, storage_root: u128, class_hash: u128) -> ContractState {
    ContractState {
        nonce: Nonce(Felt::from(nonce)),
        storage_root_hash: HashOutput(Felt::from(storage_root)),
        class_hash: ClassHash(Felt::from(class_hash)),
    }
}

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs at r5 (raw file):
can you move the additions here to a separate module gated by os_input?
there shouldn't be a problem, adding another impl block.
I ask because of all the gated-imports - generally a sign that a new module is a good choice

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 78 at r5 (raw file):

}

impl StarknetForestProofs {

why are the (de)serialize functions here needed?
we already have serde logic for facts layout, or at least we have deserialization logic for facts layout. this logic is used by the py-side ambassador to encode commitment infos for OS runs. can't you reuse it?

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 88 at r5 (raw file):

    }

    /// Bincode payload for the OS-input witness KV (structured proofs, round-trips with

KV?

Code quote:

KV

[ArielElp]

@ArielElp made 4 comments.
Reviewable status: 3 of 6 files reviewed, 4 unresolved discussions (waiting on dorimedini-starkware and yoavGrs).

---

crates/starknet_committer/src/patricia_merkle_tree/starknet_forest_proofs_serialization_test.rs line 52 at r5 (raw file):

Previously, dorimedini-starkware wrote…

can you ask claude if similar test utils exist in the patricia/committer crates? seems like duplication to me, I vaguely recall similar stuff

Doesn't look like it, existing tests also explicitly construct ContractState and I don't see (or Cursor) something for Preimage

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 78 at r5 (raw file):

Previously, dorimedini-starkware wrote…

why are the (de)serialize functions here needed?
we already have serde logic for facts layout, or at least we have deserialization logic for facts layout. this logic is used by the py-side ambassador to encode commitment infos for OS runs. can't you reuse it?

For the OsBlockInput constructed in tests we use deserialization of CommitmentInfo, which is a bit more raw compared to StarknetForestProofs.

I kept the structure of StarknetForestProofs, but now reusing the existing encoding/decoding of Preimage, so most of the new code is gone.

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs line 88 at r5 (raw file):

Previously, dorimedini-starkware wrote…

KV?

AI for the key value preimage map, changed to OS input witnesses

---

crates/starknet_committer/src/patricia_merkle_tree/types.rs at r5 (raw file):

Previously, dorimedini-starkware wrote…

can you move the additions here to a separate module gated by os_input?
there shouldn't be a problem, adding another impl block.
I ask because of all the gated-imports - generally a sign that a new module is a good choice

Done.