docs: Update pallet docs after feedback

docs/src/architecture/pallets/proofs.md

@@ -13,17 +13,16 @@
 ## Overview
 
 The `Proofs Pallet` handles all the logic related to verifying [PoRep](../../glossary.md#porep) and [PoSt](../../glossary.md#post) proofs on-chain.
-It's called by [`Storage Provider Pallet`](./storage-provider.md) when verifying proofs during the extrinsics: [`prove_commit_sectors`](./storage-provider.md#prove_commit_sectors)
+It's called by [`Storage Provider Pallet`](./storage-provider.md) when verifying proofs during the extrinsics [`prove_commit_sectors`](./storage-provider.md#prove_commit_sectors)
 and [`submit_windowed_post`](./storage-provider.md#submit_windowed_post). The Pallet **DOES NOT** expose any extrinsic for proofs verification, it only implements a trait that can be [coupled to other pallets](https://education.web3.foundation/docs/Substrate/section8/pallet-coupling).
 
-To verify the proofs properly it needs to have the verifying keys parameters set for the sector size via [`set_porep_verifying_key`](#set_porep_verifying_key) and [`set_post_verifying_key](#set_post_verifying_key).
-
+To verify the proofs properly it needs to have the verifying keys parameters set for the sector size via [`set_porep_verifying_key`](#set_porep_verifying_key) and [`set_post_verifying_key`](#set_post_verifying_key).
 
 ## Usage
 
-This pallet can only be directly used via a trait `primitives_proofs::ProofVerification`. However, for the trait to work and not fail with `Error::MisingPoRepVerifyingKey`/`Error::MissingPoStVerifingKey`, first the verifying keys need to be set via extrinsics `set_porep_verifying_key`/`set_post_verifying_key`.
+This pallet can only be directly used via the trait `primitives_proofs::ProofVerification`. However, for the trait to work and not fail with `Error::MisingPoRepVerifyingKey`/`Error::MissingPoStVerifingKey`, the verifying keys need to be set via extrinsics `set_porep_verifying_key`/`set_post_verifying_key`.
 
-Ideally, users shouldn't worry about it, as it will be set by the governance during a trusted setup procedure and then Storage Providers will download proof generation parameters from somewhere. However, in the MVP phase, those keys need to be set with the extrinsics after starting a testnet.
+Ideally, users shouldn't worry about it, as it will be set by the governance during a trusted setup procedure and then Storage Providers will download the proof generation parameters. However, in the MVP phase, those keys need to be set with the extrinsics after starting a testnet.
 
 Verifying Keys are set for a Sector Size once and then shared across all proof verifications.
 Currently, the network only supports 2KiB sector sizes, so parameters need to be generated and set for it.
@@ -32,7 +31,7 @@ Currently, the network only supports 2KiB sector sizes, so parameters need to be
 
 ### `set_porep_verifying_key`
 
-Verifying Key is a set of shared parameters used for zk-SNARK proof verification. It can be generated via [`polka-storage-provider-client proofs porep-params`](../../storage-provider-cli/client/proofs.md#porep-params) command. The verifying key used in the verification must match proving parameters used in the proof generation.
+Verifying Key is a set of shared parameters used for zk-SNARK proof verification. It can be generated via [`polka-storage-provider-client proofs porep-params`](../../storage-provider-cli/client/proofs.md#porep-params) command. The verifying key used in the verification must match the proving parameters used in the proof generation.
 
 The extrinsic sets the verifying key received in the SCALE-encoded format and then uses it for all the subsequent verification.
 Verifying Key is used to verify every PoRep proof across the network.
@@ -43,7 +42,7 @@ Verifying Key is used to verify every PoRep proof across the network.
 
 #### <a class="header" id="set_porep_verifying_key.example" href="#set_porep_verifying_key.example">Example</a>
 
-Setting a verifying key from an [^account] `//Alice` where proof is stored in `./2KiB.porep.vk.scale` file.
+Setting a verifying key from the [^account] `//Alice` account where proof is stored in the `./2KiB.porep.vk.scale` file.
 
 ```bash
 storagext-cli --sr25519-key "//Alice" proofs set-porep-verifying-key 2KiB.vk.scale
@@ -64,7 +63,7 @@ Verifying Key is used to verify every PoSt proof across the network.
 
 #### <a class="header" id="set_post_verifying_key.example" href="#set_post_verifying_key.example">Example</a>
 
-Setting a verifying key from an [^account] `//Alice` where proof is stored in `./2KiB.post.vk.scale` file.
+Setting a verifying key from the [^account] `//Alice` account where proof is stored in the `./2KiB.post.vk.scale` file.
 
 ```bash
 storagext-cli --sr25519-key "//Alice" proofs set-post-verifying-key 2KiB.vk.scale

docs/src/architecture/pallets/randomness.md

@@ -2,24 +2,26 @@
 
 ## Table of Contents
 
-- [Overview](#overview)
-- [Usage](#usage)
-- [Extrinsics](#extrinsics)
-- [Events](#events)
-- [Errors](#errors)
-- [Constants](#constants)
+- [Randomness Pallet](#randomness-pallet)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Usage](#usage)
+  - [Extrinsics](#extrinsics)
+  - [Events](#events)
+  - [Errors](#errors)
+  - [Constants](#constants)
 
 ## Overview
 
-The randomness pallet saves a random seed for each block when its finalized and allows to get this randomness later.
-There is a limitation - the randomness is available only after 81st block of the chain, due to randomness predictability earlier.
-Currently, the seeds are used for sealing pipeline's pre-commit and prove commit, so for generating a replica and proving a sector.
+The randomness pallet saves a random seed for each block when it's finalized and allows retrieval of this randomness at a later time.
+There is a limitation - the randomness is available only after the 81st block of the chain, due to randomness predictability earlier.
+Currently, the seeds are used for the sealing pipeline's pre-commit and prove commit, in other words generating a replica and proving a sector.
 
 ## Usage
 
-This pallet exposes the interface to get randomness on-chain for a certain block via a trait `primitives_proofs::Randomness`
+This pallet exposes the interface to get randomness on-chain for a certain block via the trait `primitives_proofs::Randomness`
 or chain state query `pallet_randomness:SeedsMap`.
-Note that, you can only get a randomness for a `current_block - 1` and dependent on the configuration, the old randomness seed are being removed.
+Note that, you can only get a randomness for the `current_block - 1` and depending on the configuration, the old randomness seed will be removed after the associated block has passed.
 
 ## Extrinsics
 

docs/src/architecture/pallets/storage-provider.md

@@ -21,7 +21,7 @@
 
 The `Storage Provider Pallet` handles the creation of storage providers and facilitates storage providers and clients in creating storage deals.
 Storage providers must provide the [Proof of Space-time (PoSt)](../../glossary.md#post) and the [Proof of Replication (PoRep)](../../glossary.md#porep)
-to the `Storage Provider Pallet` to prevent the pallet from imposing penalties on storage providers through [slashing](#storage-fault-slashing).
+to the `Storage Provider Pallet` to prevent the pallet from imposing penalties on storage providers through [slashing](../../glossary.md#slashing).
 
 ## Usage
 
@@ -38,8 +38,6 @@ the storage provider can declare sectors as faulty or recovered[^recovered].
 
 [^recovered]: Recovered sectors still require being proven before they can become fully active again.
 
-Substrate pallet hooks execute actions when certain conditions are met.
-
 Substrate pallet hooks execute some actions when certain conditions are met.
 We use these hooks — when a block finalizes — to check if storage providers are up to date with their proofs.
 If a storage provider fails to submit proof on time, the Storage Provider pallet will signal the Market pallet to penalize the storage provider.
@@ -91,7 +89,7 @@ Sectors are not valid after pre-commit. The sectors need to be proven first.
 
 #### <a class="header" id="pre_commit_sectors.example" href="#pre_commit_sectors.example">Example</a>
 
-Storage provider `//Alice` pre-committing[^pre_commit_sectors] a sector number 1, with a single deal ID 0.
+Storage provider `//Alice` pre-committing[^pre-committing] a sector number 1, with a single deal ID 0.
 
 ```bash
 storagext-cli --sr25519-key "//Alice" storage-provider pre-commit @pre-commit-sector.json
@@ -110,7 +108,7 @@ Where `pre-commit-sector.json` is a file with contents similar to:
 }
 ```
 
-[^pre_commit_sectors]: Read more about the `pre-commit` command in [_Storagext CLI/Subcommand `storage-provider`/`pre-commit`_](../../storagext-cli/storage-provider.md#pre-commit)
+[^pre-committing]: Read more about the `pre-commit` command in [_Storagext CLI/Subcommand `storage-provider`/`pre-commit`_](../../storagext-cli/storage-provider.md#pre-commit)
 
 ### `prove_commit_sectors`
 
@@ -275,8 +273,8 @@ Where the termination declarations contain:
 
 | Name        | Description                                                                | Type                     |
 | ----------- | -------------------------------------------------------------------------- | ------------------------ |
-| `deadline`  | The deadline the termination is targeting                                  | Positive integer.        |
-| `partition` | Partition index within the deadline containing the sector to be terminated | Positive integer.        |
+| `deadline`  | The deadline the termination is targeting                                  | Positive integer        |
+| `partition` | Partition index within the deadline containing the sector to be terminated | Positive integer        |
 | `sectors`   | Sectors in the partition being terminated                                  | Set of positive integers |
 
 #### <a class="header" id="terminate_sectors.example" href="#terminate_sectors.example">Example</a>
@@ -405,7 +403,7 @@ The Storage Provider Pallet actions can fail with the following errors:
   - `DeadlineErrorSectorsNotFound` - Emitted when trying to use sectors which haven't been prove committed yet.
   - `DeadlineErrorSectorsNotFaulty` - Emitted when trying to recover non-faulty sectors.
   - `DeadlineErrorCouldNotAssignSectorsToDeadlines` - Emitted when assigning sectors to deadlines fails.
-  - `DeadlineErrorFailedToUpdateFaultExpiration` - Emitted when trying to update fault expirations fails
+  - `DeadlineErrorFailedToUpdateFaultExpiration` - Emitted when trying to update fault expirations fails.
   - `StorageProviderErrorMaxPreCommittedSectorExceeded` - Happens when an SP tries to pre-commit more sectors than SECTOR_MAX.
   - `StorageProviderErrorSectorNotFound` - Happens when trying to access a sector that does not exist.
   - `StorageProviderErrorSectorNumberInUse` - Happens when a sector number is already in use.