docs(revm): document lifetime requirements for CachedReads wrappers (#19725)

crates/revm/src/cached.rs

@@ -24,6 +24,7 @@ use revm::{bytecode::Bytecode, state::AccountInfo, Database, DatabaseRef};
 ///     let db = cached_reads.as_db_mut(db);
 ///     // this is `Database` and can be used to build a payload, it never commits to `CachedReads` or the underlying database, but all reads from the underlying database are cached in `CachedReads`.
 ///     // Subsequent payload build attempts can use cached reads and avoid hitting the underlying database.
+///     // Note: `cached_reads` must outlive `db` to satisfy lifetime requirements.
 ///     let state = State::builder().with_database(db).build();
 /// }
 /// ```
@@ -71,6 +72,10 @@ impl CachedReads {
 }
 
 /// A [Database] that caches reads inside [`CachedReads`].
+///
+/// The lifetime parameter `'a` is tied to the lifetime of the underlying [`CachedReads`] instance.
+/// This ensures that the cache remains valid for the entire duration this wrapper is used.
+/// The original [`CachedReads`] must outlive this wrapper to prevent use-after-free.
 #[derive(Debug)]
 pub struct CachedReadsDbMut<'a, DB> {
     /// The cache of reads.
@@ -158,6 +163,11 @@ impl<DB: DatabaseRef> Database for CachedReadsDbMut<'_, DB> {
 ///
 /// This is intended to be used as the [`DatabaseRef`] for
 /// `revm::db::State` for repeated payload build jobs.
+///
+/// The lifetime parameter `'a` matches the lifetime of the underlying [`CachedReadsDbMut`],
+/// which in turn is tied to the [`CachedReads`] cache. [`RefCell`] is used here to provide
+/// interior mutability for the [`DatabaseRef`] trait (which requires `&self`), while the
+/// lifetime ensures the cache remains valid throughout the wrapper's usage.
 #[derive(Debug)]
 pub struct CachedReadsDBRef<'a, DB> {
     /// The inner cache reads db mut.