From a7c09a82a3d427bb6dbe226b07b979ead12e3e1e Mon Sep 17 00:00:00 2001
From: Matt Bell <mappum@gmail.com>
Date: Sun, 27 Oct 2024 23:49:44 -0500
Subject: [PATCH 1/2] Start doc comment coverage for ethereum module

---
 src/ethereum/consensus/mod.rs     |  18 ++++
 src/ethereum/consensus/relayer.rs |  19 ++++
 src/ethereum/mod.rs               | 141 +++++++++++++++++++++++++++---
 3 files changed, 166 insertions(+), 12 deletions(-)

diff --git a/src/ethereum/consensus/mod.rs b/src/ethereum/consensus/mod.rs
index 29e9be25..f07fe7a2 100644
--- a/src/ethereum/consensus/mod.rs
+++ b/src/ethereum/consensus/mod.rs
@@ -35,6 +35,8 @@ use crate::error::Result;
 #[cfg(feature = "ethereum-full")]
 pub mod relayer;
 
+/// Maintains the consensus state of an Ethereum chain, which can be updated via
+/// consensus proofs based on the Altair light client protocol.
 #[derive(Clone, Debug, Default, Serialize, Deserialize)]
 pub struct LightClient {
     lcs: LightClientStore,
@@ -42,6 +44,8 @@ pub struct LightClient {
 }
 
 impl LightClient {
+    /// Create a new `LightClient` with the given bootstrap data and network
+    /// configuration.
     pub fn new(bootstrap: Bootstrap, network: Network) -> Result<Self> {
         let bootstrap = bootstrap.into();
 
@@ -57,6 +61,11 @@ impl LightClient {
         Ok(LightClient { lcs, network })
     }
 
+    /// Verify and apply the update to the light client state.
+    ///
+    /// To minimize updates, this is designed to only allow updates that advance
+    /// to the next finalized slot, or to the next sync committee period.
+    /// There should be at most one update per epoch.
     pub fn update(&mut self, update: Update, now_seconds: u64) -> Result<()> {
         let expected_slot = (now_seconds - self.network.genesis_time) / 12;
         let genesis_root = (&self.network.genesis_vals_root.0).into();
@@ -79,10 +88,12 @@ impl LightClient {
         Ok(())
     }
 
+    /// Get the most recently finalized slot.
     pub fn slot(&self) -> u64 {
         self.lcs.finalized_header.beacon.slot
     }
 
+    /// Get the most recently finalized block number.
     pub fn block_number(&self) -> u64 {
         *self
             .lcs
@@ -93,6 +104,7 @@ impl LightClient {
             .block_number()
     }
 
+    /// Get the most recently finalized execution state root.
     pub fn state_root(&self) -> Bytes32 {
         self.lcs
             .finalized_header
@@ -104,6 +116,7 @@ impl LightClient {
             .into()
     }
 
+    /// Get the underlying `LightClientStore`.
     pub fn light_client_store(&self) -> &LightClientStore {
         &self.lcs
     }
@@ -238,6 +251,7 @@ impl Describe for LightClient {
     }
 }
 
+/// The network parameters for an Ethereum chain.
 #[derive(Clone, Debug, Default, Encode, Decode, Serialize, Deserialize)]
 pub struct Network {
     pub genesis_vals_root: Bytes32,
@@ -246,6 +260,7 @@ pub struct Network {
 }
 
 impl Network {
+    /// Network parameters for the Ethereum mainnet.
     pub fn ethereum_mainnet() -> Self {
         Network {
             genesis_vals_root: "0x4b363db94e286120d76eb905340fdd4e54bfe9f06bf33ff6cf5ad27f511bfe95"
@@ -256,6 +271,7 @@ impl Network {
         }
     }
 
+    /// Network parameters for the Ethereum Sepolia testnet.
     pub fn ethereum_sepolia() -> Self {
         Network {
             genesis_vals_root: "0xd8ea171f3c94aea21ebc42a1ed61052acf3f9209c00e4efbaaddac09ed9b8078"
@@ -267,6 +283,8 @@ impl Network {
     }
 }
 
+/// An update to the light client state, and all necessary proof and signature
+/// data.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Update {
     pub attested_header: LightClientHeader,
diff --git a/src/ethereum/consensus/relayer.rs b/src/ethereum/consensus/relayer.rs
index 8b011818..7e8c7275 100644
--- a/src/ethereum/consensus/relayer.rs
+++ b/src/ethereum/consensus/relayer.rs
@@ -5,6 +5,16 @@ use serde::{Deserialize, Serialize};
 use super::{Bootstrap, Bytes32, LightClient, Update};
 use crate::error::Result;
 
+/// Based on the current Nomic state machine state, get the updates needed to
+/// bring the light client up to date with the Ethereum chain.
+///
+/// This may include any number of updates that advance the light client to the
+/// next light client period (256 epochs) and a finality update that advances
+/// the light client to the most recently finalized slot within the current
+/// period.
+///
+/// If the light client is already up to date, this function will return an
+/// empty vector.
 pub async fn get_updates<C: OrgaClient<LightClient>>(
     app_client: &C,
     eth_client: &RpcClient,
@@ -38,15 +48,19 @@ pub async fn get_updates<C: OrgaClient<LightClient>>(
     Ok(updates)
 }
 
+/// A client for the Ethereum Beacon API.
 pub struct RpcClient {
     rpc_addr: String,
 }
 
 impl RpcClient {
+    /// Create a new client to the Beacon API server with the given address.
     pub fn new(rpc_addr: String) -> Self {
         Self { rpc_addr }
     }
 
+    /// Get the updates, if any, to advance the light client from the given
+    /// start period to the current period, up to the given count.
     pub async fn get_updates(
         &self,
         start_period: u64,
@@ -66,6 +80,7 @@ impl RpcClient {
         Ok(res)
     }
 
+    /// Get the most recent finality update.
     pub async fn get_finality_update(&self) -> Result<Response<Update>> {
         let url = format!(
             "{}/eth/v1/beacon/light_client/finality_update",
@@ -81,6 +96,7 @@ impl RpcClient {
         Ok(res)
     }
 
+    /// Get the block root for the given slot.
     pub async fn block_root(&self, slot: u64) -> Result<Response<Root>> {
         let url = format!("{}/eth/v1/beacon/blocks/{}/root", self.rpc_addr, slot,);
         let response = get(&url)
@@ -93,6 +109,7 @@ impl RpcClient {
         Ok(res)
     }
 
+    /// Get the bootstrap data for the given block root.
     pub async fn bootstrap(&self, block_root: Bytes32) -> Result<Response<Bootstrap>> {
         let url = format!(
             "{}/eth/v1/beacon/light_client/bootstrap/{}",
@@ -109,12 +126,14 @@ impl RpcClient {
     }
 }
 
+/// A response from the Beacon API.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Response<T> {
     pub version: Option<String>,
     pub data: T,
 }
 
+/// A response containing a block root.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Root {
     pub root: Bytes32,
diff --git a/src/ethereum/mod.rs b/src/ethereum/mod.rs
index 9f7391ad..02970046 100644
--- a/src/ethereum/mod.rs
+++ b/src/ethereum/mod.rs
@@ -1,3 +1,6 @@
+#![warn(missing_docs)]
+#![warn(clippy::missing_docs_in_private_items)]
+
 use alloy_core::{
     primitives::keccak256,
     sol_types::{sol, SolValue},
@@ -71,19 +74,28 @@ pub mod relayer;
 #[cfg(feature = "ethereum-full")]
 pub mod signer;
 
+/// How often to send messages updating to a new valset, in seconds.
 pub const VALSET_INTERVAL: u64 = 60 * 60 * 24;
 /// Gas price in microsats.
 pub const GAS_PRICE: u64 = 160_000;
+/// Approximate gas cost for a transfer in wei, deducted from transfers from
+/// Nomic to the destination chain.
 pub const APPROX_TRANSFER_GAS: u64 = 80_000;
+/// Approximate gas cost for a contract call in wei, deducted from calls made on
+/// the destination chain.
 pub const APPROX_CALL_GAS: u64 = 100_000;
 
+/// The main state machine container for all Ethereum networks managed by Nomic.
 #[orga]
 pub struct Ethereum {
+    /// The Ethereum networks managed by Nomic, keyed by chain ID.
     pub networks: Map<u32, Network>,
 }
 
 #[orga]
 impl Ethereum {
+    /// Advances the state of all networks managed by Nomic, should be called
+    /// once per Nomic block.
     pub fn step(&mut self, active_sigset: &SignatorySet) -> Result<()> {
         let ids: Vec<_> = self
             .networks
@@ -98,6 +110,10 @@ impl Ethereum {
         Ok(())
     }
 
+    /// Takes all pending transfers from all networks managed by Nomic, to be
+    /// moved into Nomic's Bitcoin state machine and eventually credited. These
+    /// transfers are either incoming from the remote EVM chain, or a bounceback
+    /// caused by a failed call or transfer.
     pub fn take_pending(&mut self) -> Result<Vec<(Dest, Coin<Nbtc>, Identity)>> {
         let ids: Vec<_> = self
             .networks
@@ -112,6 +128,9 @@ impl Ethereum {
         Ok(pending)
     }
 
+    /// Verifies and applies a consensus light client update to the given
+    /// network. This should be called by relayers whenever there is a new
+    /// finality update from the remote chain's consensus process.
     #[call]
     pub fn relay_consensus_update(
         &mut self,
@@ -129,6 +148,9 @@ impl Ethereum {
         net.light_client.update(update, now_seconds)
     }
 
+    /// Verifies a state proof and processes the incoming transfers returning
+    /// from the remote chain. This should be called by relayers whenever there
+    /// is a new state proof from the remote chain.
     #[call]
     pub fn relay_return(
         &mut self,
@@ -153,6 +175,9 @@ impl Ethereum {
         conn.relay_return(network, state_root, state_proof)
     }
 
+    /// Verifies a signature from a valset signer for a given message within a
+    /// given connection then adds it to the state. This should be called by
+    /// signers whenever they have signed an outbox message.
     #[call]
     pub fn sign(
         &mut self,
@@ -176,6 +201,8 @@ impl Ethereum {
         conn.sign(msg_index, pubkey, sig)
     }
 
+    /// Creates a new connection to the given bridge contract deployment on the
+    /// given remote chain and adds it to the state.
     pub fn create_connection(
         &mut self,
         chain_id: u32,
@@ -203,6 +230,7 @@ impl Ethereum {
         Ok(())
     }
 
+    /// Gets a list of all messages that need to be signed by the given signer.
     #[query]
     pub fn to_sign(&self, xpub: Xpub) -> Result<ToSign> {
         let mut to_sign = vec![];
@@ -240,6 +268,7 @@ impl Ethereum {
         Ok(to_sign)
     }
 
+    /// Gets a network by its chain ID.
     pub fn network(&self, network: u32) -> Result<Ref<Network>> {
         Ok(self
             .networks
@@ -247,6 +276,7 @@ impl Ethereum {
             .ok_or_else(|| Error::App("Unknown network".to_string()))?)
     }
 
+    /// Gets a mutable reference to a network by its chain ID.
     pub fn network_mut(&mut self, network: u32) -> Result<ChildMut<u32, Network>> {
         Ok(self
             .networks
@@ -254,7 +284,17 @@ impl Ethereum {
             .ok_or_else(|| Error::App("Unknown network".to_string()))?)
     }
 
-    // TODO: we shouldn't need these:
+    /// Gets the current timestamp from the time context (e.g. from the
+    /// Tendermint block header).
+    fn now(&mut self) -> Result<i64> {
+        Ok(self
+            .context::<Time>()
+            .ok_or_else(|| Error::App("No time context available".into()))?
+            .seconds)
+    }
+
+    // TODO: we shouldn't need these, these are a workaround for issues within the
+    // underlying Orga client query system
     #[query]
     pub fn token_contract(&self, network: u32, connection: Address) -> Result<Address> {
         Ok(self
@@ -328,7 +368,6 @@ impl Ethereum {
             .light_client
             .block_number())
     }
-
     #[query]
     pub fn light_client(&self, chain_id: u32) -> Result<LightClient> {
         Ok(self
@@ -338,13 +377,6 @@ impl Ethereum {
             .light_client
             .clone())
     }
-
-    fn now(&mut self) -> Result<i64> {
-        Ok(self
-            .context::<Time>()
-            .ok_or_else(|| Error::App("No time context available".into()))?
-            .seconds)
-    }
 }
 type ToSign = Vec<(u32, Address, u64, u32, [u8; 32], OutMessageArgs)>;
 type Sigs = Vec<(Pubkey, Option<Signature>)>;
@@ -358,6 +390,8 @@ pub struct Network {
 
 #[orga]
 impl Network {
+    /// Creates a new Ethereum network with the given chain ID, consensus
+    /// bootstrap data, and consensus network parameters.
     pub fn new(
         id: u32,
         bootstrap: consensus::Bootstrap,
@@ -372,6 +406,8 @@ impl Network {
         })
     }
 
+    /// Advances the state of all connections in the network, should be called
+    /// once per Nomic block.
     pub fn step(&mut self, active_sigset: &SignatorySet) -> Result<()> {
         let addrs: Vec<_> = self
             .connections
@@ -386,6 +422,10 @@ impl Network {
         Ok(())
     }
 
+    /// Takes all pending transfers from all connections in the network, to be
+    /// moved into Nomic's Bitcoin state machine and eventually credited. These
+    /// transfers are either incoming from the remote EVM chain, or a bounceback
+    /// caused by a failed call or transfer.
     pub fn take_pending(&mut self) -> Result<Vec<(Dest, Coin<Nbtc>, Identity)>> {
         let addrs: Vec<_> = self
             .connections
@@ -400,6 +440,7 @@ impl Network {
         Ok(pending)
     }
 
+    /// Gets a connection by its bridge contract address.
     pub fn connection(&self, connection: Address) -> Result<Ref<Connection>> {
         Ok(self
             .connections
@@ -407,6 +448,7 @@ impl Network {
             .ok_or_else(|| Error::App("Unknown connection".to_string()))?)
     }
 
+    /// Gets a mutable reference to a connection by its bridge contract address.
     pub fn connection_mut(&mut self, connection: Address) -> Result<ChildMut<Address, Connection>> {
         Ok(self
             .connections
@@ -415,29 +457,57 @@ impl Network {
     }
 }
 
+/// A connection to a deployment of the Nomic bridge contract on a remote EVM
+/// chain.
+///
+/// This struct manages the flow of BTC and messages to and from the contract.
+/// It maintains an outbox, which is a sequential queue of messages to be
+/// relayed to the contract, and a set of emergency disbursal balances which
+/// allocates the funds bridged to the contract to Bitcoin destinations to be
+/// used if the Nomic protocol loses liveness.
 #[orga]
 pub struct Connection {
+    /// The chain ID of the remote EVM chain.
     pub chain_id: u32,
+    /// The address of the Nomic bridge contract on the remote EVM chain.
     pub bridge_contract: Address,
+    /// The address of the BTC token contract on the remote EVM chain, managed
+    /// by the bridge contract.
     pub token_contract: Address,
+    /// The interval in seconds between valset updates.
     pub valset_interval: u64,
 
+    /// The index of the current message in the outbox.
     pub message_index: u64,
+    /// The index of the next transfer batch to be sent to the contract.
     pub batch_index: u64,
+    /// The index of the current valset in the contract.
     pub valset_index: u64,
+    /// The index of the most recently processed return message from the
+    /// contract.
     pub return_index: u64,
 
+    /// The total amount of BTC accounted for in the emergency disbursal
+    /// balances.
     pub emergency_disbursal_total: u64,
+    /// The emergency disbursal balances for each Bitcoin destination.
     pub emergency_disbursal_balances: Map<Adapter<Script>, u64>,
 
+    /// An ordered queue of messages to be sent to the contract.
     pub outbox: Deque<OutMessage>,
+    /// Pending transfers to be passed to the Bitcoin state machine within the
+    /// Nomic protocol.
     pub pending: Deque<(Dest, Coin<Nbtc>, Identity)>,
+    /// The funds currently bridged to the contract.
     pub coins: Coin<Nbtc>,
+    /// The current valset of signatories for the contract.
     pub valset: SignatorySet,
 }
 
 #[orga]
 impl Connection {
+    /// Creates a new connection to the given bridge contract deployment on the
+    /// given remote chain.
     pub fn new(
         chain_id: u32,
         bridge_contract: Address,
@@ -463,8 +533,11 @@ impl Connection {
         }
     }
 
-    // TODO: method to return pending nbtc transfers
-
+    /// Advances the state of the connection, should be called once per Nomic
+    /// block.
+    ///
+    /// This function checks if a new valset update is needed, and if so, pushes
+    /// a new valset update message to the outbox.
     pub fn step(&mut self, active_sigset: &SignatorySet) -> Result<()> {
         if active_sigset.create_time - self.valset.create_time >= self.valset_interval
             && self.valset.index != active_sigset.index
@@ -475,6 +548,7 @@ impl Connection {
         Ok(())
     }
 
+    /// Validates the destination and amount of a transfer.
     pub fn validate_transfer(&self, dest: Address, amount: u64) -> Result<()> {
         let fee_amount = APPROX_TRANSFER_GAS * GAS_PRICE;
         if amount < fee_amount {
@@ -488,6 +562,8 @@ impl Connection {
         Ok(())
     }
 
+    /// Pushes a message to the outbox to transfer funds to the given Ethereum
+    /// address.
     pub fn transfer(&mut self, dest: Address, coins: Coin<Nbtc>) -> Result<()> {
         let amount: u64 = coins.amount.into();
         self.validate_transfer(dest, amount)?;
@@ -515,6 +591,7 @@ impl Connection {
         Ok(())
     }
 
+    /// Validates the destination and amount of a contract call.
     pub fn validate_contract_call(
         &self,
         max_gas: u64,
@@ -533,6 +610,7 @@ impl Connection {
         Ok(())
     }
 
+    /// Pushes a message to the outbox to call a contract with the given data.
     pub fn call_contract(
         &mut self,
         // TODO: ethaddress type
@@ -561,6 +639,8 @@ impl Connection {
         })
     }
 
+    /// Pushes a message to the outbox to update the valset to the given new
+    /// valset.
     fn update_valset(&mut self, mut new_valset: SignatorySet) -> Result<()> {
         new_valset.normalize_vp(u32::MAX as u64);
         self.valset_index += 1;
@@ -573,6 +653,7 @@ impl Connection {
         Ok(())
     }
 
+    /// Pushes a message to the outbox.
     fn push_outbox(&mut self, msg: OutMessageArgs) -> Result<()> {
         let hash = self.message_hash(&msg);
         let mut sigs = ThresholdSig::from_sigset(&self.valset)?;
@@ -592,6 +673,7 @@ impl Connection {
         Ok(())
     }
 
+    /// Takes all pending transfers from the connection.
     pub fn take_pending(&mut self) -> Result<Vec<(Dest, Coin<Nbtc>, Identity)>> {
         let mut pending = Vec::new();
         while let Some(entry) = self.pending.pop_front()? {
@@ -600,6 +682,8 @@ impl Connection {
         Ok(pending)
     }
 
+    /// Verifies a signature from a valset signer for a given message and adds
+    /// it to the state.
     #[call]
     pub fn sign(&mut self, msg_index: u64, pubkey: Pubkey, sig: Signature) -> Result<()> {
         exempt_from_fee()?;
@@ -609,6 +693,8 @@ impl Connection {
         Ok(())
     }
 
+    /// Verifies a state proof and processes the incoming transfers coming back
+    /// from the remote bridge contract deployment.
     pub fn relay_return(
         &mut self,
         network: u32,
@@ -649,6 +735,8 @@ impl Connection {
         Ok(())
     }
 
+    /// Processes an adjustment to the emergency disbursal balances received
+    /// from the remote bridge contract deployment.
     pub fn adjust_emergency_disbursal_balance(
         &mut self,
         script: Adapter<Script>,
@@ -685,17 +773,21 @@ impl Connection {
         Ok(())
     }
 
+    /// Gets a message from the outbox by its index.
     #[query]
     pub fn get(&self, msg_index: u64) -> Result<Ref<OutMessage>> {
         let index = self.abs_index(msg_index)?;
         Ok(self.outbox.get(index)?.unwrap())
     }
 
+    /// Gets a mutable reference to a message from the outbox by its index.
     pub fn get_mut(&mut self, msg_index: u64) -> Result<ChildMut<u64, OutMessage>> {
         let index = self.abs_index(msg_index)?;
         Ok(self.outbox.get_mut(index)?.unwrap())
     }
 
+    /// Gets the absolute index of a message in the outbox by its normalized
+    /// index.
     #[query]
     pub fn abs_index(&self, msg_index: u64) -> Result<u64> {
         let start_index = self.message_index + 1 - self.outbox.len();
@@ -706,6 +798,7 @@ impl Connection {
         Ok(msg_index - start_index)
     }
 
+    /// Gets the hash of an outgoing message, used for signing.
     fn message_hash(&self, msg: &OutMessageArgs) -> [u8; 32] {
         sighash(match msg {
             OutMessageArgs::Batch {
@@ -750,7 +843,6 @@ impl Connection {
     pub fn needs_sig(&self, msg_index: u64, pubkey: Pubkey) -> Result<bool> {
         Ok(self.get(msg_index)?.sigs.needs_sig(pubkey)?)
     }
-
     #[query]
     pub fn get_sigs(&self, msg_index: u64) -> Result<Vec<(Pubkey, Option<Signature>)>> {
         let sigs = &self.get(msg_index)?.sigs;
@@ -770,6 +862,8 @@ impl Connection {
     }
 }
 
+/// A container for a message to be sent to the Nomic bridge contract on a
+/// remote EVM chain via the outbox, holding the message data and signatures.
 #[orga]
 #[derive(Debug)]
 pub struct OutMessage {
@@ -778,13 +872,17 @@ pub struct OutMessage {
     pub msg: OutMessageArgs,
 }
 
+/// The core data of a message to be sent to the Nomic bridge contract on a
+/// remote EVM chain.
 #[derive(Encode, Decode, Debug, Clone, Serialize)]
 pub enum OutMessageArgs {
+    /// A batch of funds transfers.
     Batch {
         transfers: LengthVec<u16, Transfer>,
         timeout: u64,
         batch_index: u64,
     },
+    /// A user-defined contract call.
     ContractCall {
         // TODO: ethaddress type
         #[serde(with = "SerHex::<StrictPfx>")]
@@ -798,6 +896,7 @@ pub enum OutMessageArgs {
         fee_amount: u64,
         message_index: u64,
     },
+    /// An update to the validator set.
     UpdateValset(u64, SignatorySet),
 }
 
@@ -846,6 +945,8 @@ impl Describe for OutMessageArgs {
     }
 }
 
+/// Gets the hash of an outgoing message transferring funds to a user-defined
+/// contract call.
 #[allow(clippy::too_many_arguments)]
 pub fn call_hash(
     chain_id: u32,
@@ -876,6 +977,8 @@ pub fn call_hash(
     keccak256(bytes).0
 }
 
+/// Converts a contract call message to the struct used in the Alloy-generated
+/// contract client.
 #[cfg(feature = "ethereum-full")]
 #[allow(clippy::too_many_arguments)]
 pub fn logic_call_args(
@@ -904,6 +1007,7 @@ pub fn logic_call_args(
     }
 }
 
+/// A transfer of funds to a given destination Ethereum address.
 #[orga]
 #[derive(Debug, Clone)]
 pub struct Transfer {
@@ -912,6 +1016,7 @@ pub struct Transfer {
     pub fee_amount: u64,
 }
 
+/// Gets the hash of a validator set.
 pub fn checkpoint_hash(
     chain_id: u32,
     bridge_contract: Address,
@@ -941,6 +1046,7 @@ pub fn checkpoint_hash(
     keccak256(bytes).0
 }
 
+/// Gets the hash of a batch of funds transfers.
 pub fn batch_hash(
     chain_id: u32,
     bridge_contract: Address,
@@ -972,6 +1078,7 @@ pub fn batch_hash(
     keccak256(bytes).0
 }
 
+/// Hashes a message for signing.
 pub fn sighash(message: [u8; 32]) -> [u8; 32] {
     let mut bytes = b"\x19Ethereum Signed Message:\n32".to_vec();
     bytes.extend_from_slice(&message);
@@ -979,6 +1086,8 @@ pub fn sighash(message: [u8; 32]) -> [u8; 32] {
     keccak256(bytes).0
 }
 
+/// Converts a secp256k1 ECDSA signature to components used with the
+/// Alloy-generated contract client.
 pub fn to_eth_sig(
     sig: &bitcoin::secp256k1::ecdsa::Signature,
     pubkey: &PublicKey,
@@ -1009,6 +1118,7 @@ pub fn to_eth_sig(
     (v, r, s)
 }
 
+/// Converts a slice of at most 32 bytes to a right-padded 32-byte array.
 pub fn bytes32(bytes: &[u8]) -> Result<[u8; 32]> {
     if bytes.len() > 32 {
         return Err(Error::App("bytes too long".to_string()).into());
@@ -1019,12 +1129,14 @@ pub fn bytes32(bytes: &[u8]) -> Result<[u8; 32]> {
     Ok(padded)
 }
 
+/// Converts an integer to a big-endian, left-padded 32-byte array.
 pub fn uint256(n: u64) -> [u8; 32] {
     let mut bytes = [0; 32];
     bytes[24..].copy_from_slice(&n.to_be_bytes());
     bytes
 }
 
+/// Converts a 20-byte address to a left-padded 32-byte array.
 pub fn addr_to_bytes32(addr: Address) -> [u8; 32] {
     let mut bytes = [0; 32];
     bytes[12..].copy_from_slice(&addr.bytes());
@@ -1032,6 +1144,7 @@ pub fn addr_to_bytes32(addr: Address) -> [u8; 32] {
 }
 
 impl SignatorySet {
+    /// Gets the Ethereum addresses of the signatories in the set.
     pub fn eth_addresses(&self) -> Vec<Address> {
         self.signatories
             .iter()
@@ -1044,6 +1157,8 @@ impl SignatorySet {
             .collect()
     }
 
+    /// Normalizes the voting power of the signatories in the set to the given
+    /// total voting power.
     pub fn normalize_vp(&mut self, total: u64) {
         let adjust = |n: u64| (n as u128 * total as u128 / self.present_vp as u128) as u64;
 
@@ -1054,6 +1169,8 @@ impl SignatorySet {
         self.present_vp = total;
     }
 
+    /// Converts the set to the struct used in the Alloy-generated contract
+    /// client.
     #[cfg(feature = "ethereum-full")]
     pub fn to_abi(&self, nonce: u64) -> ValsetArgs {
         ValsetArgs {

From 32c24fa9ed89dfc6cc390ac7bdf00a173a111814 Mon Sep 17 00:00:00 2001
From: Matt Bell <mappum@gmail.com>
Date: Mon, 28 Oct 2024 07:36:28 -0500
Subject: [PATCH 2/2] Add additional ethereum doc comments

---
 src/ethereum/mod.rs     |  3 ---
 src/ethereum/proofs.rs  | 24 ++++++++++++++++++++++++
 src/ethereum/relayer.rs |  2 ++
 src/ethereum/signer.rs  |  3 +++
 4 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/src/ethereum/mod.rs b/src/ethereum/mod.rs
index 02970046..df4e1bf5 100644
--- a/src/ethereum/mod.rs
+++ b/src/ethereum/mod.rs
@@ -1,6 +1,3 @@
-#![warn(missing_docs)]
-#![warn(clippy::missing_docs_in_private_items)]
-
 use alloy_core::{
     primitives::keccak256,
     sol_types::{sol, SolValue},
diff --git a/src/ethereum/proofs.rs b/src/ethereum/proofs.rs
index b426698c..2be2c211 100644
--- a/src/ethereum/proofs.rs
+++ b/src/ethereum/proofs.rs
@@ -16,6 +16,7 @@ use rlp::{Decodable as _, Rlp};
 use rlp_derive::RlpDecodable;
 use trie_db::{Trie, TrieDBBuilder};
 
+/// Account data from the Ethereum trie.
 #[derive(RlpDecodable, Debug)]
 struct Account {
     _nonce: u64,
@@ -41,6 +42,8 @@ pub struct StateProof {
 }
 
 impl StateProof {
+    /// Creates a new `StateProof` from the given account proof and list of dest
+    /// strings.
     pub fn from_response(
         proof: EIP1186AccountProofResponse,
         dests: Vec<(String, u64)>,
@@ -91,6 +94,8 @@ impl StateProof {
         })
     }
 
+    /// Verifies the proof against the given state root and returns the decoded
+    /// data.
     pub fn verify(self, state_root: [u8; 32]) -> AppResult<Vec<BridgeContractData>> {
         let result = verify_key(
             state_root,
@@ -218,10 +223,15 @@ pub struct BridgeContractData {
 }
 
 impl BridgeContractData {
+    /// Slot in the trie for the dest strings of the return message queue.
     pub const RETURN_DESTS_SLOT: u64 = 7;
+    /// Slot in the trie for the fund amounts of the return message queue.
     pub const RETURN_AMOUNTS_SLOT: u64 = 8;
+    /// Slot in the trie for the sender addresses of the return message queue.
     pub const RETURN_SENDERS_SLOT: u64 = 9;
 
+    /// Returns the trie keys for the given dest string at the given return
+    /// queue index.
     pub fn dest_keys(value: &str, index: u64) -> Vec<[u8; 32]> {
         let num_keys = 1 + (value.len() + 31) / 32;
 
@@ -242,21 +252,29 @@ impl BridgeContractData {
         res
     }
 
+    /// Returns the trie key for the head of the dest string at the given return
+    /// queue index.
     pub fn dest_key(index: u64) -> [u8; 32] {
         let index = U256::from(index);
         Self::get_key(index, Self::RETURN_DESTS_SLOT.into())
     }
 
+    /// Returns the trie key for the sender address at the given return queue
+    /// index.
     pub fn sender_key(index: u64) -> [u8; 32] {
         let index = U256::from(index);
         Self::get_key(index, Self::RETURN_SENDERS_SLOT.into())
     }
 
+    /// Returns the trie key for the fund amount at the given return queue
+    /// index.
     pub fn amount_key(index: u64) -> [u8; 32] {
         let index = U256::from(index);
         Self::get_key(index, Self::RETURN_AMOUNTS_SLOT.into())
     }
 
+    /// Returns the trie key for the chunk of the dest string at the given
+    /// return queue index.
     pub fn dest_chunk_key(index: u64, chunk_index: u64) -> [u8; 32] {
         let slot_key = Self::dest_key(index);
         let chunk_base = keccak_256(slot_key.as_slice());
@@ -268,6 +286,7 @@ impl BridgeContractData {
         key_bytes
     }
 
+    /// Returns the trie key for the given index and slot.
     fn get_key(index: U256, slot: U256) -> [u8; 32] {
         let mut index_bytes = [0u8; 32];
         index.to_big_endian(&mut index_bytes);
@@ -278,6 +297,11 @@ impl BridgeContractData {
     }
 }
 
+/// Returns the number of extra 32-byte slots required to store the given length
+/// of string data.
+///
+/// Strings less than 32 bytes can be stored inline in one slot, while longer
+/// strings are chunked across additional slots.
 pub fn extra_slots_required(len: usize) -> usize {
     (len + 31) / 32
 }
diff --git a/src/ethereum/relayer.rs b/src/ethereum/relayer.rs
index b27de667..8abc8731 100644
--- a/src/ethereum/relayer.rs
+++ b/src/ethereum/relayer.rs
@@ -6,6 +6,8 @@ use alloy_primitives::Uint;
 use alloy_provider::Provider;
 use alloy_transport::Transport;
 
+/// Builds a proof of the account and storage for state slots relevant to the
+/// return message queue in the bridge contract.
 pub async fn get_state_proof<
     T: Clone + Transport,
     P: Provider<T, alloy_provider::network::Ethereum> + Clone,
diff --git a/src/ethereum/signer.rs b/src/ethereum/signer.rs
index 2a8f8d22..d8bc1f69 100644
--- a/src/ethereum/signer.rs
+++ b/src/ethereum/signer.rs
@@ -13,6 +13,8 @@ impl<W: Wallet, F> Signer<W, F>
 where
     F: Fn() -> AppClient<InnerApp, InnerApp, HttpClient, Nom, W>,
 {
+    /// Starts a loop which constantly queries for Ethereum messages to sign and
+    /// submits the signatures.
     pub async fn start_ethereum_signing(
         &self,
         key_pairs: Vec<(ExtendedPubKey, &ExtendedPrivKey)>,
@@ -28,6 +30,7 @@ where
         }
     }
 
+    /// Queries for outbox messages to sign, then signs and submits each.
     async fn sign_eth_messages(
         &self,
         xpub: &ExtendedPubKey,