starknet_patricia_storage: two layer storage

[ArielElp]

No description provided.

[reviewable-StarkWare]

This change is 

[ArielElp]

• apollo_committer: add new request handler #14003
• apollo_committer: add request_paths_and_commit_block tests #14208
• 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
• 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 👈 (View in Graphite)
• 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

Low Risk
New isolated module with tests only; no existing call sites or storage backends are modified in this diff.

Overview
Adds a two-layer read-only storage composite so callers can stack a writable overlay on a borrowed immutable base and still satisfy ReadOnlyStorage via get_mut / mget_mut.

Reads consult the overlay first; missing keys are fetched from the base (batch reads only hit the base for overlay misses). The design is aimed at use cases like fetch_all_patricia_paths, which need &mut ReadOnlyStorage without owning the underlying DB.

Unit tests cover base fall-through, overlay shadowing, overlay delete revealing base values, and mixed mget_mut behavior.

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

[yoavGrs]

@yoavGrs reviewed 2 files and all commit messages, and made 4 comments.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on ArielElp).

---

a discussion (no related file):
Just a reminder, what do you need this for?

---

crates/starknet_patricia_storage/src/two_layer_storage.rs line 25 at r1 (raw file):

    pub overlay: Overlay,
    pub base: &'a Base,
}

Suggestion:

{
    overlay: Overlay,
    base: &'a Base,
}

---

crates/starknet_patricia_storage/src/two_layer_storage.rs line 69 at r1 (raw file):

}

#[cfg(test)]

Move tests to a testing file.

[ArielElp]

@ArielElp reviewed 1 file and made 3 comments.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on yoavGrs).

---

crates/starknet_patricia_storage/src/two_layer_storage.rs line 69 at r1 (raw file):

Previously, yoavGrs wrote…

Move tests to a testing file.

Done.

---

crates/starknet_patricia_storage/src/two_layer_storage.rs line 25 at r1 (raw file):

    pub overlay: Overlay,
    pub base: &'a Base,
}

Done.

[yoavGrs]

@yoavGrs reviewed all commit messages, made 2 comments, and resolved 2 discussions.
Reviewable status: 1 of 3 files reviewed, 4 unresolved discussions (waiting on ArielElp).

---

crates/starknet_patricia_storage/src/two_layer_storage.rs line 70 at r2 (raw file):

#[cfg(test)]
#[path = "two_layer_storage_test.rs"]

Move it to the top of the file.

[yoavGrs]

@yoavGrs reviewed 2 files and all commit messages, made 1 comment, and resolved 2 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 2 comments.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on ArielElp).

---

crates/starknet_patricia_storage/src/two_layer_storage.rs line 18 at r4 (raw file):

/// [`ReadOnlyStorage::get_mut`] / [`ReadOnlyStorage::mget_mut`] use the same immutable overlay and
/// base paths on overlay misses so the composite implements [`ReadOnlyStorage`] while holding
/// `&'a Base`. Patricia paths reads do not mutate the underlying storage.

had a stroke trying to read this first sentence, can you rephrase please?

Code quote:

/// [`ReadOnlyStorage::get_mut`] / [`ReadOnlyStorage::mget_mut`] use the same immutable overlay and
/// base paths on overlay misses so the composite implements [`ReadOnlyStorage`] while holding
/// `&'a Base`. Patricia paths reads do not mutate the underlying storage.

---

crates/starknet_patricia_storage/src/two_layer_storage_test.rs line 40 at r4 (raw file):

    two.overlay.delete(&key).await.unwrap();
    assert_eq!(two.get_mut(&key).await.unwrap(), Some(base_val));
}

non-blocking - just easier to understand what the test is checking like this

Suggestion:

    let mut two = TwoLayerStorage::new(MapStorage::default(), &base);
    let over_val = DbValue(vec![99]);
    two.overlay.set(key.clone(), over_val).await.unwrap();
    assert_eq!(two.get_mut(&key).await.unwrap(), Some(over_val));
    two.overlay.delete(&key).await.unwrap();
    assert_eq!(two.get_mut(&key).await.unwrap(), Some(base_val));
}

[yoavGrs]

Reviewable status: all files reviewed, 2 unresolved discussions (waiting on ArielElp).

[ArielElp]

@ArielElp made 1 comment and resolved 2 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on ArielElp).

---

crates/starknet_patricia_storage/src/two_layer_storage.rs line 18 at r4 (raw file):

Previously, dorimedini-starkware wrote…

had a stroke trying to read this first sentence, can you rephrase please?

Done

[dorimedini-starkware]

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

[dorimedini-starkware]

@dorimedini-starkware reviewed 1 file and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on ArielElp).