Feat: Add API and mechanism to retrieve additional top-level and child proofs via the relay state proof #10678

metricaez · 2025-12-17T13:37:14Z

Purpose

This pull request introduces a new runtime API and implements the full feature pipeline for requesting additional relay-chain storage proofs in lookahead collators. The API allows parachain runtimes to specify extra top-level storage keys or child-trie data that must be included in the relay-chain state proof. The collator collects these additional proofs and merges them into the relay-chain state proof provided to the runtime during block execution, enabling the runtime to later process custom relay-chain data.

Rationale

Immediate application in pubsub mechanism proposed in #9994

This is a narrow down of scope for easier review of PR #10679

Due to early exits when defaulted it adds no significant overhead to current flows.

What this PR adds

Runtime API

Introduces KeyToIncludeInRelayProofApi. (Suggestions for better naming are very welcome.)
Adds supporting types RelayProofRequest and RelayStorageKey.
Allows runtimes to declare which relay-chain storage entries must be included in the relay state proof.

Collator integration

The lookahead collator calls the runtime API before block production.
Requested relay-chain proofs are collected, batched, and merged in a single operation.
The additional proofs are merged into the existing relay-chain state proof and passed to the runtime via parachain inherent data.

Proof extraction

parachain-system exposes an extraction method for processing this additional proofs.
Uses a handler pattern:
- parachain-system manages proof lifecycle and initial validation.
- Application pallets consume proofs (data extraction or additional validation) by implementing ProcessRelayProofKeys.
Keeps extra proofs processing logic out of parachain-system.

About RelayStorageKey

RelayStorageKey is an enum with two variants:

Top: a Vec<u8> representing a top-level relay-chain storage key.
Child, which contains:
- storage_key: an unprefixed identifier of the child trie root (the default :child_storage:default: prefix is applied automatically),
- key: the specific key within that child trie.

On the client side, child trie access is performed via ChildInfo::new_default(&storage_key).

Why storage_key instead of ChildInfo:

ChildInfo from sp-storage does not implement TypeInfo, which runtime APIs require.
Adding TypeInfo to sp-storage (or introducing a wrapper to avoid bloating a critical core component like sp-storage) would significantly expand the scope of this PR.

As a result, the current design:

Uses raw storage_key bytes.
Is limited to child tries using the default prefix.

Future improvements

Full ChildInfo support if TypeInfo is added to sp-storage (directly or via a wrapper), enabling arbitrary child-trie prefixes.
Possible unification with additional_relay_state_keys for top-level proofs, subject to careful analysis of semantics and backward compatibility.
Integration with additional collator implementations beyond lookahead collators.

bkchr

Mostly looking good, just some small improvements.

bkchr · 2025-12-17T16:53:48Z

cumulus/client/relay-chain-rpc-interface/src/lib.rs

+		// Not implemented: requires relay chain RPC to expose child trie proof method.
+		tracing::warn!(
+			target: "relay-chain-rpc-interface",
+			"prove_child_read not implemented for RPC interface, returning empty proof"
+		);


And it is not doing this?

state_getChildReadProof.

True, missed that one, done.

bkchr · 2025-12-19T12:48:37Z

cumulus/primitives/core/src/lib.rs

