docs(book): book auto formatting & update cli commands docs (#817)

Author: cernicc

.vscode/extensions.json

@@ -10,5 +10,7 @@
         "ryanluker.vscode-coverage-gutters",
         // direnv, to use tool binaries from `nix` profile and set environment variables automatically
         "mkhl.direnv",
+        // Used for markdown formating
+        "esbenp.prettier-vscode"
     ]
-}
+}

.vscode/settings.default.json

@@ -15,6 +15,9 @@
   // Rust-analyzer doesn't need to build the wasm binary
   "rust-analyzer.cargo.extraEnv": {
     "SKIP_WASM_BUILD": "true"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
   }
   // Recommended when developing benchmarks
   /*

docs/src/architecture/index.md

@@ -22,7 +22,7 @@ We do provide an implementation of the storage provider, you can read more about
 
 ![](../images/architecture/pallets_overview.png)
 
-We've been focusing on implementing the core functionality by developing the market, storage provider, proofs and randomness pallets.
+We've been focusing on implementing the core functionality by developing the market, storage provider, proofs, randomness and faucet pallets.
 
 The market pallet handles all things related to deal payments and slashing,
 being informed by the storage provider when deals haven't been proven and applying slashing in those cases.
@@ -35,11 +35,12 @@ For a deeper dive on the pallets, you can read the [Pallets chapter](./pallets/i
 ## Resources on Parachains
 
 Reading:
-* [Parachains' Protocol Overview](https://wiki.polkadot.network/docs/learn-parachains-protocol)
-* [The Path of a Parachain Block](https://polkadot.com/blog/the-path-of-a-parachain-block)
+
+- [Parachains' Protocol Overview](https://wiki.polkadot.network/docs/learn-parachains-protocol)
+- [The Path of a Parachain Block](https://polkadot.com/blog/the-path-of-a-parachain-block)
 
 Videos:
-* [Introduction to Polkadot, Parachains, and Substrate](https://www.youtube.com/live/gT-9r1bcVHY?si=dmCJyWB5w2NY1bnu&t=1670)
-* [The Path of a Parachain Block - Joe Petrowski](https://www.youtube.com/watch?v=vRsBlVELQEo)
-* [The Path of a Parachain Block on Polkadot and Kusama Network](https://www.youtube.com/watch?v=m0vxqWwFfDs)
 
+- [Introduction to Polkadot, Parachains, and Substrate](https://www.youtube.com/live/gT-9r1bcVHY?si=dmCJyWB5w2NY1bnu&t=1670)
+- [The Path of a Parachain Block - Joe Petrowski](https://www.youtube.com/watch?v=vRsBlVELQEo)
+- [The Path of a Parachain Block on Polkadot and Kusama Network](https://www.youtube.com/watch?v=m0vxqWwFfDs)

docs/src/architecture/pallets/index.md

@@ -4,6 +4,7 @@
 - [`market`](market.md) - A pallet that handles the storage market operations.
 - [`proofs`](proofs.md) - A pallet responsible for verifying [PoRep](../../glossary.md#porep) and [PoSt](../../glossary.md#post).
 - [`randomness`](randomness.md) - A pallet providing randomness source for blocks, mainly used by Proofs.
+- [`faucet`](faucet.md) - A pallet that provides a means to distribute tokens for testing purposes.
 
 ## Overview
 
@@ -51,5 +52,3 @@ Finally, storage providers can then settle deal payments to receive their fair s
 Putting it all together, we get the following:
 
 <img id="figure-overview" src="../../images/overview_flow.svg" alt="The described flow">
-
-

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

@@ -47,14 +47,12 @@ Sealing a sector using Proof-of-Replication (PoRep) is a computation-intensive p
 - **Run a SNARK on the Proof**: Compress the proof using a Succinct Non-interactive Argument of Knowledge (SNARK).
 - **Submit the Compressed Proof:** Submit the result of the compression to the blockchain as certification of the storage commitment.
 
-
 ## Usage
 
 ### Modifying storage provider information
 
 The `Storage Provider Pallet` allows storage providers to modify their information such as changing the peer id, through `change_peer_id` and changing owners, through `change_owner_address`.
 
-
 ## Storage Provider Flow
 
 ### Registration

docs/src/architecture/polka-storage-provider-server.md

@@ -96,7 +96,7 @@ To achieve that, the pipeline is composed of 3 main stages.
 
 ### Add Piece
 
-The Add Piece stage gathers pieces into unsealed sectors, preparing them for the next steps.
+The Add Piece stage gathers pieces into unsealed sectors, preparing them for the next steps. The pipeline uses a configured fill threshold (default 95%) to determine when a sector is ready for sealing, or will seal after a configured delay even if not completely filled. The time-based sealing is important because once a storage deal is published, the storage provider has made a formal commitment to store that data. If the storage provider fails to complete the sealing process and prove storage after this commitment, they risk being slashed (penalized).
 
 While the system can theoretically support multiple sector sizes (2KiB, 8MiB, 512MiB and 1GiB), only the 1GiB sector size is considered safe for production use. Other sector sizes should be considered experimental and are not recommended for production deployments.
 

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

@@ -7,20 +7,19 @@ Quick reminder that Windows is not part of the supported operating systems.
 As such, the following guides <b>have not been tested</b> on Windows.
 </div>
 
-
 We'll be building 5 artifacts:
 
-* `polka-storage-node` — the Polka Storage Polkadot parachain node.
-* `polka-storage-provider-server` — the Polka Storage Storage Provider,
+- `polka-storage-node` — the Polka Storage Polkadot parachain node.
+- `polka-storage-provider-server` — the Polka Storage Storage Provider,
   responsible for accepting deals, storing files and executing storage proofs.
-* `polka-storage-provider-client` — the Polka Storage Storage Provider client,
+- `polka-storage-provider-client` — the Polka Storage Storage Provider client,
   this CLI tool has several utilities to interact with the Storage Provider server,
   such as proposing and publishing deals, as well as some wallet utilities and proof demos.
-* `mater-cli` — the Mater CLI enables you to convert files into CARv2 archives,
+- `mater-cli` — the Mater CLI enables you to convert files into CARv2 archives,
   an essential part of preparing files for submission to the network.
-* `storagext-cli` — the Storagext CLI is a lower-level tool to manually run the Polka Storage extrinsics.
+- `storagext-cli` — the Storagext CLI is a lower-level tool to manually run the Polka Storage extrinsics.
 
 To build these artifacts, we provide two main methods:
 
-* [Building from source](./source.md)
-* [Building with Docker](./docker.md)
+- [Building from source](./source.md)
+- [Building with Docker](./docker.md)

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

@@ -3,11 +3,11 @@
 This guide will outline how to setup your environment to build the Polka Storage parachain,
 we cover how to build the binaries directly on your system or using [Nix](https://nixos.org/download/) to ease the process.
 
-* [Get the code](#get-the-code)
-* [System dependencies](#system-dependencies)
-* [Using Nix](#using-nix)
-  * [Pre-requisites](#pre-requisites)
-* [Building](#building)
+- [Get the code](#get-the-code)
+- [System dependencies](#system-dependencies)
+- [Using Nix](#using-nix)
+  - [Pre-requisites](#pre-requisites)
+- [Building](#building)
 
 ## Get the code
 
@@ -22,9 +22,9 @@ cd polka-storage
 
 To build the binaries directly on your system you will need the following tools:
 
-* Rust 1.81.0 — you can install it using [`rustup`](https://rustup.rs/) and its [guide](https://rust-lang.github.io/rustup/installation/other.html) for help.
-* Other dependencies — keep reading, we'll get to it after the end of this list!
-* `just` (optional) — (after installing Rust) you can use `cargo install just` or check the [official list of packages](https://just.systems/man/en/packages.html).
+- Rust 1.81.0 — you can install it using [`rustup`](https://rustup.rs/) and its [guide](https://rust-lang.github.io/rustup/installation/other.html) for help.
+- Other dependencies — keep reading, we'll get to it after the end of this list!
+- `just` (optional) — (after installing Rust) you can use `cargo install just` or check the [official list of packages](https://just.systems/man/en/packages.html).
 
 The dependencies mentioned are for Linux distros using the `apt` family of package managers.
 Different systems may use different package managers, as such, they may require you to find the equivalent package.
@@ -40,7 +40,7 @@ $ sudo apt install -y libhwloc-dev \
     clang \
     build-essential \
     git \
-    libssl-dev \ 
+    libssl-dev \
     curl
 ```
 
@@ -56,15 +56,15 @@ Details can be found <a href="https://docs.nvidia.com/cuda/wsl-user-guide/index.
 </div>
 
 Requirements:
-* GCC 13
-* NVIDIA GPU
-* [Cuda drivers & toolkit (nvcc)](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#overview)
 
+- GCC 13
+- NVIDIA GPU
+- [Cuda drivers & toolkit (nvcc)](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#overview)
 
 <div class="warning">
 
 Not all of the binaries can be built from the polka-storage repository!
-We depend on the <a href="https://github.com/paritytech/zombienet/releases/tag/v1.3.116">zombienet</a> and <a href="https://github.com/paritytech/polkadot-sdk/releases/tag/polkadot-stable2409-2">polkadot, polkadot-prepare-worker, polkadot-execute-worker</a> binaries which need to be downloaded regardless (if not using <a href="#using-nix">Nix</a>).
+We depend on the <a href="https://github.com/paritytech/zombienet/releases/tag/v1.3.116">zombienet</a> and <a href="https://github.com/paritytech/polkadot-sdk/releases/tag/polkadot-stable2412">polkadot, polkadot-prepare-worker, polkadot-execute-worker</a> binaries which need to be downloaded regardless (if not using <a href="#using-nix">Nix</a>).
 
 </div>
 
@@ -122,7 +122,6 @@ cargo build --release -p polka-storage-provider-server --no-default-features --f
 cargo build --release -p polka-storage-provider-client --no-default-features --features cuda
 ```
 
-
 For more information on what each binary does, refer to [Building](./index.md).
 
 ### Just recipes
@@ -151,10 +150,11 @@ $ target/release/<BINARY-NAME>
 ```
 
 Where `<BINARY-NAME>` is one of:
-* `polka-storage-node`
-* `polka-storage-provider-server`
-* `polka-storage-provider-client`
-* `mater-cli`
-* `storagext-cli`
+
+- `polka-storage-node`
+- `polka-storage-provider-server`
+- `polka-storage-provider-client`
+- `mater-cli`
+- `storagext-cli`
 
 > Additionally, you can move them to a folder under your `$PATH` and run them as you would with any other binary.

docs/src/getting-started/demo-file-store.md

@@ -5,8 +5,8 @@ Before reading this guide, please follow the <a href="./local-testnet.md">local
 You should have a working testnet and a Storage Provider running!
 </div>
 
-
 ## Storage Client
+
 <img class="right" src="../images/polkadot.svg" alt="The Polkadot logo" style="height: 100px; padding: 4px 8px 4px;">
 
 Alice is a [Storage User](../glossary.md#storage-user) and wants to store an image of her lovely Polkadot logo [`polkadot.svg`](../images/polkadot.svg) in the Polka Storage [parachain](../glossary.md#parachain).
@@ -35,7 +35,6 @@ $ polka-storage-provider-client proofs commp polkadot.car
 Afterwards, it's time to propose a deal, currently — i.e. while the network isn't live —
 any deals will be accepted by Charlie (the Storage Provider).
 
-
 Alice fills out the deal form according to a JSON template (`polka-logo-deal.json`):
 
 ```json
@@ -53,19 +52,18 @@ Alice fills out the deal form according to a JSON template (`polka-logo-deal.jso
 }
 ```
 
-* `piece_cid` — is the `cid` field from the previous step, where she calculated the piece commitment. It uniquely identifies the piece.
-* `piece_size` — is the `size` field from the previous step, where she calculated the piece commitment. It is the size of the processed piece, not the original file!
-* `client` — is the client's (i.e. the reader's) public key, encoded in bs58 format.
+- `piece_cid` — is the `cid` field from the previous step, where she calculated the piece commitment. It uniquely identifies the piece.
+- `piece_size` — is the `size` field from the previous step, where she calculated the piece commitment. It is the size of the processed piece, not the original file!
+- `client` — is the client's (i.e. the reader's) public key, encoded in bs58 format.
   For more information on how to generate your own keypair, read the [Polka Storage Provider CLI/`client`/`wallet`](../storage-provider-cli/client/wallet.md).
-* `provider` — is the storage provider's public key, encoded in bs58 format.
+- `provider` — is the storage provider's public key, encoded in bs58 format.
   If you don't know your storage provider's public key, you can query it using `polka-storage-provider-client`'s `info` command.
-* `label` — is an arbitrary string to be associated with the deal.
-* `start_block` — is the deal's start block, it MUST be positive and lower than `end_block`.
-* `end_block` — is the deal's end block, it must be positive and larger than `start_block`.
-* `storage_price_per_block` — the storage price over the duration of a single block — e.g. if your deal is 20 blocks long, it will cost `20 * storage_price_per_block` in total.
-* `provider_collateral` — the price to pay *by the storage provider* if they fail to uphold the deal.
-* `state` — the deal state, only `Published` is accepted.
-
+- `label` — is an arbitrary string to be associated with the deal.
+- `start_block` — is the deal's start block, it MUST be positive and lower than `end_block`.
+- `end_block` — is the deal's end block, it must be positive and larger than `start_block`.
+- `storage_price_per_block` — the storage price over the duration of a single block — e.g. if your deal is 20 blocks long, it will cost `20 * storage_price_per_block` in total.
+- `provider_collateral` — the price to pay _by the storage provider_ if they fail to uphold the deal.
+- `state` — the deal state, only `Published` is accepted.
 
 <div class="warning">
 
@@ -137,7 +135,8 @@ $ polka-storage-provider-client sign-deal --sr25519-key "//Alice" @polka-logo-de
 }
 ```
 
-> Hint: you can write the following command to *just* get the file:
+> Hint: you can write the following command to _just_ get the file:
+>
 > ```
 > polka-storage-provider-client sign-deal --sr25519-key "//Alice" @polka-logo-deal.json > signed-logo-deal.json
 > ```
@@ -159,8 +158,8 @@ On Alice's side, that's it!
 
 ## Additional Notes
 
-* As other parts of this project, file retrieval is actively being worked on! 🚧
-* Files stored in storage providers are public, as such, we suggest you encrypt your files.
+- As other parts of this project, file retrieval is actively being worked on! 🚧
+- Files stored in storage providers are public, as such, we suggest you encrypt your files.
   While file encryption is a broad enough topic, if you not sure about which tools to use,
   we suggest you keep it simple by compressing your file in a format such as [7zip](https://www.7-zip.org/) and using its encryption features.
   If 7zip doesn't cut it, you may want to take a look into [age](https://github.com/FiloSottile/age) or [VeraCrypt](https://www.veracrypt.fr/code/VeraCrypt/).

docs/src/getting-started/index.md

@@ -20,5 +20,3 @@ Before proceeding with the setup, please ensure the host system meets the follow
 - [_Local Testnet - Polka Storage Parachain_](local-testnet/index.md) — Covers how to setup a local testnet for the Polka Storage parachain, using Zombienet.
 - [_Launching a Storage Provider_](storage-provider.md) - Covers how to setup a Storage Provider.
 - [_Storing a file_](demo-file-store.md) — Covers how to store a file by the Storage Client.
-
-

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

@@ -10,6 +10,7 @@ Please make sure to follow the instructions on how to generate a new account if
 You can read more about creating a Polkadot account using the extension in the following [link](https://support.polkadot.network/support/solutions/articles/65000098878-how-to-create-a-dot-account#How-to-create-an-account-with-the-Polkadot-extension)
 
 Or you can watch the following video:
+
 <iframe
     style="display:block; margin-left:auto; margin-right:auto"
     width="560"
@@ -47,11 +48,11 @@ Make sure to run the local testnet, you can find how to do so in the [local test
 > If you have changed the `ws_port` value in the zombienet configuration — `local-testnet.toml`,
 > this URL is different and you should change the port accordingly.
 
-Under the developer tab, navigate to *Sudo*.
+Under the developer tab, navigate to _Sudo_.
 
 ![sudo selection](../../images/transfer-funds/developer-sudo.png)
 
-Once you are in *Sudo* you should select `balances` from the submit dropdown.
+Once you are in _Sudo_ you should select `balances` from the submit dropdown.
 
 ![balance selection](../../images/transfer-funds/select-balance.png)
 

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

@@ -265,6 +265,7 @@ This link will automatically connect to Charlie's node running on a local machin
 ## Checking the logs
 
 At the end of the `zombienet` output you should see a table like so:
+
 ```
 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                                                         Node Information                                                          │
@@ -288,6 +289,7 @@ We strongly recommend you check the logs for the collator (in this case Charlie)
 
 > If the **Log Cmd** is shortened with `...`, try to search for the folder using the zombienet namespace, available at the top of the table.
 > For example:
+>
 > ```bash
 > $ ls /tmp | grep zombie-bcb786e1748ff0a6becd28289e1f70b9
 > ```
@@ -306,20 +308,23 @@ $ grep "<LOG_LEVEL>.*runtime::<EXTRINSIC_PALLET>" charlie.log
 ```
 
 Where `LOG_LEVEL` is one of:
-* `DEBUG`
-* `INFO`
-* `WARN`
-* `ERROR`
+
+- `DEBUG`
+- `INFO`
+- `WARN`
+- `ERROR`
 
 And the extrinsic pallet, is one of:
-* `storage_provider`
-* `market`
-* `proofs`
+
+- `storage_provider`
+- `market`
+- `proofs`
 
 > **Tip:** if you are running into the `AllProposalsInvalid` error,
 > try searching for `insane deal` in the logs, you should find the cause faster!
 >
 > For example:
+>
 > ```bash
 > $ grep "insane deal" -B 1 charlie.log
 > 2024-11-14 13:24:24.019 ERROR tokio-runtime-worker runtime::market: [Parachain] deal duration too short: 100 < 288000