docs: address 2nd review (#580)

docs/src/architecture/pallets/index.md

@@ -28,7 +28,7 @@ After publishing, the funds allocated for the deal will be moved from `free` to
 <img src="../../images/market/publish_storage_deals.svg" alt="Publishing storage deals">
 
 At this point, the remaining responsibility is shifted to the storage provider, which needs to activate the deal.
-First, the storage provider needs to call `get_randomness` from the[Randomness Pallet](./randomness.md) in order to create a replica and
+First, the storage provider needs to call `get_randomness` from the [Randomness Pallet](./randomness.md) in order to create a replica and
 [pre-commit](./storage-provider.md#pre_commit_sectors) the deal's sectors.
 The sealing and pre-committing takes some time, after that the storage provider needs to fetch yet another randomness seed to create a proof.
 Subsequently, they [prove](./storage-provider.md#prove_commit_sectors) they stored the sectors by calling [`prove_commit_sectors`](./storage-provider.md#prove_commit_sectors) extrinsics.

docs/src/architecture/pallets/market.md

@@ -197,7 +197,7 @@ The Market Pallet emits the following events:
 - `DealsSettled` - Published after the `settle_deal_payments` extrinsic is called. Indicates which deals were successfully and unsuccessfully settled.
   - `successful` - List of deal IDs that were settled
   - `unsuccessful` - List of deal IDs with the corresponding errors
-- `DealSlashed` - Is emitted when some deal expired
+- `DealSlashed` - Is emitted when some deal expired.
   - `deal_id` - Deal ID that was slashed
 - `DealTerminated` - A deal was voluntarily or involuntarily terminated.
   - `deal_id` - Terminated deal ID

docs/src/getting-started/building/source.md

@@ -74,6 +74,7 @@ for more information refer to the official Nix guide — https://nix.dev/manual/
 After all this setup, it is time to start building the binaries, which you can do manually using the following command:
 
 <div class="warning">
+
 When building `polka-storage-node` you should add `--features polka-storage-runtime/testnet` which enables the testnet configuration; all the code in the repo is currently targeting this feature, not including it may lead to unexpected behavior.
 
 When building `storagext-cli` you may want to add `--features storagext/insecure_url` which enables using non-TLS HTTP and WebSockets.
@@ -91,7 +92,6 @@ Where `<BINARY-NAME>` is one of:
 - `storagext-cli`
 - `mater-cli`
 
-Additionally, if you're building `polka-storage-node` or `storagext-cli` there are features that you may want to enable:
 
 For more information on what each binary does, refer to [Building](./index.md).
 

docs/src/getting-started/local-testnet/index.md

@@ -8,7 +8,7 @@ Charlie will be our contact point to the parachain network.
 
 ## Native Binaries
 
-The binaries for the latest releases are available to download and can be ran without any additional dependencies.
+The binaries for the latest releases are available to download and can be run without any additional dependencies.
 We support `Linux x86_64` and `MacOS ARM x64`. The commands below will download:
 
 - [Relay Chain](https://github.com/paritytech/polkadot-sdk/releases) binaries (`polkadot`, `polkadot-prepare-worker`, `polkadot-execute-worker`),

docs/src/getting-started/storage-provider.md

@@ -78,7 +78,15 @@ polka-storage-provider-server \
   --X-key <KEY>
 ```
 
-Where `--X-key <KEY>` matches the key type you used to register yourself with the network, in the previous step.
+Where `--X-key <KEY>` matches the key type you used to register yourself with the network, in the previous step. For example:
+```bash
+polka-storage-provider-server \
+  --seal-proof 2KiB \
+  --post-proof 2KiB \
+  --porep-parameters "2KiB.porep.params" \
+  --sr25519-key "//Charlie"
+```
+
 Note that currently, `--seal-proof` and `--post-proof` only support `2KiB`.
 
 `<POREP-PARAMS>` is the resulting `*.porep.params` file from the [first steps](#generating-the-porep-parameters),

docs/src/storage-provider-cli/client/index.md

@@ -13,7 +13,7 @@ More information available on the [`wallet`](./wallet.md) page.
 The `info` command retrieves information about the storage provider it connects to.
 
 ```bash
-$ polka-storage-provider-client info --rpc-server-address "http://127.0.0.1:8000"
+$ polka-storage-provider-client info --rpc-server-url "http://127.0.0.1:8000"
 {
   "start_time": "2024-11-06T11:29:06.058967136Z",
   "address": "5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y",

docs/src/storage-provider-cli/client/proofs.md

@@ -1,19 +1,15 @@
 # `proofs`
 
-<!-- TODO: add parameters -->
-
 The following subcommands are contained under `proofs`.
 
+> These are advanced commands and only useful for demo purposes.
+> This functionality is covered in the server by the [pipeline](../../architecture/polka-storage-provider-server.md#sealing-pipeline).
+
 | Name                         | Description                                                                                                                                 |
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `calculate-piece-commitment` | Calculate a piece commitment for the provided data stored at the a given path                                                               |
 | `porep-params`               | Generates PoRep verifying key and proving parameters for zk-SNARK workflows (prove commit)                                                  |
-| `porep`                      | Generates PoRep for a piece file. Takes a piece file (in a CARv2 archive, unpadded), puts it into a sector (temp file), seals and proves it |
 | `post-params`                | Generates PoSt verifying key and proving parameters for zk-SNARK workflows (submit windowed PoSt)                                           |
+| `porep`                      | Generates PoRep for a piece file. Takes a piece file (in a CARv2 archive, unpadded), puts it into a sector (temp file), seals and proves it |
 | `post`                       | Creates a PoSt for a single sector                                                                                                          |
 
-
-# `porep-params`
-<!-- TODO -->
-
-# `post-params`

docs/src/storage-provider-cli/client/wallet.md

@@ -30,7 +30,7 @@ Keys shown on this page are, by default, not secure! Do not use them in producti
 Generate a new random key to interact with the Polka Storage parachain:
 
 ```bash
-> polka-storage-provider wallet generate
+> polka-storage-provider-client wallet generate
 Secret phrase:       offer payment boost boy manage car asset lock cousin mountain vehicle setup
   Network ID:        substrate
   Secret seed:       0xfe36ee692552b0ce54de06ce4f5cc152fe2fa808cb40f58c81168bc1237208bb
@@ -43,7 +43,7 @@ Secret phrase:       offer payment boost boy manage car asset lock cousin mounta
 The password may be added interactively, using `--password-interactive` flag:
 
 ```bash
-> polka-storage-provider wallet generate --password-interactive
+> polka-storage-provider-client wallet generate --password-interactive
 Key password: <top secret hidden password>
 Secret phrase:       comfort distance rack number assist nasty young universe lamp advice neglect ladder
   Network ID:        substrate
@@ -57,7 +57,7 @@ Secret phrase:       comfort distance rack number assist nasty young universe la
 Or it can be passed directly, beforehand:
 
 ```bash
-> polka-storage-provider wallet generate --password <top secret password>
+> polka-storage-provider-client wallet generate --password <top secret password>
 Secret phrase:       cactus art crime burden hope also thought asset lake only cheese obtain
   Network ID:        substrate
   Secret seed:       0xb69c2d238fa7641f0d69911ca8f107f1b97a51cfc71e8a06e0ec9c7329d69ff7

docs/src/storage-provider-cli/server.md

@@ -58,12 +58,12 @@ Defaults to a pseudo-random temporary directory — `/tmp/<random string>/deals_
 
 ### `--storage-directory`
 
-The piece storage directory, where pieces will be kept stored in.
+The piece storage directory, where pieces will be kept.
 
 It takes in a valid folder path, if the directory does not exist, it will be created along with all intermediate paths.
 Defaults to a pseudo-random temporary directory — `/tmp/<random string>/...`.
 
-Storage directories like the pieces, unsealed and sealed directories will be created under it.
+Storage directories for the pieces, unsealed and sealed sectors will be created under it.
 
 ### `--seal-proof`
 

docs/src/storagext-cli/index.md

@@ -48,7 +48,7 @@ The `--format` global flag changes how extrinsic output is done, if the output i
 we **do not** make any guarantees about the output format, as such, you should not rely on it for scripts!
 
 If the output is set to `--json` all standard output from the CLI will be formatted as JSON, however,
-as it **currently** stands, we do not guarantee a stable interface — though we will make an effort to keep changes to a minimum, and document them.
+as it **currently** stands, we do not guarantee a stable interface — though we will make an effort to keep changes to a minimum and document them.
 
 [^keys]: Read more about how cryptographic keys are used in Polkadot — <https://wiki.polkadot.network/docs/learn-cryptography>.
 [^optional_keys]: If a key is passed to the CLI, but the operation called does not require a key, **the key will not be used**.

docs/src/storagext-cli/market.md

@@ -44,7 +44,7 @@ An attempt to create a Market account with less than <code>1000000000</code>, wi
 The `withdraw-balance` withdraws balance from the market account of the extrinsic signer.
 Like [`add-balance`](#add-balance), `withdraw-balance` takes a single `AMOUNT` argument;
 note that _only `free` balance can be withdrawn_.
-Likewise, withdrawal of a balance amount lesser than or equal to the `free` amount and greater than 0 (\\({free} \ge {amount} \gt 0\\)).
+Likewise, withdrawal of a balance amount must be less than or equal to the `free` amount and greater than 0 (\\({free} \ge {amount} \gt 0\\)).
 
 ### Parameters
 
@@ -74,7 +74,7 @@ We know this is <i>not secure</i> and <i>unrealistic</i> in a production sce
 
 ### Parameters
 
-The client keypair can be passed using `--client-<key kind>`, where `<key kind>` is one of the [three supported keys](index.md#getting-started), like the global keys, one is required.
+> The client keypair can be passed using `--client-<key kind>`, where `<key kind>` is one of the [three supported keys](index.md#getting-started), like the global keys, one is required.
 
 | Name                   | Description               | Type                                                                                                                        |
 | ---------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |

docs/src/storagext-cli/randomness.md

@@ -11,7 +11,7 @@ This chapter covers the provided commands and how to use them.
 
 ## `get`
 
-The `get` fetches random value for a specific block height. The returned value is hex encoded.
+The `get` command fetches random value for a specific block height. The returned value is hex encoded.
 
 ### Parameters
 

docs/src/storagext-cli/storage-provider.md

@@ -70,7 +70,7 @@ Where `pre-commit-sector.json` is a file with contents similar to:
     "expiration": 100,
     "unsealed_cid": "bafkreibme22gw2h7y2h7tg2fhqotaqjucnbc24deqo72b6mkl2egezxhvy",
     "seal_proof": "StackedDRG2KiBV1P1",
-    "seal_randomness_height": 85,
+    "seal_randomness_height": 85
   }
 ]
 ```
@@ -144,7 +144,7 @@ The `PROOF` JSON object has the following structure:
 
 ### <a class="header" id="submit-windowed-post.example" href="#submit-windowed-post.example">Example</a>
 
-Proves a partition in a specific deadline.
+Proves partitions in a specific deadline.
 
 ```bash
 storagext-cli --sr25519-key <key> storage-provider submit-windowed-post \
@@ -156,7 +156,7 @@ Where `window-proof.json` is a file with contents similar to:
 ```json
 {
   "deadline": 0,
-  "partition": 0,
+  "partitions": [0],
   "proof": {
     "post_proof": "2KiB",
     "proof_bytes": "07482439"