docs: add docs for proofs commands (#587)

eigerco · Nov 18, 2024 · f91ecb7 · f91ecb7
1 parent 5468462
commit f91ecb7
Show file tree

Hide file tree

Showing 5 changed files with 167 additions and 15 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/cli/polka-storage-provider/client/Cargo.toml b/cli/polka-storage-provider/client/Cargo.toml
@@ -21,7 +21,6 @@ bls12_381 = { workspace = true }
 cid = { workspace = true, features = ["std"] }
 clap = { workspace = true, features = ["derive"] }
 codec = { workspace = true }
-hex = { workspace = true }
 jsonrpsee = { workspace = true, features = ["http-client", "macros", "server", "ws-client"] }
 sc-cli = { workspace = true }
 serde = { workspace = true }

diff --git a/cli/polka-storage-provider/client/src/commands/proofs.rs b/cli/polka-storage-provider/client/src/commands/proofs.rs
@@ -97,13 +97,13 @@ pub enum ProofsCommand {
         /// Path to where parameters to corresponding `post_type` are stored.
         #[arg(short, long)]
         proof_parameters_path: PathBuf,
-        /// Directory where cache data from `po-rep` for the `replica_path` sector command has been stored.
+        /// Directory where cache data from `porep` for the `replica_path` sector command has been stored.
         /// It must be the same, or else it won't work.
         #[arg(short, long)]
         cache_directory: PathBuf,
-        /// Replica file generated with `po-rep` command e.g. `77.sector.sealed`.
+        /// Replica file generated with `porep` command e.g. `77.sector.sealed`.
         replica_path: PathBuf,
-        /// Hex-encoded CommR of a replica (output of `po-rep` command)
+        /// CID - CommR of a replica (output of `porep` command)
         comm_r: String,
         #[arg(short, long)]
         /// Directory where the PoSt proof will be stored. Defaults to the current directory.
@@ -387,10 +387,14 @@ impl ProofsCommand {
                     POST_PROOF_EXT,
                 )?;
 
+                let comm_r =
+                    cid::Cid::from_str(&comm_r).map_err(|_| UtilsCommandError::CommRError)?;
+
                 let replicas = vec![ReplicaInfo {
                     sector_id,
-                    comm_r: hex::decode(comm_r)
-                        .map_err(|_| UtilsCommandError::CommRError)?
+                    comm_r: comm_r
+                        .hash()
+                        .digest()
                         .try_into()
                         .map_err(|_| UtilsCommandError::CommRError)?,
                     replica_path,

diff --git a/docs/src/storage-provider-cli/client/proofs.md b/docs/src/storage-provider-cli/client/proofs.md
@@ -5,11 +5,158 @@ The following subcommands are contained under `proofs`.
 > These are advanced commands and only useful for demo purposes.
 > This functionality is covered in the server by the [pipeline](../../architecture/polka-storage-provider-server.md#sealing-pipeline).
 
-| Name                         | Description                                                                                                                                 |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `calculate-piece-commitment` | Calculate a piece commitment for the provided data stored at the a given path                                                               |
-| `porep-params`               | Generates PoRep verifying key and proving parameters for zk-SNARK workflows (prove commit)                                                  |
-| `post-params`                | Generates PoSt verifying key and proving parameters for zk-SNARK workflows (submit windowed PoSt)                                           |
-| `porep`                      | Generates PoRep for a piece file. Takes a piece file (in a CARv2 archive, unpadded), puts it into a sector (temp file), seals and proves it |
-| `post`                       | Creates a PoSt for a single sector                                                                                                          |
+| Name           | Description                                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `commp`        | Calculate a piece commitment (CommP) for the provided data stored at the a given path.                                                      |
+| `porep-params` | Generates PoRep verifying key and proving parameters for zk-SNARK workflows (prove commit)                                                  |
+| `post-params`  | Generates PoSt verifying key and proving parameters for zk-SNARK workflows (submit windowed PoSt)                                           |
+| `porep`        | Generates PoRep for a piece file. Takes a piece file (in a CARv2 archive, unpadded), puts it into a sector (temp file), seals and proves it |
+| `post`         | Creates a PoSt for a single sector                                                                                                          |
 
+## `commp`
+
+Produces a CommP out of the CARv2 archive and calculates [piece_size](https://spec.filecoin.io/#section-systems.filecoin_files.piece.data-representation) that will be accepted by the network in a [deal](./index.md#propose-deal).
+If the file at the path is not a CARv2 archive, it fails.
+To create a CARv2 archive, you can use [`mater-cli convert`](../../mater-cli/index.md#convert) command.
+
+### Example
+
+```bash
+$ mater-cli convert polkadot.svg
+Converted polkadot.svg and saved the CARv2 file at polkadot.car with a CID of bafkreihoxd7eg2domoh2fxqae35t7ihbonyzcdzh5baevxzrzkaakevuvy
+$ polka-storage-provider-client proofs commp polkadot.car
+{
+    "cid": "baga6ea4seaqabpfwrqjcwrb4pxmo2d3dyrgj24kt4vqqqcbjoph4flpj2e5lyoq",
+    "size": 2048
+}
+```
+
+## `porep-params`
+
+Generates a [PoRep](../../glossary.md#proofs) parameters which consist of Proving Params (`*.porep.params` file) and Verifying Key (`*.porep.vk`, `*.porep.vk.scale`).
+Proving Parameters are used by the Storage Provider to generate a PoRep and the corresponding Verifying Key is used to [verify proofs on chain](../../architecture/pallets/proofs.md#set_porep_verifying_key) by pallet-proofs and [pallet-storage-provider](../../architecture/pallets/storage-provider.md#prove_commit_sectors).
+
+### Example
+
+```bash
+$ polka-storage-provider-client proofs porep-params
+Generating params for 2KiB sectors... It can take a couple of minutes ⌛
+Generated parameters:
+[...]/polka-storage/2KiB.porep.params
+[...]/polka-storage/2KiB.porep.vk
+[...]/polka-storage/2KiB.porep.vk.scale
+```
+
+## `post-params`
+
+Generates a [PoSt](../../glossary.md#proofs) parameters which consist of Proving Params (`*.post.params` file) and Verifying Key (`*.post.vk`, `*.post.vk.scale`).
+Proving Parameters are used by the Storage Provider to generate a PoSt and the corresponding Verifying Key is used to [verify proofs on chain](../../architecture/pallets/proofs.md#set_post_verifying_key) by pallet-proofs and [pallet-storage-provider](../../architecture/pallets/storage-provider.md#submit_windowed_post).
+
+### Example
+
+```bash
+$ polka-storage-provider-client proofs post-params
+Generating PoSt params for 2KiB sectors... It can take a few secs ⌛
+Generated parameters:
+[...]/polka-storage/2KiB.post.params
+[...]/polka-storage/2KiB.post.vk
+[...]/polka-storage/2KiB.post.vk.scale
+```
+
+## `porep`
+
+Generates a 2KiB sector-size PoRep proof for an input file and its piece commitment.
+Creates the sector containing only 1 piece, [seals it](https://spec.filecoin.io/#section-algorithms.pos.porep) by creating a replica and then creates a proof for it.
+
+> This is a *demo command*, showcasing the ability to generate a PoRep
+> given the proving parameters so it can later be used to verify proof on-chain.
+> It uses hardcoded values, which normally would be sourced from the chain i.e:
+>
+> ```rust
+> let sector_id = 77;
+> let ticket = [12u8; 32];
+> let seed = [13u8; 32];
+> ```
+
+```bash
+polka-storage-provider-client proofs porep \
+    --sr25519-key|--ecdsa-key|--ed25519-key <KEY> \
+    --cache-directory <CACHE_DIRECTORY> \
+    --proofs-parameters-path <PROVING_PARAMS_FILE> \
+    <INPUT_FILE> <INPUT_FILE_PIECE_CID>
+```
+
+### Example
+
+```bash
+$ mater-cli convert polkadot.svg
+Converted polkadot.svg and saved the CARv2 file at polkadot.car with a CID of bafkreihoxd7eg2domoh2fxqae35t7ihbonyzcdzh5baevxzrzkaakevuvy
+$ polka-storage-provider-client proofs commp polkadot.car
+{
+    "cid": "baga6ea4seaqabpfwrqjcwrb4pxmo2d3dyrgj24kt4vqqqcbjoph4flpj2e5lyoq",
+    "size": 2048
+}
+$ polka-storage-provider-client proofs porep-params
+Generating params for 2KiB sectors... It can take a couple of minutes ⌛
+Generated parameters:
+[...]/polka-storage/2KiB.porep.params
+[...]/polka-storage/2KiB.porep.vk
+[...]/polka-storage/2KiB.porep.vk.scale
+$ mkdir -p /tmp/psp-cache
+$ polka-storage-provider-client proofs porep --sr25519-key "//Alice" --cache-directory /tmp/psp-cache --proof-parameters-path 2KiB.porep.params polkadot.car baga6ea4seaqabpfwrqjcwrb4pxmo2d3dyrgj24kt4vqqqcbjoph4flpj2e5lyoq
+Creating sector...
+Precommitting...
+2024-11-18T10:48:29.858550Z  INFO filecoin_proofs::api::seal: seal_pre_commit_phase1:start: SectorId(77)
+2024-11-18T10:48:29.863782Z  INFO storage_proofs_porep::stacked::vanilla::proof: replicate_phase1
+2024-11-18T10:48:29.864120Z  INFO storage_proofs_porep::stacked::vanilla::graph: using parent_cache[64 / 64]
+[...]
+CommD: Cid(baga6ea4seaqabpfwrqjcwrb4pxmo2d3dyrgj24kt4vqqqcbjoph4flpj2e5lyoq)
+CommR: Cid(bagboea4b5abcb7rgo7kuqigb2wjybggbvlmmatmki52by3wov5uwjrjwefxwzxi5)
+Wrote proof to [...]/polka-storage/77.sector.proof.porep.scale
+```
+
+## `post`
+
+Generates a 2KiB sector-sized PoSt proof.
+To be able to create a PoSt proof, first you need to generate a PoRep proof and a replica via `porep` command.
+
+> This is a *demo command*, showcasing the ability to generate a PoSt,
+> given the proving parameters so it can later be used to verify proof on-chain.
+> It uses hardcoded values, which normally would be sourced from the chain i.e:
+>
+> ```rust
+> let sector_id = 77;
+> let randomness = [1u8; 32];
+> ```
+
+```bash
+polka-storage-provider-client proofs post
+  --sr25519-key|--ecdsa-key|--ed25519-key <KEY> \
+  --proof-parameters-path <PROOF_PARAMETERS_PATH> \
+  --cache-directory <CACHE_DIRECTORY> \
+  <REPLICA_PATH>
+  <COMM_R>
+```
+
+### Example
+
+```bash
+$ polka-storage-provider-client proofs post-params
+Generating PoSt params for 2KiB sectors... It can take a few secs ⌛
+Generated parameters:
+[...]/polka-storage/2KiB.post.params
+[...]/polka-storage/2KiB.post.vk
+[...]/polka-storage/2KiB.post.vk.scale
+$ polka-storage-provider-client proofs post --sr25519-key "//Alice" --cache-directory /tmp/psp-cache --proof-parameters-path 2KiB.post.params 77.sector.sealed bagboea4b5abcb7rgo7kuqigb2wjybggbvlmmatmki52by3wov5uwjrjwefxwzxi5
+Loading parameters...
+2024-11-18T11:20:26.718119Z  INFO storage_proofs_core::compound_proof: vanilla_proofs:start
+2024-11-18T11:20:26.750347Z  INFO storage_proofs_core::compound_proof: vanilla_proofs:finish
+2024-11-18T11:20:26.750712Z  INFO storage_proofs_core::compound_proof: snark_proof:start
+2024-11-18T11:20:26.750797Z  INFO bellperson::groth16::prover::native: Bellperson 0.26.0 is being used!
+2024-11-18T11:20:26.771368Z  INFO bellperson::groth16::prover::native: synthesis time: 20.550334ms
+2024-11-18T11:20:26.771385Z  INFO bellperson::groth16::prover::native: starting proof timer
+2024-11-18T11:20:26.772676Z  INFO bellperson::gpu::locks: GPU is available for FFT!
+2024-11-18T11:20:26.772687Z  INFO bellperson::gpu::locks: BELLPERSON_GPUS_PER_LOCK fallback to single lock mode
+Proving...
+Wrote proof to [...]/polka-storage/77.sector.proof.post.scale
+```
diff --git a/primitives/proofs/src/lib.rs b/primitives/proofs/src/lib.rs
@@ -18,5 +18,8 @@ where
     AccountId: Encode,
 {
     let encoded = account_id.encode();
-    sp_core::blake2_256(&encoded)
+    let mut encoded = sp_core::blake2_256(&encoded);
+    // Necessary to be valid bls12 381 element.
+    encoded[31] &= 0x3f;
+    encoded
 }