Add missing doc for the sov-modules-stf-template crate. (#540)

module-system/sov-modules-stf-template/Cargo.toml

@@ -11,8 +11,6 @@ version = { workspace = true }
 readme = "README.md"
 resolver = "2"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
 anyhow = { workspace = true }
 borsh = { workspace = true }

module-system/sov-modules-stf-template/README.md

@@ -4,7 +4,7 @@
 
 This crate contains an implementation of a `StateTransitionFunction` called `AppTemplate` that is specifically designed to work with the Module System. The `AppTemplate` relies on a set of traits that, when combined, define the logic for transitioning the rollup state.
 
-```rust
+```rust ignore
 pub struct AppTemplate<C: Context, RT, Vm> {
     pub current_storage: C::Storage,
     pub runtime: RT,
@@ -35,7 +35,7 @@ where
 
 Both the `DispatchCall` and `Genesis` traits can be automatically derived (see `RT` in the above snippet) for any set of modules:
 
-```rust
+```rust ignore
 #[derive(Genesis, DispatchCall, MessageCodec)]
 #[serialization(borsh::BorshDeserialize, borsh::BorshSerialize)]
 pub struct Runtime<C: Context> {

module-system/sov-modules-stf-template/src/app_template.rs

@@ -14,19 +14,24 @@ use crate::{Batch, SequencerOutcome, SlashingReason, TxEffect};
 
 type ApplyBatchResult<T> = Result<T, ApplyBatchError>;
 
+/// An implementation of the
+/// [`StateTransitionFunction`](sov_rollup_interface::stf::StateTransitionFunction)
+/// that is specifically designed to work with the module-system.
 pub struct AppTemplate<C: Context, RT, Vm, B> {
+    /// State storage used by the rollup.
     pub current_storage: C::Storage,
+    /// The runtime includes all the modules that the rollup supports.
     pub runtime: RT,
     pub(crate) checkpoint: Option<StateCheckpoint<C::Storage>>,
     phantom_vm: PhantomData<Vm>,
     phantom_blob: PhantomData<B>,
 }
 
 pub(crate) enum ApplyBatchError {
-    /// Contains batch hash
+    // Contains batch hash
     Ignored([u8; 32]),
     Slashed {
-        /// Contains batch hash
+        // Contains batch hash
         hash: [u8; 32],
         reason: SlashingReason,
         sequencer_da_address: Vec<u8>,
@@ -64,6 +69,7 @@ where
         + TxHooks<Context = C>
         + ApplyBlobHooks<Context = C, BlobResult = SequencerOutcome>,
 {
+    /// [`AppTemplate`] constructor.
     pub fn new(storage: C::Storage, runtime: RT) -> Self {
         Self {
             runtime,
@@ -272,7 +278,7 @@ where
         &self,
         batch: Batch,
     ) -> Result<Vec<TransactionAndRawHash<C>>, SlashingReason> {
-        match verify_txs_stateless(batch.take_transactions()) {
+        match verify_txs_stateless(batch.txs) {
             Ok(txs) => Ok(txs),
             Err(e) => {
                 error!("Stateless verification error - the sequencer included a transaction which was known to be invalid. {}\n", e);

module-system/sov-modules-stf-template/src/batch.rs

@@ -1,20 +1,11 @@
 use borsh::{BorshDeserialize, BorshSerialize};
 use serde::{Deserialize, Serialize};
 
-// use sov_rollup_interface::traits::TransactionTrait;
 use crate::tx_verifier::RawTx;
 
+/// Contains raw transactions obtained from the DA blob.
 #[derive(Debug, PartialEq, Clone, BorshDeserialize, BorshSerialize, Serialize, Deserialize)]
 pub struct Batch {
+    /// Raw transactions.
     pub txs: Vec<RawTx>,
 }
-
-impl Batch {
-    pub fn transactions(&self) -> &[RawTx] {
-        &self.txs
-    }
-
-    pub fn take_transactions(self) -> Vec<RawTx> {
-        self.txs
-    }
-}

module-system/sov-modules-stf-template/src/lib.rs

@@ -1,4 +1,6 @@
-pub mod app_template;
+#![deny(missing_docs)]
+#![doc = include_str!("../README.md")]
+mod app_template;
 mod batch;
 mod tx_verifier;
 
@@ -12,33 +14,43 @@ use sov_rollup_interface::zk::Zkvm;
 use sov_state::{StateCheckpoint, Storage};
 pub use tx_verifier::RawTx;
 
+/// The receipts of all the transactions in a batch.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub enum TxEffect {
+    /// Batch was reverted.
     Reverted,
+    /// Batch was processed successfully.
     Successful,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 // TODO: Should be generic for Address for pretty printing https://github.com/Sovereign-Labs/sovereign-sdk/issues/465
+/// Represents the different outcomes that can occur for a sequencer after batch processing.
 pub enum SequencerOutcome {
     /// Sequencer receives reward amount in defined token and can withdraw its deposit
     Rewarded(u64),
     /// Sequencer loses its deposit and receives no reward
     Slashed {
+        /// Reason why sequencer was slashed.
         reason: SlashingReason,
         // Keep this comment for so it doesn't need to investigate serde issue again.
         // https://github.com/Sovereign-Labs/sovereign-sdk/issues/465
         // #[serde(bound(deserialize = ""))]
+        /// Sequencer address on DA.
         sequencer_da_address: Vec<u8>,
     },
     /// Batch was ignored, sequencer deposit left untouched.
     Ignored,
 }
 
+/// Reason why sequencer was slashed.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub enum SlashingReason {
+    /// This status indicates problem with batch deserialization.
     InvalidBatchEncoding,
+    /// Stateless verification failed, for example deserialized transactions have invalid signatures.
     StatelessVerificationFailed,
+    /// This status indicates problem with transaction deserialization.
     InvalidTransactionEncoding,
 }
 

module-system/sov-modules-stf-template/src/tx_verifier.rs

@@ -16,6 +16,7 @@ pub(crate) struct TransactionAndRawHash<C: Context> {
 /// RawTx represents a serialized rollup transaction received from the DA.
 #[derive(Debug, PartialEq, Clone, BorshDeserialize, BorshSerialize, Serialize, Deserialize)]
 pub struct RawTx {
+    /// Serialized transaction.
     pub data: Vec<u8>,
 }