Chore/combine examples (#420)

* Merged Stronghold with basic examples in account

* Updated explorer to identity resolver

* Added explorer URL after basic example

* Renamed examples

* Completed manipulate did example

* Fixed suggestions, removed replaced examples.

* Improved example readme

* Consistently use Stronghold and Resolver URL

* Fix examples

* Merged config example with private tangle

* low-level-api private-network example runs

* cargo fmt

* cargo fmt with nightly

* Impl suggestions

.gitignore

@@ -23,4 +23,7 @@ book
 # ignore index.html
 index.html
 
+# ignore files generated by example
+*.hodl
+
 !/bindings/wasm/static/index.html

examples/Cargo.toml

@@ -15,37 +15,25 @@ name = "getting_started"
 path = "getting_started.rs"
 
 [[example]]
-name = "account_basic"
-path = "account/basic.rs"
+name = "account_create"
+path = "account/create_did.rs"
 
 [[example]]
 name = "account_config"
 path = "account/config.rs"
 
 [[example]]
-name = "account_methods"
-path = "account/methods.rs"
+name = "account_manipulate"
+path = "account/manipulate_did.rs"
 
 [[example]]
 name = "account_lazy"
 path = "account/lazy.rs"
 
-[[example]]
-name = "account_services"
-path = "account/services.rs"
-
 [[example]]
 name = "account_signing"
 path = "account/signing.rs"
 
-[[example]]
-name = "account_stronghold"
-path = "account/stronghold.rs"
-
-[[example]]
-name = "account_private_tangle"
-path = "account/private_tangle.rs"
-
 [[example]]
 name = "create_did"
 path = "low-level-api/create_did.rs"

examples/README.md

@@ -18,28 +18,27 @@ For Instance, to run the example `getting_started`, use
 cargo run --example getting_started
 ```
 
-The following examples are available for using the basic account (A high level API):
+The following examples are available for using the basic account (A high-level API):
 
 | # | Name | Information |
 | :--: | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
 | 1 | [getting_started](./getting_started.rs) | Introductory example for you to test whether the library is set up / working properly and compiles.                        |
-| 2 | [account_basic](./account/basic.rs) | A basic example that generates and publishes a DID Document, the fundamental building block for decentralized identity.    |
-| 3 | [account_config](./account/config.rs) | This example goes into more detail regarding the usage of DID Documents. |
-| 4 | [account_methods](./account/methods.rs) | A basic example that generates and publishes subject and issuer DID Documents, then creates a Verifiable Credential (vc) specifying claims about the subject, and retrieves information through the CredentialValidator API. |
-| 5 | [account_services](./account/services.rs) | This example explains how to create a Verifiable Presentation from a set of credentials and sign it. |
-| 6 | [account_signing](./account/signing.rs) | A basic example that generates a DID Document, publishes it to the Tangle, and retrieves information through DID Document resolution/dereferencing. |
-| 7 | [account_stronghold](./account/stronghold.rs) | An example that utilizes a diff and integration chain to publish updates to a DID Document. |
+| 2 | [account_create_did](./account/create_did.rs) | A basic example that generates and publishes a DID Document, the fundamental building block for decentralized identity.    |
+| 3 | [account_config](./account/config.rs) | How to configure the account to work with different networks and other settings. |
+| 4 | [account_manipulate](./account/manipulate_did.rs) | How to manipulate a DID Document by adding/removing Verification Methods and Services. |
+| 5 | [account_lazy](./account/lazy.rs) | How to take control over publishing DID updates manually, instead of the default automated behavior. |
+| 6 | [account_signing](./account/signing.rs) | Using a DID to sign arbitrary statements and validating them. |
 
 
 The following examples are available for using the low-level APIs, which provides more flexibility at the cost of complexity:
 
 | # | Name | Information |
 | :--: | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
 | 1 | [create_did](./low-level-api/create_did.rs) | A basic example that generates and publishes a DID Document, the fundamental building block for decentralized identity. |
-| 2 | [manipulate_did](low-level-api/manipulate_did.rs) | This example demonstrates how to perform a basic update to integration chain of a DID Document. |
+| 2 | [manipulate_did](low-level-api/manipulate_did.rs) | This example demonstrates how to perform a basic update to the integration chain of a DID Document. |
 | 3 | [diff_chain](low-level-api/diff_chain.rs) | This example demonstrates how to perform a basic update to the diff chain of a DID Document. |
 | 4 | [resolve_history](low-level-api/resolve_history.rs) | Advanced example that performs multiple diff chain and integration chain updates and demonstrates how to resolve the DID Document history to view these chains. |
-| 5 | [create_vc](./low-level-api/create_vc.rs) | Generates and publishes subject and issuer DID Documents, then creates a Verifiable Credential (vc) specifying claims about the subject, and retrieves information through the CredentialValidator API. |
+| 5 | [create_vc](./low-level-api/create_vc.rs) | Generates and publishes subject and issuer DID Documents, then creates a Verifiable Credential (VC) specifying claims about the subject, and retrieves information through the CredentialValidator API. |
 | 6 | [create_vp](./low-level-api/create_vp.rs) | This example explains how to create a Verifiable Presentation from a set of credentials and sign it. |
 | 7 | [resolution](./low-level-api/resolution.rs) | A basic example that shows how to retrieve information through DID Document resolution/dereferencing. |
 | 8 | [revoke_vc](./low-level-api/revoke_vc.rs) | A basic example that shows how to retrieve information through DID Document resolution/dereferencing. |

examples/account/config.rs

@@ -6,13 +6,26 @@
 use identity::account::Account;
 use identity::account::AccountStorage;
 use identity::account::AutoSave;
+use identity::account::IdentityCreate;
+use identity::account::IdentityState;
 use identity::account::Result;
+use identity::iota::IotaDID;
 use identity::iota::Network;
 
 #[tokio::main]
 async fn main() -> Result<()> {
   pretty_env_logger::init();
 
+  // Set-up for private Tangle
+  // You can use https://github.com/iotaledger/one-click-tangle for a local setup.
+  // The `network_name` needs to match the id of the network or a part of it.
+  // As an example we are treating the devnet as a `private-tangle`, so we use `dev`.
+  // Replace this with `tangle` if you run this against a one-click private tangle.
+  let network_name = "dev";
+  let network = Network::try_from_name(network_name)?;
+  // In a locally running one-click tangle, this would often be `http://127.0.0.1:14265/`
+  let private_node_url = "https://api.lb-0.h.chrysalis-devnet.iota.cafe";
+
   // Create a new Account with explicit configuration
   let account: Account = Account::builder()
     .autosave(AutoSave::Never) // never auto-save. rely on the drop save
@@ -21,18 +34,46 @@ async fn main() -> Result<()> {
     .dropsave(false) // save the account state on drop
     .milestone(4) // save a snapshot every 4 actions
     .storage(AccountStorage::Memory) // use the default in-memory storage adapter
-    // configure the mainnet Tangle client
+    // configure a mainnet Tangle client with node and permanode
     .client(Network::Mainnet, |builder| {
       builder
+        // Manipulate this in order to manually appoint nodes
         .node("https://chrysalis-nodes.iota.org")
         .unwrap() // unwrap is safe, we provided a valid node URL
+        // Set a permanode from the same network (Important)
         .permanode("https://chrysalis-chronicle.iota.org/api/mainnet/", None, None)
         .unwrap() // unwrap is safe, we provided a valid permanode URL
     })
+    // Configure a client for the private network, here `dev`
+    // Also set the URL that points to the REST API of the node
+    .client(network, |builder| {
+      // unwrap is safe, we provided a valid node URL
+      builder.node(private_node_url).unwrap()
+    })
     .build()
     .await?;
 
-  println!("[Example] Account = {:#?}", account);
+  // Create an Identity specifically on the devnet by passing `network_name`
+  // The same applies if we wanted to create an identity on a private tangle
+  let id_create = IdentityCreate::new().network(network_name)?;
+
+  // Create a new Identity with the network name set.
+  let identity: IdentityState = match account.create_identity(id_create).await {
+    Ok(identity) => identity,
+    Err(err) => {
+      eprintln!("[Example] Error: {:?} {}", err, err.to_string());
+      eprintln!("[Example] Is your Tangle node listening on {}?", private_node_url);
+      return Ok(());
+    }
+  };
+  let iota_did: &IotaDID = identity.try_did()?;
+
+  // Prints the Identity Resolver Explorer URL, the entire history can be observed on this page by "Loading History".
+  println!(
+    "[Example] Explore the DID Document = {}/{}",
+    iota_did.network()?.explorer_url().unwrap().to_string(),
+    iota_did.to_string()
+  );
 
   Ok(())
 }

examples/account/create_did.rs

@@ -0,0 +1,52 @@
+// Copyright 2020-2021 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+//! cargo run --example account_create
+
+use std::path::PathBuf;
+
+use identity::account::Account;
+use identity::account::AccountStorage;
+use identity::account::IdentityCreate;
+use identity::account::IdentityState;
+use identity::account::Result;
+use identity::iota::IotaDID;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+  pretty_env_logger::init();
+
+  // Sets the location and password for the Stronghold
+  //
+  // Stronghold is an encrypted file that manages private keys.
+  // It implements best practices for security and is the recommended way of handling private keys.
+  let stronghold_path: PathBuf = "./example-strong.hodl".into();
+  let password: String = "my-password".into();
+
+  // Create a new Account with the default configuration
+  let account: Account = Account::builder()
+    .storage(AccountStorage::Stronghold(stronghold_path, Some(password)))
+    .build()
+    .await?;
+
+  // Create a new Identity with default settings
+  //
+  // This step generates a keypair, creates an identity and publishes it to the IOTA mainnet.
+  let identity: IdentityState = account.create_identity(IdentityCreate::default()).await?;
+  let iota_did: &IotaDID = identity.try_did()?;
+
+  // Print the local state of the DID Document
+  println!(
+    "[Example] Local Document from {} = {:#?}",
+    iota_did,
+    identity.to_document()
+  );
+
+  // Prints the Identity Resolver Explorer URL, the entire history can be observed on this page by "Loading History".
+  println!(
+    "[Example] Explore the DID Document = {}/{}",
+    iota_did.network()?.explorer_url().unwrap().to_string(),
+    iota_did.to_string()
+  );
+  Ok(())
+}

