diff --git a/crates/storage/codecs/src/lib.rs b/crates/storage/codecs/src/lib.rs
index 54ca046cb..58a7db8c1 100644
--- a/crates/storage/codecs/src/lib.rs
+++ b/crates/storage/codecs/src/lib.rs
@@ -48,6 +48,12 @@ pub mod test_utils;
 /// Regarding the `specialized_to/from_compact` methods: Mainly used as a workaround for not being
 /// able to specialize an impl over certain types like `Vec<T>`/`Option<T>` where `T` is a fixed
 /// size array like `Vec<B256>`.
+///
+/// ## Caution
+///
+/// Due to the bitfields, every type change on the rust type (e.g. `U256` to `u64`) is a breaking
+/// change and will lead to a new, incompatible [`Compact`] implementation. Implementers must take
+/// special care when changing or rearranging fields.
 pub trait Compact: Sized {
     /// Takes a buffer which can be written to. *Ideally*, it returns the length written to.
     fn to_compact<B>(&self, buf: &mut B) -> usize