diff --git a/crates/tycho-substreams/src/balances.rs b/crates/tycho-substreams/src/balances.rs
index 2547723..66ff2b5 100644
--- a/crates/tycho-substreams/src/balances.rs
+++ b/crates/tycho-substreams/src/balances.rs
@@ -19,6 +19,20 @@ use substreams::key;
 use substreams::pb::substreams::StoreDeltas;
 use substreams::prelude::{BigInt, StoreAdd};
 
+/// Store relative balances changes in a additive manner.
+///
+/// Effectively aggregates the relative balances changes into an absolute balances.
+///
+/// ## Arguments
+///
+/// * `deltas` - A `BlockBalanceDeltas` message containing the relative balances changes.
+///     Note: relative balance deltas must have strictly increasing ordinals per token
+///     address, will panic otherwise.
+/// * `store` - An AddStore that will add relative balance changes.
+///
+/// This method is meant to be used in combination with `aggregate_balances_changes`
+/// which consumes the store filled with this methods in
+/// [deltas mode](https://substreams.streamingfast.io/documentation/develop/manifest-modules/types#deltas-mode).
 pub fn store_balance_changes(deltas: BlockBalanceDeltas, store: impl StoreAdd<BigInt>) {
     let mut previous_ordinal = HashMap::<String, u64>::new();
     deltas
@@ -49,6 +63,22 @@ pub fn store_balance_changes(deltas: BlockBalanceDeltas, store: impl StoreAdd<Bi
         });
 }
 
+/// Aggregates absolute balances per transaction and token.
+///
+/// ## Arguments
+/// * `balance_store` - A `StoreDeltas` with all changes that occured in the source
+///     store module.
+/// * `deltas` - A `BlockBalanceDeltas` message containing the relative balances changes.
+///
+/// Reads absolute balance values from the additive store (see `store_balance_changes`
+/// on how to create such a store), proceeds to zip them with the relative balance
+/// deltas to associate balance values to token and component.
+///
+/// Will keep the last balance change per token per transaction if there are multiple
+/// changes.
+///
+/// Returns a map of transactions hashes to the full transaction and aggregated
+/// absolute balance changes.
 pub fn aggregate_balances_changes(
     balance_store: StoreDeltas,
     deltas: BlockBalanceDeltas,
diff --git a/crates/tycho-substreams/src/contract.rs b/crates/tycho-substreams/src/contract.rs
index 633ef35..f054380 100644
--- a/crates/tycho-substreams/src/contract.rs
+++ b/crates/tycho-substreams/src/contract.rs
@@ -1,12 +1,17 @@
-/// This file contains helpers to capture contract changes from the expanded block model. These
-///  leverage the `code_changes`, `balance_changes`, and `storage_changes` fields available on the
-///  `Call` type provided by block model in a substream (i.e. `logs_and_calls`, etc).
+/// Helpers to extract relevant contract storage.
 ///
-/// ⚠️ These helpers *only* work if the **expanded block model** is available,
+/// This file contains helpers to capture contract changes from the expanded block
+/// model. These leverage the `code_changes`, `balance_changes`, and `storage_changes`
+/// fields available on the `Call` type provided by block model in a substream
+/// (i.e. `logs_and_calls`, etc).
+///
+/// ## Warning
+/// ⚠️ These helpers *only* work if the **extended block model** is available,
 /// more [here](https://streamingfastio.medium.com/new-block-model-to-accelerate-chain-integration-9f65126e5425)
 use std::collections::HashMap;
 
 use substreams_ethereum::pb::eth;
+use substreams_ethereum::pb::eth::v2::block::DetailLevel;
 use substreams_ethereum::pb::eth::v2::StorageChange;
 
 use crate::pb::tycho::evm::v1::{self as tycho};
@@ -70,11 +75,26 @@ impl From<InterimContractChange> for tycho::ContractChange {
     }
 }
 
+/// Extracts relevant contract changes from the block.
+///
+/// Contract changes include changes in storage, code and native balance.
+///
+/// ## Arguments
+///
+/// * `block` - The block to extract changes from. Must be the extended block model.
+/// * `inclusion_predicate` - A predicate function that determines if a contract address is relevant.
+/// * `transaction_contract_changes` - A mutable map to store the contract changes in.
+///
+/// ## Panics
+/// Will panic in case the detail level of the block is not extended.
 pub fn extract_contract_changes<F: Fn(&[u8]) -> bool>(
     block: &eth::v2::Block,
     inclusion_predicate: F,
     transaction_contract_changes: &mut HashMap<u64, tycho::TransactionContractChanges>,
 ) {
+    if block.detail_level != Into::<i32>::into(DetailLevel::DetaillevelExtended) {
+        panic!("Only extended blocks are supported");
+    }
     let mut changed_contracts: HashMap<Vec<u8>, InterimContractChange> = HashMap::new();
 
     // Collect all accounts created in this block
diff --git a/crates/tycho-substreams/src/pb/mod.rs b/crates/tycho-substreams/src/pb/mod.rs
index ceced59..5e6abdd 100644
--- a/crates/tycho-substreams/src/pb/mod.rs
+++ b/crates/tycho-substreams/src/pb/mod.rs
@@ -8,6 +8,7 @@ pub mod tycho {
             // @@protoc_insertion_point(tycho.evm.v1)
 
             impl TransactionContractChanges {
+                /// Creates a new empty `TransactionContractChanges` instance.
                 pub fn new(tx: &Transaction) -> Self {
                     Self {
                         tx: Some(tx.clone()),
@@ -46,6 +47,9 @@ pub mod tycho {
             }
 
             impl ProtocolComponent {
+                /// Creates a new empty `ProtocolComponent` instance.
+                ///
+                /// You can use the `with_*` methods to set the fields in a convience way.
                 pub fn new(id: &str, tx: &Transaction) -> Self {
                     Self {
                         id: id.to_string(),
@@ -58,6 +62,10 @@ pub mod tycho {
                     }
                 }
 
+                /// Shorthand to create a component with a 1-1 relationship to a contract.
+                ///
+                /// Will set the component id to a hex encoded address with a 0x prefix
+                /// and add the contract to contracts attributes.
                 pub fn at_contract(id: &[u8], tx: &Transaction) -> Self {
                     Self {
                         id: format!("0x{}", hex::encode(id)),
@@ -70,6 +78,7 @@ pub mod tycho {
                     }
                 }
 
+                /// Replaces the tokens on this component.
                 pub fn with_tokens<B: AsRef<[u8]>>(mut self, tokens: &[B]) -> Self {
                     self.tokens = tokens
                         .iter()
@@ -78,6 +87,7 @@ pub mod tycho {
                     self
                 }
 
+                /// Replaces the contracts associated with this component.
                 pub fn with_contracts<B: AsRef<[u8]>>(mut self, contracts: &[B]) -> Self {
                     self.contracts = contracts
                         .iter()
@@ -86,6 +96,9 @@ pub mod tycho {
                     self
                 }
 
+                /// Replaces the static attributes on this component.
+                ///
+                /// The change type will be set to Creation.
                 pub fn with_attributes<K: AsRef<str>, V: AsRef<[u8]>>(
                     mut self,
                     attributes: &[(K, V)],
@@ -101,6 +114,10 @@ pub mod tycho {
                     self
                 }
 
+                /// Sets the protocol_type on this component.
+                ///
+                /// Will set the `financial_type` to FinancialType::Swap and the
+                /// `attribute_schema` to an empty list.
                 pub fn as_swap_type(
                     mut self,
                     name: &str,