+Before reading this guide,
+please ensure you've followed the local testnet guide and that a working testnet is running!
+
+
+A high-level overview with diagrams of the process described below can be found in Pallets section.
+
+## 1. Publishing a deal
+
+Charlie heard he could provide storage to people worldwide and earn some tokens,
+so he decided to register as a [Storage Provider](../glossary.md).
+
+```bash
+$ storagext-cli --sr25519-key "//Charlie" storage-provider register Charlie
+[0xd14d…4b6a] Storage Provider Registered: { owner: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, info: Storage Provider Info: { peer_id: 3ZAB4sc5BS, window_post_proof_type: StackedDRGWindow2KiBV1P1, sector_size: _2KiB, window_post_partition_sectors: 2 }, proving_period_start: 21 }
+```
+
+
+
+Alice is a [Storage User](../glossary.md#storage-user) and wants to store an image of her lovely Husky (`husky.jpg`) in the Polka Storage [parachain](../glossary.md#parachain).
+
+Alice knows[^no-cid] that she needs to get a [CID](https://github.com/multiformats/cid) of the image,
+so she [uploaded it to the CAR server](../storage-provider-cli/storage.md#upload-a-file)
+and received the CID: `bafybeihxgc67fwhdoxo2klvmsetswdmwwz3brpwwl76qizbsl6ypro6vxq`.
+
+Alice heard somewhere[^no-sp-discovery] in the hallways of her favourite gym that Charlie is a Storage Provider.
+She calls him (off-chain), and they negotiate a deal:
+
+`husky-deal.json`
+
+```json
+[
+ {
+ "piece_cid": "bafybeihxgc67fwhdoxo2klvmsetswdmwwz3brpwwl76qizbsl6ypro6vxq",
+ "piece_size": 1278,
+ "client": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
+ "provider": "5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y",
+ "label": "My lovely Husky (husky.jpg)",
+ "start_block": 25,
+ "end_block": 50,
+ "storage_price_per_block": 1000000000,
+ "provider_collateral": 12500000000,
+ "state": "Published"
+ }
+]
+```
+
+| Name | Value | Description |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `piece_cid` | `bafybeihxgc67fwhdoxo2klvmsetswdmwwz3brpwwl76qizbsl6ypro6vxq` | The submitted file's CID |
+| `piece_size` | `1278` | The submitted file's size |
+| `client` | [`//Alice`](https://docs.substrate.io/reference/glossary/#dev-phrase) or `5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY` | The client's address |
+| `provider` | [`//Charlie`](https://docs.substrate.io/reference/glossary/#dev-phrase) or `5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y` | The providers's address |
+| `start_block` | `25` | When the deal should start |
+| `end_block` | `50` | When the deal should end |
+| `storage_price_per_block` | `1_000_000_000` | In [Plancks](../glossary.md#planck), the storage price per block (12 sec) |
+| `provider_collateral` | `12_500_000_000` | In [Plancks](../glossary.md#planck), the price paid by the storage provider if they fail to uphold their end of the deal |
+
+After the negotiation, they need to [add funds to the Pallet](../pallets/market.md#add_balance) and then [publish their intent](../pallets/market.md#publish_storage_deals) so it can be checked by the parachain.
+So here they go:
+
+```bash
+# Adding balance to Alice's account
+$ storagext-cli --sr25519-key "//Alice" market add-balance 25000000000
+[0xe0bd…06f9] Balance Added: { account: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY, amount: 25000000000 }
+# Adding balance to Charlie's account
+$ storagext-cli --sr25519-key "//Charlie" market add-balance 12500000000
+[0x25aa…edd3] Balance Added: { account: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, amount: 12500000000 }
+# Publishing their deal
+$ storagext-cli --sr25519-key "//Charlie" market publish-storage-deals --client-sr25519-key "//Alice" "@husky-deal.json"
+[0xd50b…dee6] Deal Published: { deal_id: 0, provider_account: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, client_account: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY }
+```
+
+[^no-cid]: We have not provided a standalone command to generate CID out of the file. The CAR server is a temporary showcase component.
+[^no-sp-discovery]: We have not yet implemented Storage Provider Discovery protocol.
+
+## 2. Committing a deal
+
+After the deals have been published, the rest is up to Charlie.
+If Charlie does not behave appropriately, [pre-commit](../pallets/storage-provider.md#pre_commit_sector) and [prove](../pallets/storage-provider.md#prove_commit_sector) the deal by block 25 (`start_block`),
+he will be slashed, and all his funds [(`provider_collateral`)](../glossary.md#collateral) will be gone.[^slash]
+So he should do his part!
+
+`pre-commit-husky.json`
+
+```json
+{
+ "sector_number": 1,
+ "sealed_cid": "bafk2bzaceajreoxfdcpdvitpvxm7vkpvcimlob5ejebqgqidjkz4qoug4q6zu",
+ "deal_ids": [0],
+ "expiration": 75,
+ "unsealed_cid": "bafk2bzaceajreoxfdcpdvitpvxm7vkpvcimlob5ejebqgqidjkz4qoug4q6zu",
+ "seal_proof": "StackedDRG2KiBV1P1"
+}
+```
+
+| Name | Value | Description |
+| -------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [`sector_number`](../glossary.md#sector) | 1 | The place where `husky.jpg` will be stored. Charlie decided it'll be on his 1st sector. |
+| `deal_ids` | `[0]` | A sector can contain multiple deals, but it only contains the first one ever created (id: 0). |
+| `expiration` | `75` | The 75th block is 5 minutes after the `end_block`, so the sector expires only after the deal has been terminated. |
+| [`sealed_cid`](../glossary.md#commitment-of-replication), [`unsealed_cid`](../glossary.md#commitment-of-data), | multiple | Currently, placeholder values (any CID) since the proof mechanism is a work-in-progress. |
+| `seal_proof` | `StackedDRG2KiBV1P1` | Currently, we only accept sector sizes of 2KiB, so this is the only value possible. |
+
+`prove-commit-husky.json`
+```json
+{
+ "sector_number": 1,
+ "proof": "1230deadbeef"
+}
+```
+
+- `proof`: hex string of bytes of the proof, it's WIP, so any non-zero value works.
+
+```bash
+$ storagext-cli --sr25519-key "//Charlie" storage-provider pre-commit "@pre-commit-husky.json"
+[0xf2ad…dc3d] Sector Pre-Committed: { owner: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, sector_number: Sector Pre-Commit Info: { sector_number: 1, expiration: 75, seal_proof: RegisteredSealProof::StackedDRG2KiBV1P1, unsealed_cid: bafk2bzaceajreoxfdcpdvitpvxm7vkpvcimlob5ejebqgqidjkz4qoug4q6zu, sealed_cid: bafk2bzaceajreoxfdcpdvitpvxm7vkpvcimlob5ejebqgqidjkz4qoug4q6zu } }
+$ storagext-cli --sr25519-key "//Charlie" storage-provider prove-commit "@prove-commit-husky.json"
+[0x0743…6fd3] Sector Proven: { owner: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, sector_number: 1, partition_number: 0, deadline_idx: 0 }
+```
+
+
+
+[^slash]: You can wait for 5 minutes and observe a `DealSlashed` [Event](../pallets/market.md#events) being published.
+
+## 3. Proofs and faults
+
+### Aside on Deadlines
+
+There is a little something that Charlie needs to know about: deadlines *(don't we all...)*.
+
+Each Storage Provider has a Proving Period, a time divided into segments (deadlines).
+To simplify, let's say a proving period lasts a day (24 hours), and between the start and end of each hour, there is a segment, just like on a clock.
+
+
+
+Now, when Charlie gathers enough data and stores it in a sector, he must keep proving that he has some data.
+Charlie can have multiple sectors and he doesn't want to overload the system by proving all of them simultaneously.
+So what if each sector got assigned a segment (1 hour) during the day, and Charlie would need to submit proof that he has data roughly on the same hour each day?
+That'd work, right?
+
+So this is what a Proving Period and Deadlines are.
+We divide a proving period into deadlines and when we prove commit, we assign a sector to a deadline.
+From now on, the sector must be proven periodically and daily during this lifetime.
+
+`windowed-post.json`
+```json
+{
+ "deadline": 0,
+ "partitions": [0],
+ "proof": {
+ "post_proof": "2KiB",
+ "proof_bytes": "1230deadbeef"
+ }
+}
+```
+
+
+| Name | Value | Description |
+| ------------- | ---------------- | ----------------------------------------------------------------------------- |
+| `deadline` | `0` | the deadline index which has been assigned by the Prove Commit |
+| `partitions` | `[0]` | the partitions which have been assigned by Prove Commit |
+| `post_proof` | "2KiB" | we only support sectors of size 2KiB for now, so it's the only possible value |
+| `proof_bytes` | `0x1230deadbeef` | hex string of bytes of the proof, it's WIP, so any non-zero value works |
+
+Now that the sector has been proven, Charlie must keep confirming that he stores the data.
+Charlie's proving period starts at block `21` (as `register-storage-provider` tells us), so the first deadline is between blocks `[21, 31)`, second `[31, 41)`.
+That's because there are [2 deadlines](#const-period-deadlines) within a [proving period](#const-proving-period), and a deadline has a [window of 10 blocks](#const-challenge-window).
+Charlie got assigned the first deadline, so he waits until block `21` to send the proof that he still stores the data.
+
+```bash
+$ storagext-cli --sr25519-key "//Charlie" storage-provider submit-windowed-post "@windowed-post.json"
+[0x3aa1…a12a] Valid PoSt Submitted: { owner: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y }
+```
+
+
+
+The next proving period starts at block `41`, with the deadline `[41, 51)`, so Charlie must submit his proof on this block.
+He knows he won't be able to create a proof, as his hard drives went down, so he reports it. If he didn't report, he'd get slashed.
+
+`fault-declaration.json`
+
+```json
+[
+ {
+ "deadline": 0,
+ "partition": 0,
+ "sectors": [1]
+ }
+]
+```
+
+```bash
+$ storagext-cli --sr25519-key "//Charlie" storage-provider declare-faults "@fault-declaration.json"
+[0x49cd…9a88] Faults Declared: { owner: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, faults: [Fault Declaration: { deadline: 0, partition: 0, sectors: [1] }] }
+```
+
+
+
+Charlie fixed his issues with storage and now wants to declare that he can still provide data in this sector.
+If he does this too late (1 minute before the next deadline starts), he won't be able to.
+
+```bash
+$ storagext-cli --sr25519-key "//Charlie" storage-provider declare-faults-recovered "@fault-declaration.json"
+Error: Runtime error: Pallet error: StorageProvider::FaultRecoveryTooLate
+
+Caused by:
+ Pallet error: StorageProvider::FaultRecoveryTooLate
+```
+
+
+If he does it at least a minute before, it succeeds:
+
+```bash
+$ storagext-cli --sr25519-key "//Charlie" storage-provider declare-faults-recovered "@fault-declaration.json"
+[0xca6b…875c] Faults Recovered: { owner: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, recoveries: [Recovery Declaration: { deadline: 0, partition: 0, sectors: [1] }] }
+```
+
+And then, at the next deadline, in the next proving period `[41, 51)` he needs to remember to submit windowed PoSt again.
+
+```bash
+$ storagext-cli --sr25519-key "//Charlie" storage-provider submit-windowed-post "@windowed-post.json"
+[0x3e46…5636] Valid PoSt Submitted: { owner: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y }
+```
+
+## 4. Reaping the rewards
+
+After the deal ends (after block `50`), Charlie goes to get his rewards!
+First, he settles all of the locked funds, so his balance gets unlocked, and then he withdraws the balance from his Market account to use his DOTs for a new shiny dumbbell.
+
+```bash
+$ storagext-cli --sr25519-key "//Charlie" market settle-deal-payments 0
+[0x1633…d17b] Deals settled: { successful: [Settled Deal { deal_id: 0, provider_account: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, client_account: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY, amount: 25000000000 }], unsuccessful: [] }
+$ storagext-cli --sr25519-key "//Charlie" market withdraw-balance 37500000000
+[0x0197…bdd9] Balance Withdrawn: { account: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y, amount: 37500000000 }
+```
diff --git a/src/getting-started/index.md b/src/getting-started/index.md
new file mode 100644
index 0000000..b98f003
--- /dev/null
+++ b/src/getting-started/index.md
@@ -0,0 +1,16 @@
+# Getting Started
+
+This chapter will guide you through setting up, running, and trying out the components that have been implemented so far.
+
+## System Requirements
+
+Before proceeding with the setup, please ensure your system meets the following requirements:
+
+- **OS**: Linux x86_64/MacOS ARM x64
+- **RAM**: Minimum 8GB, recommended 16GB or more
+
+## Guides
+
+- [*Local Testnet - Polka Storage Parachain*](local-testnet.md) — Covers how to setup a local testnet for the Polka Storage parachain, using Zombienet.
+- [*CAR server*](car-server.md) — Covers how to setup and run the CARv2 server, which transforms files into `.car` archives.
+- [*Real-world use case demo*](demo.md) — Covers a real-world use case, adding balances, submitting sectors, and more!
diff --git a/src/getting-started/local-testnet.md b/src/getting-started/local-testnet.md
new file mode 100644
index 0000000..f285db9
--- /dev/null
+++ b/src/getting-started/local-testnet.md
@@ -0,0 +1,310 @@
+# Local Testnet - Polka Storage Parachain
+
+This guide will help you set up a local parachain network using zombienet.
+At the end, we will have three nodes: Alice, Bob and Charlie.
+Alice and Bob will be running Polkadot relay chain nodes as validators,
+and Charlie will run a relay chain and parachain node.
+Charlie will be our contact point to the parachain network.
+
+## Native Binaries
+
+You can download our latest releases's binaries directly and run them on your machine without 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`),
+- Polka Storage Parachain binary (`polka-storage-node`),
+- [Polka Storage Provider](../storage-provider-cli/index.md) internal node (`polka-storage-provider`),
+- [CLI for interacting with the parachain](../storagext-cli/) (`storagext-cli`),
+- [zombienet](https://paritytech.github.io/zombienet/install.html) to spawn local testnets and orchestrate them (`zombienet`),
+- Polka Storage Parachain out-of-the-box zombienet's configuration (`polka-storage-testnet.toml`).
+
+### Linux x86_64
+
+1. Download the binaries:
+
+```bash
+wget https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-v1.13.0/polkadot
+wget https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-v1.13.0/polkadot-prepare-worker
+wget https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-v1.13.0/polkadot-execute-worker
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/linux_x86-64/polka-storage-node
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/linux_x86-64/polka-storage-provider
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/linux_x86-64/storagext-cli
+wget https://github.com/paritytech/zombienet/releases/download/v1.3.106/zombienet-linux-x64 -O zombienet
+```
+
+2. Setup permissions:
+
+```bash
+chmod +x zombienet polka-storage-node polka-storage-provider storagext-cli polkadot polkadot-prepare-worker polkadot-execute-worker
+```
+
+3. Run `zombienet`:
+
+```bash
+export PATH=$(pwd):$PATH
+
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/polka-storage-testnet.toml
+zombienet -p native spawn polka-storage-testnet.toml
+```
+
+### MacOS ARM
+
+1. Download the binaries:
+
+```bash
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/macos_arm/polkadot
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/macos_arm/polkadot-prepare-worker
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/macos_arm/polkadot-execute-worker
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/macos_arm/polka-storage-node
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/macos_arm/polka-storage-provider
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/macos_arm/storagext-cli
+wget https://github.com/paritytech/zombienet/releases/download/v1.3.106/zombienet-macos-arm64 -O zombienet
+```
+
+2. Setup permissions & de-quarantine:
+
+```bash
+chmod +x zombienet polka-storage-node polka-storage-provider storagext-cli polkadot polkadot-prepare-worker polkadot-execute-worker
+xattr -d com.apple.quarantine zombienet polka-storage-node polka-storage-provider storagext-cli polkadot polkadot-prepare-worker polkadot-execute-worker
+```
+
+
+If, when running the
+
+3. Run `zombienet`:
+
+```bash
+export PATH=$(pwd):$PATH
+
+wget https://s3.eu-central-1.amazonaws.com/polka-storage/polka-storage-testnet.toml
+zombienet -p native spawn polka-storage-testnet.toml
+```
+
+You can easily access the parachain using the Polkadot.js Apps interface by clicking on this link:
+xattr command, it outputs No such attr: com.apple.quarantine, there's nothing to worry about. It means the downloaded binaries were not quarantined.
+
+
+ 
+
+
+Docker Images were only published on x86_64 platforms! They won't work on Kubernetes on MacOS.
+
+
+### Prerequisites
+
+- [zombienet v1.3.106](https://github.com/paritytech/zombienet/releases/tag/v1.3.106) - cli tool to easily spawn ephemeral Polkadot/Substrate networks and perform tests against them.
+- [minikube](https://minikube.sigs.k8s.io/docs/start/) — to run the parachain nodes
+- a configured [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) — is used to set up the required kubernetes resources by `zombienet`
+ - [https://minikube.sigs.k8s.io/docs/handbook/kubectl/](https://minikube.sigs.k8s.io/docs/handbook/kubectl/)
+ - [https://kubernetes.io/docs/tasks/tools/#kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
+
+### Start up the Kubernetes cluster
+
+Using `minikube`, you can start the cluster with the following command:
+
+```
+minikube start
+```
+
+You can read more about `minikube` on its [Getting Started](https://minikube.sigs.k8s.io/docs/handbook/controls/) page.
+
+### Running the Parachain
+
+1. Create a `local-kube-testnet.toml` file on your machine with the following content.
+
+```toml
+[settings]
+image_pull_policy = "IfNotPresent"
+
+[relaychain]
+chain = "rococo-local"
+default_args = ["--detailed-log-output", "-lparachain=debug,xcm=trace,runtime=trace"]
+default_image = "docker.io/parity/polkadot:v1.13.0"
+
+[[relaychain.nodes]]
+name = "alice"
+validator = true
+
+[[relaychain.nodes]]
+name = "bob"
+validator = true
+
+[[parachains]]
+cumulus_based = true
+
+# We need to use a Parachain of an existing System Chain (https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/runtime/rococo/src/xcm_config.rs).
+# The reason: being able to get native DOTs from Relay Chain to Parachain via XCM Teleport.
+# We'll have a proper Parachain ID in the *future*, but for now, let's stick to 1000 (which is AssetHub and trusted).
+id = 1000
+
+# Run Charlie as parachain collator
+[[parachains.collators]]
+args = ["--detailed-log-output", "-lparachain=debug,xcm=trace,runtime=trace"]
+command = "polka-storage-node"
+image = "polkadotstorage.azurecr.io/parachain-node:0.1.0"
+name = "charlie"
+rpc_port = 42069
+validator = true
+```
+
+2. Run the Parachain, and spawn the zombienet testnet in the Kubernetes cluster:
+
+```
+zombienet -p kubernetes spawn local-kube-testnet.toml
+```
+
+
+
+
+### Verifying the Setup
+
+Check if all zombienet pods were started successfully:
+
+`kubectl get pods --all-namespaces`
+
+Click here to show the example output.
+ +``` +│ /ip4/10.1.0.16/tcp/30333/ws/p2p/12D3KooWPKzmmE2uYgF3z13xjpbFTp63g9dZFag8pG6MgnpSLF4S │ +└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ + + Warn: Tracing collator service doesn't exist +┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Network launched 🚀🚀 │ +├──────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Namespace │ zombie-1cecb9b5e0f9a14208f2fbefd9384490 │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Provider │ kubernetes │ +├──────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Node Information │ +├──────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Name │ alice │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Direct Link │ https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A34341#/explorer │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Prometheus Link │ http://127.0.0.1:35537/metrics │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Log Cmd │ kubectl logs -f alice -c alice -n zombie-1cecb9b5e0f9a14208f2fbefd9384490 │ +├──────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Node Information │ +├──────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Name │ bob │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Direct Link │ https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A44459#/explorer │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Prometheus Link │ http://127.0.0.1:43841/metrics │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Log Cmd │ kubectl logs -f bob -c bob -n zombie-1cecb9b5e0f9a14208f2fbefd9384490 │ +├──────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Node Information │ +├──────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Name │ charlie │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Direct Link │ https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A42069#/explorer │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Prometheus Link │ http://127.0.0.1:42675/metrics │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Log Cmd │ kubectl logs -f charlie -c charlie -n zombie-1cecb9b5e0f9a14208f2fbefd9384490 │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ Parachain ID │ 1000 │ +├──────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤ +│ ChainSpec Path │ /tmp/zombie-1cecb9b5e0f9a14208f2fbefd9384490_-29755-WOCdKtq9zPGA/1000-rococo-local.json │ +└──────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┘ +``` + +
+
+
+### Accessing the Parachain
+
+You can easily access the parachain using the Polkadot.js Apps interface by clicking on this link:
+
+[https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A42069#/explorer](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A42069#/explorer)
+
+This link will automatically connect to Charlie's node running on your local machine at port `42069`. The port is configured in `local-kube-testnet.toml` under `rpc_port` for Charlie's node.
+
+## Zombienet Configuration Breakdown
+
+During the setup, you either download a file in the third step of [Linux](#linux-x86_64)/[MacOS](#macos-arm) — `polka-storage-testnet.toml` —
+or copy it from the first step of [Running the parachain](#running-the-parachain).
+
+### Similarities
+
+The two files share most of the contents, so we'll start by covering their similarities.
+For more details, you should refer to the [`zombienet` documentation](https://paritytech.github.io/zombienet/network-definition-spec.html):
+
+#### `relaychain`
+
+| Name | Description |
+| ----------------- | --------------------------------------------- |
+| `chain` | The relaychain name |
+| `default_args` | The default arguments passed to the `command` |
+| `default_command` | The default command to run the relaychain |
+| `nodes` | List of tables defining the nodes to run |
+
+##### `nodes`
+
+| Name | Description |
+| ----------- | -------------------------------------- |
+| `name` | The node name |
+| `validator` | Whether the node is a validator or not |
+
+#### `parachains`
+
+A list of tables defining multiple parachains, in our case, we only care for our own parachain.
+
+| Name | Description |
+| --------------- | ------------------------------------------------------------- |
+| `cumulus_based` | Whether to use `cumulus` based generation |
+| `id` | The parachain ID, we're using `1000` as a placeholder for now |
+| `collators` | List of tables defining the collators |
+
+##### `collators`
+
+| Name | Description |
+| ----------- | ---------------------------------------- |
+| `args` | The arguments passed to the `command` |
+| `command` | The command to run the collator |
+| `name` | The collator name |
+| `validator` | Whether the collator is also a validator |
+
+### Differences
+
+The difference between them lies in the usage of container configurations:
+
+| Name | Description |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image_pull_policy` | Defines when `zombienet` should pull an image; read more about it in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy) |
+| `image` | Defines which image to pull |
+| `ws_port`/`rpc_port` | Depending on the type of configuration (Native or Kubernetes), this variable sets the port for the collator RPC service |
diff --git a/src/glossary.md b/src/glossary.md
new file mode 100644
index 0000000..9ff43e2
--- /dev/null
+++ b/src/glossary.md
@@ -0,0 +1,306 @@
+# Glossary and Anti-Glossary
+
+This document provides definitions and explanations for terms used throughout the project and a list of terms that should not be used.
+
+## Table of Contents
+
+- [Glossary and Anti-Glossary](#glossary-and-anti-glossary)
+ - [Table of Contents](#table-of-contents)
+ - [Glossary](#glossary)
+ - [Actor](#actor)
+ - [Bond](#bond)
+ - [Collateral](#collateral)
+ - [Collator](#collator)
+ - [Committed Capacity](#committed-capacity)
+ - [Commitment of Data](#commitment-of-data)
+ - [Commitment of Replication](#commitment-of-replication)
+ - [Crowdloan](#crowdloan)
+ - [Deadline](#deadline)
+ - [Extrinsics](#extrinsics)
+ - [Fault](#fault)
+ - [Full Node](#full-node)
+ - [Invulnerable](#invulnerable)
+ - [Node](#node)
+ - [Parachain](#parachain)
+ - [Partition](#partition)
+ - [Planck](#planck)
+ - [Polkadot](#polkadot)
+ - [Proofs](#proofs)
+ - [Proving Period](#proving-period)
+ - [Relay Chain](#relay-chain)
+ - [Sector](#sector)
+ - [Session](#session)
+ - [Slashing](#slashing)
+ - [Slot Auction](#slot-auction)
+ - [Staking](#staking)
+ - [Storage Provider](#storage-provider)
+ - [Storage User](#storage-user)
+ - [System Parachain](#system-parachain)
+ - [Anti-Glossary](#anti-glossary)
+ - [Term to Avoid: Miner](#term-to-avoid-miner)
+ - [Term to Avoid: Pledge](#term-to-avoid-pledge)
+
+## Glossary
+
+This section lists terms used throughout the project.
+
+### Actor
+
+In [Filecoin](https://spec.filecoin.io/#section-glossary.filecoin),
+an [actor](https://spec.filecoin.io/#section-glossary.actor) is an on-chain object with its state and set of
+methods. [Actors](https://spec.filecoin.io/#section-glossary.actor) define how
+the [Filecoin](https://spec.filecoin.io/#section-glossary.filecoin) network manages and updates its global state.
+
+### Bond
+
+This term is used in:
+
+- Parachain [Slot Auction](#slot-auction). To bid in an auction, [parachain](#parachain) teams agree to lock up (or
+ bond) a portion of DOT tokens for the duration of the lease. While bonded for a lease, the DOT cannot be used for
+ other activities like staking or transfers.
+
+- [Collator](#collator) slot auction (selection mechanism). It is used as a deposit to become a collator. Candidates can
+ register by placing the minimum bond. Then, if an account wants to participate in the [collator](#collator) slot
+ auction, they have to replace an existing candidate by placing a more significant deposit (bond).
+
+### Collateral
+
+[Collaterals](https://spec.filecoin.io/#section-glossary.collateral) are assets locked up or deposited as a form of security
+to mitigate risks and ensure the performance of specific actions. Collateral acts as a guarantee that an
+individual will fulfil their obligations. Failing to meet obligations or behaving maliciously can result in the loss of
+staked assets or collateral as a penalty for non-compliance or misconduct by [slashing](#slashing).
+
+### Collator
+
+[Collators](https://wiki.polkadot.network/docs/learn-collator) maintain [parachains](#parachain) by
+collecting [parachain](#parachain) transactions from users and producing state transition proofs
+for [Relay Chain](#relay-chain) validators. In other words, collators maintain [parachains](#parachain) by
+aggregating [parachain](#parachain) transactions into [parachain](#parachain) block candidates and producing state
+transition proofs (Proof-of-Validity, PoV) for validators. They must provide a financial
+commitment ([collateral](#collateral)) to ensure they are incentivized to perform their duties correctly and
+to dissuade malicious behaviour.
+
+### Committed Capacity
+
+The [Committed Capacity](https://spec.filecoin.io/#section-glossary.capacity-commitment) (CC) is one of three types of
+deals in which there is effectively no deal, and the [Storage Provider](#storage-provider) stores random data inside the
+sector instead of customer data.
+
+If a [storage provider](#storage-provider) doesn't find any available deal proposals appealing, they can alternatively
+make a capacity commitment, filling a sector with arbitrary data, rather than with client data. Maintaining this sector
+allows the [storage provider](#storage-provider) to provably demonstrate that they are reserving space on behalf of the
+network.
+
+### Commitment of Data
+
+This value is also known as `commD` or `unsealed_cid`.
+As the storage miner receives each piece of client data, they place it into a sector. Sectors are the fundamental units of storage in Filecoin,
+and can contain pieces from multiple deals and clients.
+
+Once a sector is full, a CommD (Commitment of Data, aka UnsealedSectorCID) is produced, representing the root node of all the piece CIDs contained in the sector.
+
+### Commitment of Replication
+
+The terms `commR`, `sealed_cid`, `commitment of replication` are interchangeable.
+During sealing, the sector data (identified by the CommD) is encoded through a sequence of graph and hashing processes to create a unique replica.
+The root hash of the merkle tree of the resulting replica is the CommRLast.
+
+The CommRLast is then hashed together with the CommC (another merkle root output from Proof of Replication).
+This generates the CommR (Commitment of Replication, aka SealedSectorCID), which is recorded to the public blockchain.
+The CommRLast is saved privately by the miner for future use in Proof of Spacetime, but is not saved to the chain.
+
+### Crowdloan
+
+Projects can raise DOT tokens from the community
+through [crowdloans](https://wiki.polkadot.network/docs/learn-crowdloans). Participants pledge their DOT tokens to help
+the project win a parachain slot auction. If successful, the tokens are locked up for the duration of the parachain
+lease, and participants might receive rewards or tokens from the project in return.
+
+### Deadline
+
+A deadline is one of the multiple points during a proving period when proofs for some partitions are due.
+
+For more information on deadlines, you can read the original Filecoin specification:
+Click here to show the example output.
+ +``` +... +zombie-01b7920d650c18d3d78f75fd8b0978af alice 1/1 Running 0 77s +zombie-01b7920d650c18d3d78f75fd8b0978af bob 1/1 Running 0 62s +zombie-01b7920d650c18d3d78f75fd8b0978af charlie 1/1 Running 0 49s +zombie-01b7920d650c18d3d78f75fd8b0978af fileserver 1/1 Running 0 2m28s +zombie-01b7920d650c18d3d78f75fd8b0978af temp 0/1 Completed 0 2m25s +zombie-01b7920d650c18d3d78f75fd8b0978af temp-1 0/1 Completed 0 2m25s +zombie-01b7920d650c18d3d78f75fd8b0978af temp-2 0/1 Completed 0 2m15s +zombie-01b7920d650c18d3d78f75fd8b0978af temp-3 0/1 Completed 0 2m1s +zombie-01b7920d650c18d3d78f75fd8b0978af temp-4 0/1 Completed 0 114s +zombie-01b7920d650c18d3d78f75fd8b0978af temp-5 0/1 Completed 0 91s +zombie-01b7920d650c18d3d78f75fd8b0978af temp-collator 0/1 Completed 0 104s +``` + +
+ 
+
+
+ 
+
+
+
+Now that storage providers can be registered in the storage provider pallet, we need to add some balance to both the
+[Storage User's](../glossary.md#storage-user) and the Provider's accounts,
+which is done using the Market's [`add_balance`](./market.md#add_balance) extrinsic.
+
+
+
+Afterwards, storage users and providers negotiate data storage deals off-chain.
+Once a deal between the two parties is reached, the client can sign the deal and send it to the storage provider for publishing
+— the storage provider will then publish the signed deal using the [`publish_storage_deals`](market.md#publish_storage_deals) extrinsic.
+
+After publishing, the funds allocated for the deal will be moved from `free` to `locked`, and they can no longer be withdrawn until the deal has ended.
+
+
+
+At this point, the remaining responsibility is shifted to the storage provider, which needs to activate the deal;
+to do so, the storage provider first needs to [pre-commit](./storage-provider.md#pre_commit_sector) the deal's sectors,
+and then [prove](./storage-provider.md#prove_commit_sector) they stored the sectors
+— these two steps are done using the [`pre_commit_sector`](./storage-provider.md#pre_commit_sector) and [`prove_commit_sector`](./storage-provider.md#prove_commit_sector) extrinsics.
+
+Verification is done and reported to the Market pallet to terminate the deal and apply penalties to the storage provider
+(remove and burn its collateral — i.e. `locked` funds) if they fail to activate the deal on time and return the funds to the client.
+
+
+
+Suppose the deal has been completed successfully or is **Active**.
+In that case, the storage provider is now required to periodically submit proofs that they're still storing the user's data
+— the storage provider does this by calculating a proof and submitting it using [`submit_windowed_post`](./storage-provider.md#submit_windowed_post).
+
+
+
+Finally, storage providers can then settle deal payments to receive their fair share for keeping the user's data safe — using the [`settle_deal_payments`](./market.md#settle_deal_payments) extrinsic.
+
+
+
+Putting it all together, we get the following:
+
+
+
+
diff --git a/src/pallets/market.md b/src/pallets/market.md
new file mode 100644
index 0000000..db00d71
--- /dev/null
+++ b/src/pallets/market.md
@@ -0,0 +1,235 @@
+# Market Pallet
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Extrinsics](#extrinsics)
+ - [`add_balance`](#add_balance)
+ - [`withdraw_balance`](#withdraw_balance)
+ - [`settle_deal_payments`](#settle_deal_payments)
+ - [`publish_storage_deals`](#publish_storage_deals)
+- [Events](#events)
+- [Errors](#errors)
+- [Constants](#constants)
+
+## Overview
+
+The purpose of the pallet is to manage storage deals between storage market participants and to track their funds.
+Market Pallet is tightly coupled with [Storage Provider Pallet](./storage-provider.md) because it's a source of truth for deals.
+Storage Provider Pallet cannot exist without deal information from Market Pallet.
+
+## Extrinsics\*
+
+### `add_balance`
+
+Reserves a given amount of currency for usage in the Storage Market.
+
+The reserved amount will be considered `free` until it is used in a deal when moved to `locked` and used to pay for the deal.
+
+| Name | Description | Type |
+| -------- | ------------------------- | ---------------- |
+| `amount` | The amount to be reserved | Positive integer |
+
+#### Example
+
+Using the `storagext-cli` you can add 1000000000[^existential_deposit] [Plancks](../glossary.md#planck) to Alice's account with the following command[^add_balance]:
+
+```bash
+storagext-cli --sr25519-key "//Alice" market add-balance 1000000000
+```
+
+[^existential_deposit]:
+ This value is the minimum amount due to Polkadot's existential deposit.
+ You can read more about it at
+Notice how the CLI command doesn't take the
+
+[^storage_price_per_block]: The formula to calculate the total price is as follows: \\[total\\\_price = (end\\\_block - start\\\_block) * storage\\_price\\_per\\_block\\]
+[^publish_storage_deals]: Read more about the `publish-storage-deals` command in [_Storagext CLI/Subcommand `market`/`publish-storage-deals`_](../storagext-cli/market.md#publish-storage-deals)
+[^warn]: Take into account that the CLI is currently for demo purposes, the authors are aware that the command isn't safe since it requires the private keys of both parties.
+
+### `settle_deal_payments`
+
+Settle specified deals between providers and clients.
+
+Both clients and providers can call this extrinsic.
+However, since the settlement is the mechanism through which the provider gets paid,
+a client has no reason to call this extrinsic.
+Non-existing deal IDs will be ignored.
+
+| Name | Description | Type |
+| ---------- | ---------------------------------- | ----------------- |
+| `deal_ids` | List of the deal IDs to be settled | Array of integers |
+
+#### Example
+
+Using the `storagext-cli` you can settle deal payments for IDs 97, 1010, 1337 and 42069 using the following command[^settle_deal_payments]:
+
+```bash
+storagext-cli --sr25519-key "//Alice" market settle-deal-payments 97 1010 1337 42069
+```
+
+[^settle_deal_payments]: Read more about the `settle-deal-payments` command in [_Storagext CLI/Subcommand `market`/`settle-deal-payments`_](../storagext-cli/market.md#settle-deal-payments)
+
+## Events
+
+The Market Pallet emits the following events:
+
+- `BalanceAdded` - Indicates that some balance was added as _free_ to the Market Pallet account for usage in the storage market.
+ - `who` - SS58 address of then account which added balance
+ - `amount` - Amount added
+- `BalanceWithdrawn` - Some balance was transferred (free) from the Market Account to the Participant's account.
+ - `who` - SS58 address of the account which had withdrawn the balance
+ - `amount` - Amount withdrawn
+- `DealPublished` - Indicates that a deal was successfully published with `publish_storage_deals`.
+ - `deal_id` - Unique deal ID
+ - `client` - SS58 address of the storage client
+ - `provider` - SS58 address of the storage provider
+- `DealActivated` - Deal's state has changed to `Active`.
+ - `deal_id` - Unique deal ID
+ - `client` - SS58 address of the storage client
+ - `provider` - SS58 address of the storage provider
+- `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
+ - `deal_id` - Deal ID that was slashed
+- `DealTerminated` - Is emitted it indicates that the deal was voluntarily or involuntarily terminated.
+ - `deal_id` - Terminated deal ID
+ - `client` - SS58 address of the storage client
+ - `provider` - SS58 address of the storage provider
+
+## Errors
+
+The Market Pallet actions can fail with following errors:
+
+- `InsufficientFreeFunds` - Market participants do not have enough free funds.
+- `NoProposalsToBePublished` - `publish_storage_deals` was called with an empty list of `deals`.
+- `ProposalsNotPublishedByStorageProvider` - Is returned when calling `publish_storage_deals` and the deals in a list are not published by the same storage provider.
+- `AllProposalsInvalid` - `publish_storage_deals` call was supplied with a list of `deals` which are all invalid.
+- `DuplicateDeal` - There is more than one deal with this ID in the Sector.
+- `DealNotFound` - Tried to activate a deal that is not in the system.
+- `DealActivationError` - Tried to activate a deal, but data was malformed.
+ - Invalid specified provider.
+ - The deal already expired.
+ - Sector containing the deal expires before the deal.
+ - Invalid deal state.
+ - Deal is not pending.
+- `DealsTooLargeToFitIntoSector` - Sum of all deals piece sizes for a sector exceeds sector size. The sector size is based on the registered proof type. We currently only support registered `StackedDRG2KiBV1P1` proofs, which have 2KiB sector sizes.
+- `TooManyDealsPerBlock` - Tried to activate too many deals at a given `start_block`.
+- `UnexpectedValidationError` - `publish_storage_deals`'s core logic was invoked with a broken invariant that `validate_deals` should call. Report an issue if you receive this error.
+- `DealPreconditionFailed` - Due to a programmer bug. Report an issue if you receive this error.
+
+## Constants
+
+| Name | Description | Value |
+| ------------------ | ----------------------------------------------------------------------------- | ----------- |
+| `MaxDeals` | How many deals can be published in a single batch of `publish_storage_deals`. | 128 |
+| `MaxDealsPerBlock` | Maximum deals that can be scheduled to start at the same block. | 128 |
+| `MinDealDuration` | Minimum time an activated deal should last. | 5 Minutes |
+| `MaxDealDuration` | Maximum time an activated deal should last. | 180 Minutes |
diff --git a/src/pallets/storage-provider-extra.md b/src/pallets/storage-provider-extra.md
new file mode 100644
index 0000000..caee767
--- /dev/null
+++ b/src/pallets/storage-provider-extra.md
@@ -0,0 +1,74 @@
+
+
+## Storage fault slashing
+
+Storage Fault Slashing refers to a set of penalties that storage providers may incur if they fail to maintain sector reliability or choose to voluntarily exit the network. These penalties include Fault Fees, Sector Penalties, and Termination Fees. Below is a detailed explanation of each type of penalty.
+
+### Fault Fee (FF)
+
+- **Description**: A penalty incurred by a storage provider for each day that a sector is offline.
+- **Rationale**: Ensures that storage providers maintain high availability and reliability of their committed data.
+
+### Sector Penalty (SP)
+
+- **Description**: A penalty incurred by a storage provider for a sector that becomes faulted without being declared as such before a WindowPoSt (Proof-of-Spacetime) check.
+- **Rationale**: Encourages storage providers to promptly declare any faults to avoid more severe penalties.
+- **Details**: If a fault is detected during a WindowPoSt check, the sector will incur an SP and will continue to incur a FF until the fault is resolved.
+
+### Termination Penalty (TP)
+
+- **Description**: A penalty incurred when a sector is either voluntarily or involuntarily terminated and removed from the network.
+- **Rationale**: Discourages storage providers from arbitrarily terminating sectors and ensures they fulfill their storage commitments.
+
+By implementing these penalties, storage providers are incentivised to maintain the reliability and availability of the data they store. This system of Storage Fault Slashing helps maintain the integrity and reliability of our decentralized storage network.
+
+### State management for Storage Providers
+
+In our parachain, the state management for all storage providers is handled collectively, unlike Filecoin, which manages the state for individual storage providers.
+
+## Sector sealing
+
+Before a sector can be used, the storage provider must seal the sector, which involves encoding the data in the sector to prepare it for the proving process.
+
+- **Unsealed Sector**: An unsealed sector is a sector containing raw data that has not yet been sealed.
+- **UnsealedCID (CommD)**: The root hash of the unsealed sector’s Merkle tree, also referred to as CommD or "data commitment."
+- **Sealed Sector**: A sector that has been encoded and prepared for the proving process.
+- **SealedCID (CommR)**: The root hash of the sealed sector’s Merkle tree, also referred to as CommR or "replica commitment."
+
+By sealing sectors, storage providers ensure that data is properly encoded and ready for the proof-of-storage process, maintaining the integrity and security of the stored data in the network.
+
+Sealing a sector using Proof-of-Replication (PoRep) is a computation-intensive process that results in a unique encoding of the sector. Once the data is sealed, storage providers follow these steps:
+
+- **Generate a Proof**: Create a proof that the data has been correctly sealed.
+- **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
+
+The first thing a storage provider must do is register itself by calling `storage_provider.create_storage_provider(peer_id: PeerId, window_post_proof_type: RegisteredPoStProof)`. At this point there are no funds locked in the storage provider pallet. The next step is to place storage market asks on the market, this is done through the market pallet. After that the storage provider needs to make deals with clients and begin filling up sectors with data. When they have a full sector they should seal the sector.
+
+### Commit
+
+When the storage provider has completed their first seal, they should post it to the storage provider pallet by calling `storage_provider.pre_commit_sector(sectors: SectorPreCommitInfo)`. If the storage provider had zero committed sectors before this call, this begins their proving period. The proving period is a fixed amount of time in which the storage provider must submit a Proof of Space Time to the network.
+During this period, the storage provider may also commit to new sectors, but they will not be included in proofs of space time until the next proving period starts. During the prove commit call, the storage provider pledges some collateral in case they fail to submit their PoSt on time.
+
+### Proof of Spacetime submission
+
+When the storage provider has completed their PoSt, they must submit it to the network by calling `storage_provider.submit_windowed_post(deadline: u64, partitions: Vecclient_signature parameter but a keypair that can sign it.
+
+We are aware that this is **not secure**. However, the system is still under development
+and is **not final**; it is a testing tool.
+
+
+
+[^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.
+Accordingly, removing and burning the collateral locked up during the pre-commit.
+
+## Extrinsics
+
+### `register_storage_provider`
+
+Storage Provider registration is the first extrinsic any storage provider must call. Without being registered, other extrinsics will return an error.
+
+Before a storage provider can register, they must set up a [PeerId](https://docs.libp2p.io/concepts/fundamentals/peers/#peer-id). This [PeerId](https://docs.libp2p.io/concepts/fundamentals/peers/#peer-id) is used in the p2p network to connect to the storage provider.
+
+| Name | Description | Type |
+| ------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `peer_id` | [libp2p](https://libp2p.io/) [ID](https://docs.libp2p.io/concepts/fundamentals/peers/) | Hex string of the PeerId bytes |
+| `window_post_proof_type` | Proof type the storage provider uses | String, currently only `StackedDRGWindow2KiBV1P1` is available |
+
+#### Example
+
+Registering a storage provider with keypair `//Alice` and peer ID `alice` with the following command[^register_storage_provider]:
+
+```bash
+storagext-cli --sr25519-key "//Alice" storage-provider register alice
+```
+
+[^register_storage_provider]: Read more about the `register` command in [_Storagext CLI/Subcommand `storage-provider`/`register`_](../storagext-cli/storage-provider.md#register)
+
+### `pre_commit_sector`
+
+After publishing a deal, the storage provider needs to pre-commit the sector information to the chain.
+Sectors are not valid after pre-commit. The sectors need to be proven first.
+
+| Name | Description | Type |
+| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `seal_proof` | Seal proof type this storage provider is using [^note] | String, currently only `StackedDRGWindow2KiBV1P1` is available |
+| `sector_number` | The sector number that is being pre-committed | Positive integer |
+| `sealed_cid` | [Commitment of replication](../glossary.md#commitment-of-replication) | Hex string of the sealed CID bytes |
+| `deal_ids` | Deal IDs to be pre-committed, from `publish_storage_deals` | Array of integers |
+| `expiration` | Expiration block of the pre-committed sector | Positive integer |
+| `unsealed_cid` | Commitment of data [sector sealing](../glossary.md#commitment-of-data) | Hex string of the unsealed CID bytes |
+
+
+Sectors are not valid after pre-commit. The sectors need to be proven first.
+
+
+[^note]: Only one seal-proof type supported at the moment, `2KiB`.
+
+#### Example
+
+Storage provider `//Alice` pre-committing[^pre_commit_sector] a sector number 1, with a single deal ID 0.
+
+```bash
+storagext-cli --sr25519-key "//Alice" storage-provider pre-commit @pre-commit-sector.json
+```
+
+Where `pre-commit-sector.json` is a file with contents similar to:
+
+```json
+{
+ "sector_number": 1,
+ "sealed_cid": "bafk2bzaceajreoxfdcpdvitpvxm7vkpvcimlob5ejebqgqidjkz4qoug4q6zu",
+ "deal_ids": [0],
+ "expiration": 100,
+ "unsealed_cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
+ "seal_proof": "StackedDRG2KiBV1P1"
+}
+```
+
+[^pre_commit_sector]: Read more about the `pre-commit` command in [_Storagext CLI/Subcommand `storage-provider`/`pre-commit`_](../storagext-cli/storage-provider.md#pre-commit)
+
+### `prove_commit_sector`
+
+After pre-committing some new sectors the storage provider needs to supply a [Proof-of-Replication](../glossary.md#commitment-of-replication) for these sectors [^note].
+
+| Name | Description | Type |
+| --------------- | -------------------------------------------------------------------- | ----------------------------- |
+| `sector_number` | The sector number that is being prove-committed | Positive integer |
+| `proof` | The [proof of replication](../glossary.md#commitment-of-replication) | Hex string of the proof bytes |
+
+[^note]: At the moment, any proof of non-zero length is accepted for PoRep.
+
+#### Example
+
+This example follows up on the pre-commit example. Storage provider `//Alice` is proven committing[^prove_commit_sector] sector number 1.
+
+```bash
+storagext-cli --sr25519-key "//Alice" storage-provider prove-commit @prove-commit-sector.json
+```
+
+Where `prove-commit-sector.json` is a file with contents similar to:
+
+```json
+{
+ "sector_number": 1,
+ "proof": "1230deadbeef"
+}
+```
+
+[^prove_commit_sector]: Read more about the `prove-commit` command in [_Storagext CLI/Subcommand `storage-provider`/`prove-commit`_](../storagext-cli/storage-provider.md#prove-commit)
+
+### `submit_windowed_post`
+
+A storage provider needs to periodically submit a [Proof-of-Spacetime](../glossary.md#proofs) to prove that they are still storing the data they promised. Multiple proofs can be submitted at once.
+
+| Name | Description | Type |
+| ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `deadline` | The deadline index which the submission targets | Positive integer |
+| `partitions` | The partitions being proven | Array of positive integers |
+| `post_proof` | The proof type, should be consistent with the proof type for registration | String, currently only `StackedDRGWindow2KiBV1P1` is available |
+| `proof_bytes` | The proof submission, to be checked in the storage provider pallet. | Hex string of the proof bytes |
+
+#### Example
+
+Storage provider `//Alice` submitting[^submit_windowed_post] proof for deadline 0, partition 0.
+
+```bash
+storagext-cli --sr25519-key "//Alice" storage-provider submit-windowed-post @submit-windowed-post.json
+```
+
+Where `submit-windowed-post.json` is a file with contents similar to:
+
+```json
+{
+ "deadline": 0,
+ "partition": [0],
+ "proof": {
+ "post_proof": "2KiB",
+ "proof_bytes": "1230deadbeef"
+ }
+}
+```
+
+[^submit_windowed_post]: Read more about the `submit-windowed-post` command in [_Storagext CLI/Subcommand `storage-provider`/`submit-windowed-post`_](../storagext-cli/storage-provider.md#submit-windowed-post)
+
+### `declare_faults`
+
+A storage provider can declare faults when they know they cannot submit PoSt on time to prevent getting penalized.
+Faults have an expiry of 42 days.
+The sectors will be terminated if the faults have not been recovered before this time.
+Multiple faults can be declared at once.
+
+`declare_faults` can take in multiple fault declarations:
+
+| Name | Description | Type |
+| -------- | ---------------------- | ------------------------------------------------ |
+| `faults` | The fault declarations | Array of the fault declarations, described below |
+
+Where the fault declarations contain:
+
+| Name | Description | Type |
+| ----------- | ------------------------------------------------------------------ | ------------------------ |
+| `deadline` | The deadline to which the faulty sectors are assigned | Positive integer |
+| `partition` | Partition index within the deadline containing the faulty sectors. | Positive integer |
+| `sectors` | Sectors in the partition being declared faulty | Set of positive integers |
+
+#### Example
+
+Storage provider `//Alice` declaring faults[^declare_faults] on deadline 0, partition 0, sector 1.
+
+```bash
+storagext-cli --sr25519-key "//Alice" storage-provider declare-faults @fault-declaration.json
+```
+
+Where `fault-declaration.json` is a file with contents similar to:
+
+```json
+[
+ {
+ "deadline": 0,
+ "partition": 0,
+ "sectors": [1]
+ }
+]
+```
+
+[^declare_faults]: Read more about the `declare-faults` command in [_Storagext CLI/Subcommand `storage-provider`/`declare-faults`_](../storagext-cli/storage-provider.md#declare-faults)
+
+### `declare_faults_recovered`
+
+After declaring sectors as faulty, a storage provider can recover them.
+The storage provider must recover the faults if the system has marked some sectors as faulty due to a missing PoSt.
+Faults are not fully recovered until the storage provider submits a valid PoSt after the `declare_faults_recovered` extrinsic.
+
+`declare_faults_recovered` can take in multiple fault recoveries:
+
+| Name | Description | Type |
+| ------------ | -------------------- | --------------------------------------------------------- |
+| `recoveries` | The fault recoveries | Array of the fault recovery declarations, described below |
+
+Where the fault recoveries contain:
+
+| Name | Description | Type |
+| ----------- | -------------------------------------------------------------------- | ------------------------ |
+| `deadline` | The deadline to which the recovered sectors are assigned | Positive integer |
+| `partition` | Partition index within the deadline containing the recovered sectors | Positive integer |
+| `sectors` | Sectors in the partition being declared recovered | Set of positive integers |
+
+#### Example
+
+Storage provider `//Alice` declaring recoveries[^declare_faults_recovered] on deadline 0, partition 0, sector 1.
+
+```bash
+storagext-cli --sr25519-key "//Alice" storage-provider declare-faults-recovered @fault-declaration.json
+```
+
+Where `fault-declaration.json` is a file with contents similar to:
+
+```json
+[
+ {
+ "deadline": 0,
+ "partition": 0,
+ "sectors": [1]
+ }
+]
+```
+
+[^declare_faults_recovered]: Read more about the `declare-faults-recovered` command in [_Storagext CLI/Subcommand `storage-provider`/`declare-faults-recovered`_](../storagext-cli/storage-provider.md#declare-faults-recovered)
+
+## Events
+
+The Storage Provider Pallet emits the following events:
+
+- `StorageProviderRegistered` - Indicates that a new storage provider has been registered.
+ - `owner` - SS58 address of the storage provider.
+ - `info` - The static information about the new storage provider. This information includes:
+ - `peer_id` - Libp2p identity that should be used when connecting to the storage provider.
+ - `window_post_proof_type` - The proof type used by the storage provider for sealing sectors.
+ - `sector_size` - Amount of space in each sector committed to the network by the storage provider.
+ - `window_post_partition_sectors` - The number of sectors in each Window PoSt partition (proof).
+- `SectorPreCommitted` - A storage provider has pre-committed some new sector after publishing some new deal.
+ - `owner` - SS58 address of the storage provider.
+ - `sector` - The sector number being pre-committed.
+- `SectorProven` - A storage provider has proven a sector that they previously pre-committed.
+ - `owner` - SS58 address of the storage provider.
+ - `sector_number` - The sector number that was proven.
+- `SectorSlashed` - A previously pre-committed sector, but not proven, has been slashed by the system because it has expired.
+ - `owner` - SS58 address of the storage provider.
+ - `sector_number` - The sector number that has been slashed because of expiry.
+- `ValidPoStSubmitted` - A valid PoSt has been submitted by a storage provider.
+ - `owner` - SS58 address of the storage provider.
+- `FaultsDeclared` - A storage provider has declared some sectors as faulty.
+ - `owner` - SS58 address of the storage provider.
+ - `faults` - An array with information about the fault declarations. This information includes:
+ - `deadline` - The deadline to which the faulty sectors are assigned.
+ - `partition` - Partition number within the deadline containing the faulty sectors.
+ - `sectors` - Sectors in the partition being declared as faulty.
+- `FaultsRecovered` - A storage provider has recovered some sectors previously declared as faulty.
+ - `owner` - SS58 address of the storage provider.
+ - `recoveries` - An array with information about the fault recoveries. This information includes:
+ - `deadline` - The deadline to which the recovered sectors are assigned.
+ - `partition` - Partition number within the deadline containing the recovered sectors.
+ - `sectors` - Sectors in the partition being declared as recovered.
+- `PartitionFaulty` - It was detected that a storage provider has not submitted their PoSt on time and has marked some sectors as faulty.
+ - `owner` - SS58 address of the storage provider.
+ - `partition` - Partition number for which the PoSt was missed.
+ - `sectors` - The sectors in the partition declared faulty by the system.
+
+## Errors
+
+The Storage Provider Pallet actions can fail with the following errors:
+
+- `StorageProviderExists` - A storage provider is already registered and tries to register again.
+- `StorageProviderNotFound` - This error is emitted by all extrinsics except registration in the storage provider pallet when a storage provider tries to call an extrinsic without registering first.
+- `InvalidSector` - This error can be emitted when:
+ - A storage provider supplies a sector number during pre-commit exceeding the maximum number of sectors.
+ - A storage provider supplies a sector number during proof commit that exceeds the maximum amount of sectors.
+- `InvalidProofType` - This error can be emitted when:
+ - A storage provider submits a seal-proof type during pre-commit that is different than the one configured during registration.
+ - During a prove commit extrinsic, the proof type supplied by the storage provider is invalid.
+ - A storage provider submits a windowed PoSt proof type that is different from the one configured during registration.
+- `NotEnoughFunds` - Emitted when a storage provider does not have enough funds for the pre-commit deposit.
+- `SectorNumberAlreadyUsed` - A storage provider tries to pre-commit a sector number that has already been used.
+- `ExpirationBeforeActivation` - A storage provider tries to pre-commit a sector where that sector expires before activation.
+- `ExpirationTooSoon` - A storage provider tries to pre-commit a sector with a total lifetime less than MinSectorExpiration.
+- `ExpirationTooLong` - A storage provider tries to pre-commit a sector with an expiration that exceeds `MaxSectorExpirationExtension`.
+- `MaxSectorLifetimeExceeded` - A storage provider tries to pre-commit a sector with a total lifetime that exceeds `SectorMaximumLifetime`.
+- `InvalidCid` - Emitted when a storage provider submits an invalid unsealed CID when trying to pre-commit a sector.
+- `ProveCommitAfterDeadline` - A storage provider has tried to prove a previously pre-committed sector after the proving deadline.
+- `PoStProofInvalid` - A proof that the storage provider submitted is invalid. Currently, this error is emitted when the proof length is 0.
+- `InvalidUnsealedCidForSector` - This error is emitted when the declared unsealed_cid for pre_commit is different from the one calculated by the system.
+- `FaultDeclarationTooLate` - A fault declaration was submitted after the fault declaration cutoff. The fault declaration can be submitted after the upcoming deadline is closed.
+- `FaultRecoveryTooLate` - A fault recovery was submitted after the fault recovery cutoff. The fault recovery can be submitted after the upcoming deadline is closed.
+- `DeadlineError` - An error was encountered in the deadline module. If you encounter this error, please report an issue, as this is a programmer error.
+- `PartitionError` - An error was encountered in the partition module. If you encounter this error, please report an issue, as this is a programmer error.
+- `StorageProviderError` - An error was encountered in the storage provider module. If you encounter this error, please report an issue, as this is a programmer error.
+- `SectorMapError` - An error was encountered in the sector map module. These errors can be:
+ - `FailedToInsertSector` - Internal bounds violation with Sectors. If you encounter this error please report an issue as this is a programmer error.
+ - `FailedToInsertPartition` - Internal bounds violation with partitions. If you encounter this error please report an issue as this is a programmer error.
+- `CouldNotActivateSector` - Failure during prove commit when trying to convert a previously pre-committed sector due to a programming error. Please report an issue if you receive this error.
+- `CouldNotVerifySectorForPreCommit` - Failure during pre-commit due to the [commd](../glossary.md#commitment-of-data) calculation failing due to a programming error. Please report an issue if you receive this error.
+- `SlashingFailed` - Slashing of funds fails due to a programmer error. Please report an issue if you receive this error.
+- `ConversionError` - Due to a programmer error. Please report an issue if you receive this error.
+
+## Pallet constants
+
+The Storage Provider Pallet has the following constants:
+
+| Name | Description | Value |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `WPoStProvingPeriod` | The average [period](../glossary.md#proving-period) for proving all sectors maintained by a storage provider. | 4 Minutes |
+| `WPoStChallengeWindow` | The period immediately before a deadline during which a challenge can be generated by the chain and the requisite proofs computed. | 2 Minutes |
+| `WPoStChallengeLookBack` | This period allows the storage providers to start working on the [PoSt](../glossary.md#post) before the deadline is officially opened to receiving a [PoSt](../glossary.md#post). | 1 Minute |
+| `WPoStPeriodDeadlines` | Represents how many challenge deadlines there are in one proving period. Closely tied to `WPoStChallengeWindow`. | 48 |
+| `MinSectorExpiration` | Minimum time past the current block a sector may be set to expire. | 5 Minutes |
+| `MaxSectorExpirationExtension` | Maximum time past the current block a sector may be set to expire. | 60 Minutes |
+| `SectorMaximumLifetime` | Maximum time a sector can stay in pre-committed state. | 120 Minutes |
+| `MaxProveCommitDuration` | Maximum time between [pre-commit](#pre_commit_sector) and [proving](#prove_commit_sector) the committed sector. | 5 Minutes |
+| `MaxPartitionsPerDeadline` | Maximum number of partitions that can be assigned to a single deadline. | 3000 |
+| `FaultMaxAge` | Maximum time a [fault](../glossary.md#fault) can exist before being removed by the pallet. | 210 Minutes |
+| FaultDeclarationCutoff | Time before a deadline opens that a storage provider can declare or recover a fault. | 2 Minutes |
diff --git a/src/storage-provider-cli/index.md b/src/storage-provider-cli/index.md
new file mode 100644
index 0000000..e73e978
--- /dev/null
+++ b/src/storage-provider-cli/index.md
@@ -0,0 +1,16 @@
+# Polka Storage Provider
+
+The Polka Storage Provider CLI provides two commands — `wallet` and `storage`.
+
+## `storage`
+
+The `storage` command launches a server that converts arbitrary files into CARv2 files
+— it does so using our CARv2 Rust library (the first Rust CARv2 implementation).
+
+You can read more about it on the [`storage`](./storage.md) page.
+
+## `wallet`
+
+The `wallet` command is a thin wrapper over the [`subkey`](https://docs.substrate.io/reference/command-line-tools/subkey/) utility provided by Polkadot.
+
+You can read more about it on the [`wallet`](./wallet.md) page.
diff --git a/src/storage-provider-cli/storage.md b/src/storage-provider-cli/storage.md
new file mode 100644
index 0000000..05d1b49
--- /dev/null
+++ b/src/storage-provider-cli/storage.md
@@ -0,0 +1,56 @@
+# The `storage` command
+
+The `storage` command launches a server that can convert files into CAR files.
+It has two parameters that you can customize:
+
+| Parameter | Description | Default value |
+| ---------------------- | ------------------------------------------------------- | ---------------- |
+| `--listen-addr
+Keys shown on this page are, by default, not secure! Do not use them in production!
+
+
+Generate a new random key to interact with the Polka Storage parachain:
+
+```bash
+> polka-storage-provider wallet generate
+Secret phrase: offer payment boost boy manage car asset lock cousin mountain vehicle setup
+ Network ID: substrate
+ Secret seed: 0xfe36ee692552b0ce54de06ce4f5cc152fe2fa808cb40f58c81168bc1237208bb
+ Public key (hex): 0x3ae6bdc05a6657cea011084d32b9970891be5d02b2101bbad0ca95d287f0226e
+ Account ID: 0x3ae6bdc05a6657cea011084d32b9970891be5d02b2101bbad0ca95d287f0226e
+ Public key (SS58): 5DPwBLBRGunws9T2aF59cht37HeBg9aSTAc6Fh2aFBJPSsr6
+ SS58 Address: 5DPwBLBRGunws9T2aF59cht37HeBg9aSTAc6Fh2aFBJPSsr6
+```
+
+If you want to add parameters like a password, you may do so using the `--password-interactive` flag:
+
+```bash
+> polka-storage-provider wallet generate --password-interactive
+Key password:
+If you haven't done so before, you should read the
+
+## `add-balance`
+
+The `add-balance` command allows you to add balance to your market account.
+It takes a single `AMOUNT` argument, the balance, to add to the market account,
+and the balance will be added to the `free` balance.
+
+### Parameters
+
+| Name | Description | Type |
+| -------- | -------------------------------------------- | ---------------- |
+| `AMOUNT` | The amount to be added to the market balance | Positive integer |
+
+### Example
+
+Adding 1000000000 [Plancks](../glossary.md#planck) to Alice's account.
+
+```bash
+storagext-cli --sr25519-key "//Alice" market add-balance 1000000000
+```
+
+storagext-cli getting started page,
+which covers the basic flags necessary to operate the CLI.
+
+The
+
+> You can read more about the `add_balance` extrinsic in [_Pallets/Market Pallet/Add Balance_](../pallets/market.md#add_balance).
+
+## `withdraw-balance`
+
+The `withdraw-balance` command allows you to withdraw balance from your market account.
+Like [`add-balance`](#add-balance), `withdraw-balance` takes a single `AMOUNT` argument;
+note that _only the `free` balance can be withdrawn_.
+Likewise, you can only withdraw a balance amount lesser than or equal to the `free` amount and greater than 0 (\\({free} \ge {amount} \gt 0\\)).
+
+### Parameters
+
+| Name | Description | Type |
+| -------- | ------------------------------------------------ | ---------------- |
+| `AMOUNT` | The amount to be withdrawn to the market balance | Positive integer |
+
+### Example
+
+Withdrawing 10000 [Plancks](../glossary.md#planck) from Alice's account.
+
+```bash
+storagext-cli --sr25519-key "//Alice" market withdraw-balance 10000
+```
+
+> You can read more about the `withdraw_balance` extrinsic in [_Pallets/Market Pallet/Withdraw Balance_](../pallets/market.md#withdraw-balance).
+
+## `publish-storage-deals`
+
+The `publish-storage-deals` command allows you to publish storage deals that have been agreed upon off-chain.
+The deals are to be submitted by the storage provider, having been previously signed by the client.
+
+1000000000 value is not arbitrary, it is the minimum existential deposit for any Polkadot account. As such, when the Market account is being setup, the first deposit ever needs to meet this minimum to create the Market account.
+
+If you attempt to create the Market account with less than 1000000000, you will get the following error:
+
+
+Error: Runtime error: Token error: Account cannot exist with the funds that would be given.
+
+
+Since this CLI is currently targeted at testing and demos, the client keypair is required to sign the deal.
+We know this is not secure and unrealistic in a production scenario (it is a good thing this is a demo)!
+
+
+### Parameters
+
+The client keypair can be passed using `--client-
+If you haven't done so, you should read the
+
+### `register`
+
+The `register` command allows you to register as a storage provider. Before you can start providing storage, you need to register to be able to deal with the clients and perform any storage provider duties.
+
+### Parameters
+
+| Name | Description | Type |
+| ------------ | -------------------------------------------------------------------------- | ------ |
+| `PEER_ID` | The peer ID under which the registered provider will be tracked | String |
+| `POST_PROOF` | The proof type that the provider will use to prove storage (Default: 2KiB) | String |
+
+### Example
+
+Registering the provider with the specific `peer_id`
+
+```bash
+storagext-cli --sr25519-key storagext-cli getting started page,
+which covers the basic flags necessary to operate the CLI.
+
+If you haven't done so before, you should read the
+
+## `get-height`
+
+The command allows you to get the current block height of the chain.
+
+### Example
+
+Getting the current block height of the chain.
+
+```bash
+storagext-cli system get-height
+```
+
+## `wait-for-height`
+
+The command allows you to wait for the chain to reach a specific block height. It will exit once the chain has reached the specified height.
+
+### Parameters
+
+| Name | Description | Type |
+| -------- | ---------------------------- | ---------------- |
+| `HEIGHT` | The block height to wait for | Positive integer |
+
+### Example
+
+Waiting for the chain to reach block height 100.
+
+```bash
+storagext-cli system wait-for-height 100
+```
storagext-cli getting started page,
+which covers the basic flags necessary to operate the CLI.
+