Update mithril-client library developer doc

docs/website/root/manual/developer-docs/nodes/mithril-client-library.md

@@ -11,6 +11,11 @@ import CompiledBinaries from '../../../compiled-binaries.md'
 
 Mithril Client Library can be used by Rust developers to use the Mithril Network in their applications.
 
+It handles the different types that can be queried to a mithril aggregator:
+- [**Snapshot**](../../../glossary.md#snapshot): list, get and download tarball.
+- [**Mithril stake distribution**](../../../glossary#stake-distribution): list and get.
+- [**Certificate**](../../../glossary#certificate): list, get, and chain validation.
+
 :::
 
 :::tip
@@ -31,15 +36,9 @@ Mithril Client Library can be used by Rust developers to use the Mithril Network
 
 ## Resources
 
-| Node | Source repository | Rust documentation | Docker packages |
-|:-:|:-----------------:|:------------------:|:---------------:|
-**Mithril client** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client-cli) | [:arrow_upper_right:](https://mithril.network/mithril-client/doc/mithril_client/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
-
-## Resources
-
-| Node | Source repository | Rust documentation | Docker packages |
-|:-:|:-----------------:|:------------------:|:---------------:|
-**Mithril client** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client-cli) | [:arrow_upper_right:](https://mithril.network/mithril-client/doc/mithril_client/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
+| Node | Source repository | Rust documentation |
+|:-:|:-----------------:|:------------------:|
+**Mithril client** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client) | [:arrow_upper_right:](https://mithril.network/mithril-client/doc/mithril_client/index.html) |
 
 ## Pre-requisites
 
@@ -49,56 +48,100 @@ Mithril Client Library can be used by Rust developers to use the Mithril Network
 
 ## Installation
 
-In your project crate, use `cargo` to add [mithril-client](https://crates.io/crates/mithril-client) as a dependency:
+:::caution
+
+Mithril Client library has not yet been published on [crates.io](https://crates.io/), so you won't be able to follow the procedure below. The crate will be published soon.
+
+:::
+
+In your project, use `cargo` to add [mithril_client](https://crates.io/crates/mithril_client) crate as a dependency:
 
 ```bash
-cargo add mithril-client
+cargo add mithril_client
 ```
 
 It will add the latest version of the Mithril client library.
 
-Mithril client is an asynchronous library. It has been tested with the crate [tokio](https://crates.io/crates/tokio), In the Cargo.toml of your project, add the following dependency:
-
-```toml
-tokio = { version = "1.32.0", features = ["full"] }
-``````
+Mithril client is an asynchronous library, you will need a runtime to execute drive your futures. We recommand to use the crate [tokio](https://crates.io/crates/tokio), as the library has been tested with it.
 
 ## Using Mithril Client Library
 
-If the goal is just to use the existing certificates, it is easier to use the `Client` structure:
+Below is a basic example of how to use most of the functions exposed by the Mithril Client library:
 
-```rust
-use mithril_client_cli::client::Client;
-use mithril_client_cli::common::*;
+```rust title="/src/main.rs"
+use mithril_client::{ClientBuilder, MessageBuilder};
+use std::path::Path;
 
 #[tokio::main]
-async fn main() -> StdResult<()> {
-    let client = Client::new("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").await?;
-    let response = client.list_mithril_stake_distributions().await?;
-
-    for mithril_stake_distribution in response {
-        println!("Stake distribution hash = '{}'.", mithril_stake_distribution.hash);
-    }
-
+async fn main() -> mithril_client::MithrilResult<()> {
+    let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
+
+    let snapshots = client.snapshot().list().await?;
+
+    let last_digest = snapshots.first().unwrap().digest.as_ref();
+    let snapshot = client.snapshot().get(last_digest).await?.unwrap();
+
+    let certificate = client
+        .certificate()
+        .verify_chain(&snapshot.certificate_hash)
+        .await?;
+
+    // Note: the directory must already exist, and the user running this code must have read/write access to it.
+    let target_directory = Path::new("YOUR_TARGET_DIRECTORY");
+    client
+        .snapshot()
+        .download_unpack(&snapshot, target_directory)
+        .await?;
+
+    let message = MessageBuilder::new()
+        .compute_snapshot_message(&certificate, target_directory)
+        .await?;
+    assert!(certificate.match_message(&message));
+
     Ok(())
 }
 ```
 
-Here is an example of the code for the release-preprod network:
+:::info
 
-```rust
-use mithril_client_cli::client::Client;
-use mithril_client_cli::common::*;
+Snapshot download and Certificate chain validation can take quite some time even with a fast computer and network. For those a feedback mechanism is available, more details on it in the [feedback submodule](https://mithril.network/rust-doc/mithril_client/feedback/index.html).
 
-#[tokio::main]
-async fn main() -> StdResult<()> {
-    let client = Client::new("https://aggregator.release-mainnet.api.mithril.network/aggregator", "5b3132372c37332c3132342c3136312c362c3133372c3133312c3231332c3230372c3131372c3139382c38352c3137362c3139392c3136322c3234312c36382c3132332c3131392c3134352c31332c3233322c3234332c34392c3232392c322c3234392c3230352c3230352c33392c3233352c34345d").await?;
-    let response = client.list_mithril_stake_distributions().await?;
+An example of implementation with the crate [indicatif](https://crates.io/crates/indicatif) is available in the [Mithril repository](https://github.com/input-output-hk/mithril/tree/main/mithril-client/examples/snapshot_list_get_show_download_verify.rs).
 
-    for mithril_stake_distribution in response {
-        println!("Stake distribution hash = '{}'.", mithril_stake_distribution.hash);
-    }
+:::
 
+Here is an example of the code for the release-preprod network:
+
+```rust title="/src/main.rs"
+use mithril_client::{ClientBuilder, MessageBuilder};
+use std::path::Path;
+
+#[tokio::main]
+async fn main() -> mithril_client::MithrilResult<()> {
+    let client = ClientBuilder::aggregator("https://aggregator.release-preprod.api.mithril.network/aggregator", "5b3132372c37332c3132342c3136312c362c3133372c3133312c3231332c3230372c3131372c3139382c38352c3137362c3139392c3136322c3234312c36382c3132332c3131392c3134352c31332c3233322c3234332c34392c3232392c322c3234392c3230352c3230352c33392c3233352c34345d").build()?;
+
+    let snapshots = client.snapshot().list().await?;
+
+    let last_digest = snapshots.first().unwrap().digest.as_ref();
+    let snapshot = client.snapshot().get(last_digest).await?.unwrap();
+
+    let certificate = client
+        .certificate()
+        .verify_chain(&snapshot.certificate_hash)
+        .await?;
+
+    // Note: the directory must already exist, and the user running this code must have read/write access to it.
+    let target_directory = Path::new(".");
+    client
+        .snapshot()
+        .download_unpack(&snapshot, target_directory)
+        .await?;
+
+    let message = MessageBuilder::new()
+        .compute_snapshot_message(&certificate, target_directory)
+        .await?;
+    assert!(certificate.match_message(&message));
+
     Ok(())
 }
 ```