docs(trie): hashed post state & cursors

[rkrasiuk]

Description

Improve documentation for the HashedPostState and cursors.

@mattsse PTAL.

[codecov]

Codecov Report

Merging #3572 (fb79551) into main (4f32f56) will decrease coverage by 0.16%.
The diff coverage is 32.77%.

Impacted Files	Coverage Δ
crates/rpc/rpc/src/eth/api/fees.rs	48.41% <0.00%> (ø)
crates/rpc/rpc/src/eth/pubsub.rs	7.38% <0.00%> (ø)
crates/storage/libmdbx-rs/src/cursor.rs	90.45% <ø> (ø)
crates/storage/provider/src/post_state/mod.rs	95.73% <ø> (ø)
crates/storage/provider/src/traits/state.rs	28.07% <ø> (ø)
crates/transaction-pool/src/lib.rs	36.00% <ø> (ø)
crates/transaction-pool/src/test_utils/mod.rs	100.00% <ø> (+5.55%)	⬆️
crates/transaction-pool/src/traits.rs	5.12% <0.00%> (-0.14%)	⬇️
crates/transaction-pool/src/noop.rs	11.38% <11.38%> (ø)
crates/blockchain-tree/src/blockchain_tree.rs	81.84% <50.00%> (ø)
... and 16 more

... and 40 files with indirect coverage changes

Flag	Coverage Δ
integration-tests	16.12% <21.11%> (-0.12%)	⬇️
unit-tests	63.99% <25.00%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
reth binary	26.46% <ø> (+3.45%)	⬆️
blockchain tree	81.25% <75.00%> (ø)
pipeline	86.89% <100.00%> (-0.09%)	⬇️
storage (db)	73.48% <95.23%> (-0.34%)	⬇️
trie	95.64% <100.00%> (+<0.01%)	⬆️
txpool	49.46% <10.93%> (-1.69%)	⬇️
networking	77.88% <100.00%> (+0.01%)	⬆️
rpc	57.98% <72.22%> (+0.10%)	⬆️
consensus	62.58% <ø> (ø)
revm	34.95% <100.00%> (-0.05%)	⬇️
payload builder	6.83% <ø> (ø)
primitives	88.29% <ø> (-0.21%)	⬇️

[mattsse]

ty,

what would be useful is an explainer how this works:

reth/crates/storage/provider/src/traits/state.rs

Lines 222 to 223 in b4801f9

	/// Returns the state root of the PostState on top of the current state.
	fn state_root(&self, post_state: PostState) -> Result<H256>;

especially on PostState, it's not obvious how all the pieces tie together here which makes it very hard to understand why this can be a perf bottleneck:

there are like 4 steps required here to get the state root:

reth/crates/blockchain-tree/src/chain.rs

Lines 201 to 220 in b4801f9

	let canonical_fork = post_state_data_provider.canonical_fork();
	let state_provider = db.history_by_block_number(canonical_fork.number)?;
	let provider = PostStateProvider::new(state_provider, post_state_data_provider);
	let mut executor = externals.executor_factory.with_sp(&provider);
	let post_state = executor.execute_and_verify_receipt(&block, U256::MAX, Some(senders))?;
	// check state root if the block extends the canonical chain.
	if block_kind.extends_canonical_head() {
	// check state root
	let state_root = provider.state_root(post_state.clone())?;
	if block.state_root != state_root {
	return Err(ConsensusError::BodyStateRootDiff {
	got: state_root,
	expected: block.state_root,
	}
	.into())
	}
	}

[rkrasiuk]

@mattsse since this is already documented on PostState::state_root_slow, i simply referenced it in StateRootProvider::state_root docs

reth/crates/storage/provider/src/post_state/mod.rs

Lines 216 to 247 in 0042e9b

	/// Calculate the state root for this [PostState].
	/// Internally, function calls [Self::hash_state_slow] to obtain the [HashedPostState].
	/// Afterwards, it retrieves the [PrefixSets](reth_trie::prefix_set::PrefixSet) of changed keys
	/// from the [HashedPostState] and uses them to calculate the incremental state root.
	///
	/// # Example
	///
	/// ```
	/// use reth_primitives::{Address, Account};
	/// use reth_provider::PostState;
	/// use reth_db::{test_utils::create_test_rw_db, database::Database};
	///
	/// // Initialize the database
	/// let db = create_test_rw_db();
	///
	/// // Initialize the post state
	/// let mut post_state = PostState::new();
	///
	/// // Create an account
	/// let block_number = 1;
	/// let address = Address::random();
	/// post_state.create_account(1, address, Account { nonce: 1, ..Default::default() });
	///
	/// // Calculate the state root
	/// let tx = db.tx().expect("failed to create transaction");
	/// let state_root = post_state.state_root_slow(&tx);
	/// ```
	///
	/// # Returns
	///
	/// The state root for this [PostState].
	pub fn state_root_slow<'a, 'tx, TX: DbTx<'tx>>(

[mattsse]

send it