+	///
+	/// This API allows parachains to request both top-level relay chain storage keys
+	/// and child trie storage keys to be included in the relay chain state proof.
+	pub trait KeyToIncludeInRelayProofApi {


Suggested change

pub trait KeyToIncludeInRelayProofApi {

pub trait KeyToIncludeInRelayProof {

bkchr · 2025-12-19T12:48:51Z

cumulus/primitives/core/src/lib.rs

+		/// The returned `RelayProofRequest` contains a list of storage keys where each key
+		/// can be either:
+		/// - `RelayStorageKey::Top`: Top-level relay chain storage key
+		/// - `RelayStorageKey::Child`: Child trie storage, containing the child trie identifier
+		///   and the key to prove from that child trie
+		///


Suggested change

/// The returned `RelayProofRequest` contains a list of storage keys where each key

/// can be either:

/// - `RelayStorageKey::Top`: Top-level relay chain storage key

/// - `RelayStorageKey::Child`: Child trie storage, containing the child trie identifier

/// and the key to prove from that child trie

///

bkchr · 2025-12-19T12:49:28Z

cumulus/primitives/core/src/lib.rs

+		/// - `RelayStorageKey::Child`: Child trie storage, containing the child trie identifier
+		///   and the key to prove from that child trie
+		///
+		/// The collator generates proofs for these and includes them in the relay chain state proof.


Suggested change

/// The collator generates proofs for these and includes them in the relay chain state proof.

/// The collator will include them in the relay chain proof that is passed alongside the parachain inherent into the runtime.

bkchr · 2025-12-19T12:51:30Z

cumulus/client/parachain-inherent/src/lib.rs

+async fn collect_additional_storage_proofs(
+	relay_chain_interface: &impl RelayChainInterface,
+	relay_parent: PHash,
+	relay_proof_request: RelayProofRequest,
+) -> Option<StorageProof> {


I don't get why we have two functions doing almost the same.

IMO we should have one function that returns us the "static keys" (aka what we used so far and then we will join them with the additional keys to download all at once)

Did it just for the sake of keeping logics more isolated but I have unified with the suggested approach and we reduced a prove_read call which is nice.

bkchr · 2025-12-19T13:31:38Z

cumulus/pallets/parachain-system/src/lib.rs

+		/// Processor for relay chain proof keys.
+		///
+		/// This allows parachains to process data from the relay chain state proof,
+		/// including both child trie keys and main trie keys that were requested
+		/// via `KeyToIncludeInRelayProofApi`.
+		type RelayProofKeysProcessor: relay_state_snapshot::ProcessRelayProofKeys;


Just merge this with OnSystemEvent. Then we don't need a new type here.

bkchr · 2025-12-19T13:34:26Z

cumulus/test/runtime/src/lib.rs

+
+	impl cumulus_primitives_core::KeyToIncludeInRelayProofApi<Block> for Runtime {
+		fn keys_to_prove() -> RelayProofRequest {
+			Default::default()


Could you return here some key that isn't read up to now. And then add some logic to the test_pallet that asserts that the key is part of the proof.
As we use the test runtime in zombienet tests, it will be automatically tested there for us.

bkchr

Some last nitpicks, otherwise looks good.

bkchr · 2025-12-24T10:36:27Z

cumulus/client/consensus/aura/src/collators/mod.rs

+		.unwrap_or_else(|e| {
+			tracing::warn!(
+				target: crate::LOG_TARGET,
+				error = ?e,
+				"Failed to fetch relay proof requests from runtime, using empty request"
+			);
+			Default::default()
+		})


Suggested change

.unwrap_or_else(|e| {

tracing::warn!(

target: crate::LOG_TARGET,

error = ?e,

"Failed to fetch relay proof requests from runtime, using empty request"

);

Default::default()

})

.unwrap_or_else(|e| {

tracing::debug!(

target: crate::LOG_TARGET,

error = ?e,

"Failed to fetch relay proof requests from runtime, using empty request"

);

Default::default()

})

The API may not exists and then we clearly don't want to see these warnings :)

bkchr · 2025-12-24T10:37:41Z

cumulus/pallets/parachain-system/src/lib.rs

+			total_weight.saturating_accrue(
+			<T::OnSystemEvent as OnSystemEvent>::on_relay_state_proof(&relay_state_proof),


bkchr · 2025-12-24T10:38:27Z

cumulus/primitives/core/src/lib.rs

+	pub trait KeyToIncludeInRelayProof {
+		/// Returns relay chain storage proof requests.
+		///
+


Suggested change

bkchr · 2025-12-24T10:41:10Z

cumulus/test/runtime/src/test_pallet.rs

+
+		// Expect the requested key to be part of the proof.
+		relay_state_proof
+			.read_optional_entry::<u64>(RELAY_EPOCH_INDEX_KEY)


My point was to use a key that isn't by default part of the proof, this is already part of the proof. Let's take the balance key for ALICE for example.

Yes, I understand it, I picked EPOCH_INDEX because I didn't realize it was already included because it was not part of the static keys. Already switched to ALICE System key and had to add to sproof builder for it not to break any unit test. Also tested and working as expected :)

github-actions · 2025-12-24T11:14:53Z

Review required! Latest push from author must always be reviewed

metricaez mentioned this pull request Dec 17, 2025

PubSub Mechanism - Follow up on #9994 #10679

Open

bkchr reviewed Dec 19, 2025

View reviewed changes

metricaez requested a review from bkchr December 22, 2025 03:09

metricaez added 9 commits December 22, 2025 10:24

feat: KeyToIncludeInRelayProofApi

d5ca459

choir: shorter imports

4882d6e

feat: better naming and batch merging of proofs

fbd13f8

feat: naming and comment suggestions

2f90953

fix: name change occurences fix

2d7717e

feat: collect static keys and unify prove_read

6676373

feat: move relay proof handler to OnSystemEvent

0a02f4c

feat: prove_child_read for relay rpc interface

41f52af

feat: imp KeyToIncludeInRelayProof for test pallet

d40f024

metricaez force-pushed the feat/keys-to-proof-api branch from ceed7ce to d40f024 Compare December 22, 2025 13:25

bkchr approved these changes Dec 24, 2025

View reviewed changes

choir: fmt and move api warn to debug

e240fab

github-actions bot requested a review from bkchr December 24, 2025 11:14

feat: test pallet check with Alice balance

39aa7fc

	pub trait KeyToIncludeInRelayProofApi {
	pub trait KeyToIncludeInRelayProof {

	/// The collator generates proofs for these and includes them in the relay chain state proof.
	/// The collator will include them in the relay chain proof that is passed alongside the parachain inherent into the runtime.

		total_weight.saturating_accrue(
		<T::OnSystemEvent as OnSystemEvent>::on_relay_state_proof(&relay_state_proof),

Feat: Add API and mechanism to retrieve additional top-level and child proofs via the relay state proof #10678

Are you sure you want to change the base?

Feat: Add API and mechanism to retrieve additional top-level and child proofs via the relay state proof #10678

Uh oh!

Conversation

metricaez commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose

Rationale

What this PR adds

Runtime API

Collator integration

Proof extraction

About RelayStorageKey

Future improvements

Uh oh!

bkchr 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bkchr 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!

github-actions bot commented Dec 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

metricaez commented Dec 17, 2025 •

edited

Loading