diff --git a/module-system/sov-modules-stf-template/Cargo.toml b/module-system/sov-modules-stf-template/Cargo.toml index 341b36a87..577470e7a 100644 --- a/module-system/sov-modules-stf-template/Cargo.toml +++ b/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 } diff --git a/module-system/sov-modules-stf-template/README.md b/module-system/sov-modules-stf-template/README.md index 48532e940..20f0078f8 100644 --- a/module-system/sov-modules-stf-template/README.md +++ b/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 { 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 { diff --git a/module-system/sov-modules-stf-template/src/app_template.rs b/module-system/sov-modules-stf-template/src/app_template.rs index 4b35f3446..9b8595ba5 100644 --- a/module-system/sov-modules-stf-template/src/app_template.rs +++ b/module-system/sov-modules-stf-template/src/app_template.rs @@ -14,8 +14,13 @@ use crate::{Batch, SequencerOutcome, SlashingReason, TxEffect}; type ApplyBatchResult = Result; +/// An implementation of the +/// [`StateTransitionFunction`](sov_rollup_interface::stf::StateTransitionFunction) +/// that is specifically designed to work with the module-system. pub struct AppTemplate { + /// 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>, phantom_vm: PhantomData, @@ -23,10 +28,10 @@ pub struct AppTemplate { } 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, @@ -64,6 +69,7 @@ where + TxHooks + ApplyBlobHooks, { + /// [`AppTemplate`] constructor. pub fn new(storage: C::Storage, runtime: RT) -> Self { Self { runtime, @@ -272,7 +278,7 @@ where &self, batch: Batch, ) -> Result>, 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); diff --git a/module-system/sov-modules-stf-template/src/batch.rs b/module-system/sov-modules-stf-template/src/batch.rs index 074eadee6..c5ffd7a56 100644 --- a/module-system/sov-modules-stf-template/src/batch.rs +++ b/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, } - -impl Batch { - pub fn transactions(&self) -> &[RawTx] { - &self.txs - } - - pub fn take_transactions(self) -> Vec { - self.txs - } -} diff --git a/module-system/sov-modules-stf-template/src/lib.rs b/module-system/sov-modules-stf-template/src/lib.rs index 6b6057574..ae1bf9bc5 100644 --- a/module-system/sov-modules-stf-template/src/lib.rs +++ b/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, }, /// 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, } diff --git a/module-system/sov-modules-stf-template/src/tx_verifier.rs b/module-system/sov-modules-stf-template/src/tx_verifier.rs index 0e130310a..f8e15eeb0 100644 --- a/module-system/sov-modules-stf-template/src/tx_verifier.rs +++ b/module-system/sov-modules-stf-template/src/tx_verifier.rs @@ -16,6 +16,7 @@ pub(crate) struct TransactionAndRawHash { /// 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, }