Add missing docs for bank, prover-incentives, demo-rollup and const-r…

…ollup-config (#592) * WIP: Add optimsitic sync * WIP: implement chain state module * WIP: Add attester incentives * Can compile * Does compile * Start working on attester incentives * Implement attestation processing * Finish unbonding * Improve events * Rename sov-attester-incentives to optimistic-workflow * Refactor * Start working on apply_sync_data_blob * Refactoring apply_tx_blob * Refactoring files * Rewriting unbonding * Refactor attestation processing * Refactor process challenge * Refactoring * Fixing compile issues * Does compile * Everything compiles * Add 2 phase unbonding back * Updating tests * Changing bonding proof * Changing bonding proof * Fixing get_with_proof * Fixing chain updates * Missing docs bank * Missing docs prover-incentives * Missing docs const-rollup-config * demo-rollup missing docs, finish missing docs * Refactoring buf reader * Fixing lint error * Change STF interface to work on slot level * Removing Misbehavour hint from parameters * Fixing prover * Update docs * Adding chain state * Starting chain state * Fix lint * Fixing warnings * Integrating slot hooks * Populating todos * Adding data generation for different modules * Implementing automatic bank data generation * Fixing stf * Compiles * Fixing chain-state test, adding EncodeCall trait * Fixing lints * Chain state testing * Simple chain state module tests * All tests pass * Fixing lints * Fixing comments PR * Fixing comments PR * nit fix * Fixing PR comments * Deleting borsh compat * Adding missing_docs * Adding back github and config files * Specifying commit for jmt * Update module-system/sov-state/src/storage.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Fixing comments PR * Fix rpc macro * Fixing missing docs * Applying PR comments * Update adapters/risc0/src/host.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Update adapters/risc0/src/host.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Fixing error handling * Fixing lints * Fixing lints * Fix lints * Refactor buf reader * Fixing tests * Update rollup-interface/src/state_machine/mocks.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Addressing PR comments * Including PR comments * Update Cargo.toml Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Update adapters/risc0/src/guest.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Update adapters/risc0/src/host.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Update adapters/risc0/src/host.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Adding back genesis and call * Fix lints * Lint * Restoring default context * Fixing imports * Fixing prover compiles * Fix prover compiles * Fixing end slot hook * Reorganizing integration tests * Reorganizing integration tests * Adding unit tests for chain-state * Update chain state tests * Update apply slot signature * Fix demo-prover * Update adapters/risc0/src/guest.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Update adapters/risc0/src/host.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Fix lints * Format demo-prover * Fix feature data generators * Merge with chain-state and fix lints * Update examples/demo-stf/Cargo.toml Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Update adapters/risc0/src/guest.rs Co-authored-by: Nikolai Golub <nikolai@sovlabs.io> * Fixing pr comments * Fix lint * Fix doctests demo rollup * Add folder generated by README test to gitignore --------- Co-authored-by: Preston Evans <preston.b.evans@gmail.com> Co-authored-by: Nikolai Golub <nikolai@sovlabs.io>
Sovereign-Labs · Aug 10, 2023 · 4e5c2ff · 4e5c2ff
1 parent 154cbbe
commit 4e5c2ff
Show file tree

Hide file tree

Showing 22 changed files with 633 additions and 192 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/examples/const-rollup-config/src/lib.rs b/examples/const-rollup-config/src/lib.rs
@@ -1,3 +1,8 @@
-// The rollup stores its data in the namespace b"sov-test" on Celestia.
+/// The namespace used by the rollup to store its data. This is a raw slice of 8 bytes.
+/// The rollup stores its data in the namespace b"sov-test" on Celestia. Which in this case is encoded using the
+/// ascii representation of each character.
 pub const ROLLUP_NAMESPACE_RAW: [u8; 8] = [115, 111, 118, 45, 116, 101, 115, 116];
+
+/// The DA address of the sequencer (for now we use a centralized sequencer) in the tests.
+/// Here this is the address of the sequencer on the celestia blockchain.
 pub const SEQUENCER_DA_ADDRESS: [u8; 47] = *b"celestia1w7wcupk5gswj25c0khnkey5fwmlndx6t5aarmk";
diff --git a/examples/demo-rollup/.gitignore b/examples/demo-rollup/.gitignore
@@ -1,2 +1,3 @@
 /target
 /demo_data
+/path_readme
diff --git a/examples/demo-rollup/README.md b/examples/demo-rollup/README.md
@@ -67,32 +67,32 @@ understand how to build your own state transition function, check out at the doc
 
 2. Switch to the `examples/demo-rollup` directory (which is where this `README.md` is located!).
 
-   ```
-   $ cd examples/demo-rollup/
-   ```
+```shell
+$ cd examples/demo-rollup/
+```
 
 3. Spin up a local Celestia instance as your DA layer. We've built a small Makefile to simplify that process:
 
-   ```
-   $ make clean
-   $ make start   # Make sure to run `make stop` when you're done with this demo!
-   ```
+```sh
+$ make clean
+$ make start   # Make sure to run `make stop` when you're done with this demo!
+```
 
-   If interested, you can check out what the Makefile does [here](#Makefile).  
-   The above command will also modify some configuration files:
+If interested, you can check out what the Makefile does [here](#Makefile).  
+ The above command will also modify some configuration files:
 
-   ```
-   $ git status
-   ..
-   ..
-   	modified:   rollup_config.toml
-   ```
+```sh
+$ git status
+..
+..
+	modified:   rollup_config.toml
+```
 
 ### Start the Rollup Full Node
 
 Now run the demo-rollup full node, as shown below. You will see it consuming blocks from the Celestia node running inside Docker:
 
-```
+```sh
 # Make sure you're still in the examples/demo-rollup directory.
 $ cargo run
 2023-06-07T10:03:25.473920Z  INFO jupiter::da_service: Fetching header at height=1...
@@ -112,13 +112,13 @@ Leave it running while you proceed with the rest of the demo.
 
 After switching to a new terminal tab, let's submit our first transaction by creating a token:
 
-```
+```sh
 $ make test-create-token
 ```
 
 ...wait a few seconds and you will see the transaction receipt in the output of the demo-rollup full node:
 
-```
+```sh
 2023-07-12T15:04:52.291073Z  INFO jupiter::da_service: Fetching header at height=31...
 2023-07-12T15:05:02.304393Z  INFO sov_demo_rollup: Received 1 blobs at height 31
 2023-07-12T15:05:02.305257Z  INFO sov_demo_rollup: blob #0 at height 31 with blob_hash 0x4876c2258b57104356efa4630d3d9f901ccfda5dde426ba8aef81d4a3e357c79 has been applied with #1 transactions, sequencer outcome Rewarded(0)
@@ -134,7 +134,7 @@ The `make test-create-token` command above was useful to test if everything is r
 
 You'll need the `sov-cli` binary in order to create transactions. Build it with these commands:
 
-```console
+```sh
 $ cd ../demo-stf   # Assuming you're still in examples/demo-rollup/
 $ cargo build --bin sov-cli
 $ cd ../..   # Go back to the root of the repository
@@ -160,6 +160,10 @@ Options:
 Each transaction that we want to submit is a member of the `CallMessage` enum defined as part of creating a module. For example, let's consider the `Bank` module's `CallMessage`:
 
 ```rust
+use sov_bank::CallMessage::Transfer;
+use sov_bank::Coins;
+use sov_bank::Amount;
+
 pub enum CallMessage<C: sov_modules_api::Context> {
     /// Creates a new token with the specified name and initial balance.
     CreateToken {
@@ -180,19 +184,19 @@ pub enum CallMessage<C: sov_modules_api::Context> {
         /// The address to which the tokens will be transferred.
         to: C::Address,
         /// The amount of tokens to transfer.
-        coins: Coins<C>,
+        coins: Coins::<C>,
     },
 
     /// Burns a specified amount of tokens.
     Burn {
         /// The amount of tokens to burn.
-        coins: Coins<C>,
+        coins: Coins::<C>,
     },
 
     /// Mints a specified amount of tokens.
     Mint {
         /// The amount of tokens to mint.
-        coins: Coins<C>,
+        coins: Coins::<C>,
         /// Address to mint tokens to
         minter_address: C::Address,
     },
@@ -208,7 +212,9 @@ pub enum CallMessage<C: sov_modules_api::Context> {
 In the above snippet, we can see that `CallMessage` in `Bank` support five different types of calls. The `sov-cli` has the ability to parse a JSON file that aligns with any of these calls and subsequently serialize them. The structure of the JSON file, which represents the call, closely mirrors that of the Enum member. Consider the `Transfer` message as an example:
 
 ```rust
-Transfer {
+use sov_bank::Coins;
+
+struct Transfer<C: sov_modules_api::Context>  {
     /// The address to which the tokens will be transferred.
     to: C::Address,
     /// The amount of tokens to transfer.
@@ -241,7 +247,7 @@ Note: we're able to make a `Transfer` call here because we already created the t
 
 To generate transactions you can use the `sov-cli generate-transaction-from-json` subcommand, as shown below:
 
-```
+```sh
 $ ./target/debug/sov-cli generate-transaction-from-json -h
 Serialize a call to a module. This creates a .dat file containing the serialized transaction
 
@@ -258,13 +264,13 @@ For our test, we'll use the test private key located at `examples/test-data/keys
 
 Let's go ahead and serialize the transaction:
 
-```
+```bash
 $ ./target/debug/sov-cli generate-transaction-from-json ./examples/test-data/keys/minter_private_key.json Bank ./examples/test-data/requests/transfer.json 0
 ```
 
 Once the above command executes successfully, there will be a file named `./examples/test-data/requests/transfer.dat`:
 
-```
+```bash
 $ cat ./examples/test-data/requests/transfer.dat
 5ef848746e8d2b9c27ee46210e185dc9f3b690d5cef42a13fb9c336bd40c798210bf7af613997f7af57c9681a242f5fe4121a1539ba4f5f32f14c49f978b990a7b758bf2e7670fafaf6bf0015ce0ff5aa802306fc7e3f45762853ffc37180fe64a0000000001fea6ac5b8751120fb62fff67b54d2eac66aef307c7dde1d394dea1e09e43dd44c800000000000000135d23aee8cb15c890831ff36db170157acaac31df9bba6cd40e7329e608eabd0000000000000000
 ```
@@ -275,7 +281,7 @@ The above is the hex representation of the serialized transaction.
 
 After serializing your transactions (just one in this case), you must bundle them into a blob. You can use the `sov-cli make-batch` subcommand:
 
-```
+```bash
 $ ./target/debug/sov-cli make-batch -h
 Usage: sov-cli make-batch [PATH_LIST]...
 
@@ -285,7 +291,7 @@ Arguments:
 
 Use the command below to store the serialized blob in `./examples/test-data/requests/tx_blob`:
 
-```
+```bash
 $ ./target/debug/sov-cli make-batch ./examples/test-data/requests/transfer.dat > ./examples/test-data/requests/tx_blob
 $ cat ./examples/test-data/requests/tx_blob
 01000000b60000005ef848746e8d2b9c27ee46210e185dc9f3b690d5cef42a13fb9c336bd40c798210bf7af613997f7af57c9681a242f5fe4121a1539ba4f5f32f14c49f978b990a7b758bf2e7670fafaf6bf0015ce0ff5aa802306fc7e3f45762853ffc37180fe64a0000000001fea6ac5b8751120fb62fff67b54d2eac66aef307c7dde1d394dea1e09e43dd44c800000000000000135d23aee8cb15c890831ff36db170157acaac31df9bba6cd40e7329e608eabd0000000000000000
@@ -295,7 +301,7 @@ $ cat ./examples/test-data/requests/tx_blob
 
 You now have a blob with one serialized transaction in `./examples/test-data/requests/tx_blob`. Switch back to the `examples/demo-rollup` directory and use the Makefile to submit it:
 
-```
+```bash
 $ cd examples/demo-rollup
 $ SERIALIZED_BLOB_PATH=../test-data/requests/tx_blob make submit-txn
 ```
@@ -304,7 +310,7 @@ Here the `make submit-txn` command locates the Docker container the Celestia ins
 
 #### 5. Verify the Token Supply
 
-```
+```bash
 $ curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"bank_supplyOf","params":["sov1zdwj8thgev2u3yyrrlekmvtsz4av4tp3m7dm5mx5peejnesga27svq9m72"],"id":1}' http://127.0.0.1:12345
 {"jsonrpc":"2.0","result":{"amount":1000},"id":1}
 ```
@@ -379,11 +385,18 @@ automatically picked up by the node implementation. For this tutorial, the Makef
 The next step is to initialize your state transition function.
 
 ```rust
-  let mut app: App<Risc0Verifier, jupiter::BlobWithSender> =
+  use demo_stf::app::App;
+  use risc0_adapter::host::Risc0Verifier;
+  use jupiter::verifier::ChainValidityCondition;
+  use sov_stf_runner::StorageConfig;
+  use std::path::PathBuf;
+
+  let config = StorageConfig { path: PathBuf::from("path_readme") };
+
+  let mut app: App<Risc0Verifier, ChainValidityCondition, jupiter::BlobWithSender> =
         App::new(config);
 ```
 
-
 ### 3. Run the Main Loop
 
 The full node implements a simple loop for processing blocks. The workflow is:

diff --git a/examples/demo-rollup/src/ledger_rpc.rs b/examples/demo-rollup/src/ledger_rpc.rs
@@ -60,6 +60,8 @@ fn register_ledger_rpc_methods<
     Ok(())
 }
 
+/// Register rpc methods for the provided `ledger_db`.
+/// Calls the internal [`register_ledger_rpc_methods`] function.
 pub fn get_ledger_rpc<
     B: Serialize + DeserializeOwned + Clone + 'static,
     T: Serialize + DeserializeOwned + Clone + 'static,
@@ -76,6 +78,7 @@ mod query_args {
     use serde::de::DeserializeOwned;
     use sov_rollup_interface::rpc::QueryMode;
 
+    /// A structure containing serialized query arguments for RPC queries.
     #[derive(serde::Deserialize)]
     pub struct QueryArgs<I>(pub Vec<I>, #[serde(default)] pub QueryMode);
 

diff --git a/examples/demo-rollup/src/lib.rs b/examples/demo-rollup/src/lib.rs
@@ -1 +1,4 @@
+#![deny(missing_docs)]
+#![doc = include_str!("../README.md")]
+/// A very simple example of rollup configuration.
 pub mod rng_xfers;
diff --git a/examples/demo-rollup/src/main.rs b/examples/demo-rollup/src/main.rs
@@ -35,6 +35,7 @@ const TX_SIGNER_PRIV_KEY_PATH: &str = "../test-data/keys/tx_signer_private_key.j
 // You can change this constant to point your rollup at a different namespace
 const ROLLUP_NAMESPACE: NamespaceId = NamespaceId(ROLLUP_NAMESPACE_RAW);
 
+/// Initializes a [`LedgerDB`] using the provided `path`.
 pub fn initialize_ledger(path: impl AsRef<std::path::Path>) -> LedgerDB {
     LedgerDB::with_path(path).expect("Ledger DB failed to open")
 }
@@ -76,6 +77,9 @@ pub fn get_genesis_config() -> GenesisConfig<DefaultContext> {
     )
 }
 
+/// Main demo runner. Initialize a DA chain, and starts a demo-rollup using the config provided
+/// (or a default config if not provided). Then start checking the blocks sent to the DA layer in
+/// the main event loop.
 #[derive(Debug, BorshSerialize, BorshDeserialize)]
 pub struct CelestiaChainChecker {
     current_block_hash: [u8; 32],

diff --git a/examples/demo-rollup/src/rng_xfers.rs b/examples/demo-rollup/src/rng_xfers.rs
@@ -16,6 +16,7 @@ use sov_rollup_interface::mocks::{
 };
 use sov_rollup_interface::services::da::DaService;
 
+/// A simple DaService for a random number generator.
 pub struct RngDaService;
 
 fn generate_transfers(n: usize, start_nonce: u64) -> Vec<u8> {
@@ -74,6 +75,7 @@ fn generate_create(start_nonce: u64) -> Vec<u8> {
 }
 
 impl RngDaService {
+    /// Instantiate a new [`RngDaService`]
     pub fn new() -> Self {
         RngDaService
     }
@@ -85,6 +87,7 @@ impl Default for RngDaService {
     }
 }
 
+/// A simple DaSpec for a random number generator.
 pub struct RngDaSpec;
 
 impl DaSpec for RngDaSpec {

diff --git a/full-node/sov-ethereum/src/lib.rs b/full-node/sov-ethereum/src/lib.rs
@@ -113,7 +113,7 @@ pub mod experimental {
                 let data: Bytes = parameters.one().unwrap();
                 let data = RethBytes::from(data.as_ref());
 
-                let evm_transaction: EvmTransaction = data.try_into()?;
+                let evm_transaction: EvmTransaction = data.try_into().expect("Not an evm tx");
 
                 let tx_hash = evm_transaction.hash;
                 let raw_tx = ethereum

diff --git a/module-system/module-implementations/sov-bank/src/call.rs b/module-system/module-implementations/sov-bank/src/call.rs
@@ -53,14 +53,16 @@ pub enum CallMessage<C: sov_modules_api::Context> {
         minter_address: C::Address,
     },
 
-    /// Freeze a token so that the supply is frozen
+    /// Freezes a token so that the supply is frozen
     Freeze {
         /// Address of the token to be frozen
         token_address: C::Address,
     },
 }
 
 impl<C: sov_modules_api::Context> Bank<C> {
+    /// Creates a token from a set of configuration parameters.
+    /// Checks if a token already exists at that address. If so return an error.
     #[allow(clippy::too_many_arguments)]
     pub(crate) fn create_token(
         &self,
@@ -94,6 +96,8 @@ impl<C: sov_modules_api::Context> Bank<C> {
         Ok(CallResponse::default())
     }
 
+    /// Transfers the set of `coins` to the address specified by `to`.
+    /// Helper function that calls the [`transfer_from`] method from the bank module
     pub fn transfer(
         &self,
         to: C::Address,
@@ -104,6 +108,9 @@ impl<C: sov_modules_api::Context> Bank<C> {
         self.transfer_from(context.sender(), &to, coins, working_set)
     }
 
+    /// Burns the set of `coins`. If there is no token at the address specified in the
+    /// `Coins` structure, return an error.
+    /// Calls the [`Token::burn`] function and updates the total supply of tokens.
     pub(crate) fn burn(
         &self,
         coins: Coins<C>,
@@ -130,6 +137,8 @@ impl<C: sov_modules_api::Context> Bank<C> {
         Ok(CallResponse::default())
     }
 
+    /// Mints the `coins` set by the address `minter_address`. If the token address doesn't exist return an error.
+    /// Calls the [`Token::mint`] function and update the `self.tokens` set to store the new minted address.
     pub(crate) fn mint(
         &self,
         coins: Coins<C>,
@@ -157,6 +166,9 @@ impl<C: sov_modules_api::Context> Bank<C> {
         Ok(CallResponse::default())
     }
 
+    /// Tries to freeze the token address `token_address`.
+    /// Returns an error if the token address doesn't exist,
+    /// otherwise calls the [`Token::freeze`] function, and update the token set upon success.
     pub(crate) fn freeze(
         &self,
         token_address: C::Address,
@@ -184,6 +196,8 @@ impl<C: sov_modules_api::Context> Bank<C> {
 }
 
 impl<C: sov_modules_api::Context> Bank<C> {
+    /// Transfers the set of `coins` from the address `from` to the address `to`.
+    /// Returns an error if the token address doesn't exist. Otherwise, call the [`Token::transfer`] function.
     pub fn transfer_from(
         &self,
         from: &C::Address,
@@ -208,6 +222,8 @@ impl<C: sov_modules_api::Context> Bank<C> {
     }
 }
 
+/// Creates a new prefix from an already existing prefix `parent_prefix` and a `token_address`
+/// by extending the parent prefix.
 pub(crate) fn prefix_from_address_with_parent<C: sov_modules_api::Context>(
     parent_prefix: &sov_state::Prefix,
     token_address: &C::Address,

diff --git a/module-system/module-implementations/sov-bank/src/genesis.rs b/module-system/module-implementations/sov-bank/src/genesis.rs
@@ -4,9 +4,13 @@ use sov_state::WorkingSet;
 use crate::token::Token;
 use crate::Bank;
 
+/// The address of the deployment node. For now, set to [0; 32]
 pub(crate) const DEPLOYER: [u8; 32] = [0; 32];
 
 impl<C: sov_modules_api::Context> Bank<C> {
+    /// Init an instance of the bank module from the configuration `config`.
+    /// For each token in the `config`, calls the [`Token::create`] function to create
+    /// the token. Upon success, updates the token set if the token address doesn't already exist.
     pub(crate) fn init_module(
         &self,
         config: &<Self as sov_modules_api::Module>::Config,