examples/account/lazy.rs

@@ -2,8 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0
 
 //! cargo run --example account_lazy
+use std::path::PathBuf;
 
 use identity::account::Account;
+use identity::account::AccountStorage;
 use identity::account::IdentityCreate;
 use identity::account::IdentityState;
 use identity::account::Result;
@@ -14,20 +16,28 @@ use identity::iota::IotaDID;
 async fn main() -> Result<()> {
   pretty_env_logger::init();
 
+  // Stronghold settings
+  let stronghold_path: PathBuf = "./example-strong.hodl".into();
+  let password: String = "my-password".into();
+
   // Create a new Account with auto publishing set to false.
   // This means updates are not pushed to the tangle automatically.
   // Rather, when we publish, multiple updates are batched together.
-  let account: Account = Account::builder().autopublish(false).build().await?;
+  let account: Account = Account::builder()
+    .storage(AccountStorage::Stronghold(stronghold_path, Some(password)))
+    .autopublish(false)
+    .build()
+    .await?;
 
   // Create a new Identity with default settings.
   // The identity will only be written to the local storage - not published to the tangle.
   let identity: IdentityState = account.create_identity(IdentityCreate::default()).await?;
 
   // Retrieve the DID from the newly created Identity state.
-  let did: &IotaDID = identity.try_did()?;
+  let iota_did: &IotaDID = identity.try_did()?;
 
   account
-    .update_identity(did)
+    .update_identity(iota_did)
     .create_service()
     .fragment("example-service")
     .type_("LinkedDomains")
@@ -37,11 +47,11 @@ async fn main() -> Result<()> {
 
   // Publish the newly created DID document,
   // including the new service, to the tangle.
-  account.publish_updates(did).await?;
+  account.publish_updates(iota_did).await?;
 
   // Add another service.
   account
-    .update_identity(did)
+    .update_identity(iota_did)
     .create_service()
     .fragment("another-service")
     .type_("LinkedDomains")
@@ -51,19 +61,21 @@ async fn main() -> Result<()> {
 
   // Delete the previously added service.
   account
-    .update_identity(did)
+    .update_identity(iota_did)
     .delete_service()
     .fragment("example-service")
     .apply()
     .await?;
 
   // Publish the updates as one message to the tangle.
-  account.publish_updates(did).await?;
-
-  // Resolve the document to confirm its consistency.
-  let doc = account.resolve_identity(did).await?;
+  account.publish_updates(iota_did).await?;
 
-  println!("[Example] Document: {:#?}", doc);
+  // Prints the Identity Resolver Explorer URL, the entire history can be observed on this page by "Loading History".
+  println!(
+    "[Example] Explore the DID Document = {}/{}",
+    iota_did.network()?.explorer_url().unwrap().to_string(),
+    iota_did.to_string()
+  );
 
   Ok(())
 }