Docs/readme improvs (#257) (#258)

* Update main readme * WASM readme update * Updated example with account * Rust examples readme
iotaledger · May 10, 2021 · d3e38aa · d3e38aa
1 parent 34d480f
commit d3e38aa
Show file tree

Hide file tree

Showing 12 changed files with 104 additions and 90 deletions.
diff --git a/README.md b/README.md
@@ -28,13 +28,9 @@ IOTA Identity is a [Rust](https://www.rust-lang.org/) implementation of decentra
 
 The individual libraries are developed to be agnostic about the utilized [Distributed Ledger Technology (DLT)](https://en.wikipedia.org/wiki/Distributed_ledger), with the exception of the [IOTA](https://www.iota.org) integration and higher level libraries. Written in stable Rust, it has strong guarantees of memory safety and process integrity while maintaining exceptional performance.
 
-> :warning: **WARNING #1** :warning: 
->
-> **The Framework only works on the Chrysalis Phase 2 network, use [v0.2](https://github.com/iotaledger/identity.rs/releases/tag/v0.2.0) or older for pre-chrysalis phase 2 networks.**
+> :warning: **WARNING** :warning:
 > 
-> :warning: **WARNING #2** :warning:
-> 
-> This library is currently in its **alpha stage** and **under development** and might undergo large changes!
+> This library is currently in its **beta stage** and **under development** and might undergo large changes!
 > Until a formal third-party security audit has taken place, the [IOTA Foundation](https://www.iota.org/) makes no guarantees to the fitness of this library. As such, it is to be seen as **experimental** and not ready for real-world applications.
 > Nevertheless, we are very interested in feedback about user experience, design and implementation, and encourage you to reach out with any concerns or suggestions you may have.
 
@@ -81,93 +77,92 @@ edition = "2018"
 
 [dependencies]
 identity = { git = "https://github.com/iotaledger/identity.rs", branch = "main"}
-smol = { version = "0.1", features = ["tokio02"] }
-smol-potat = { version = "0.3" }
+pretty_env_logger = { version = "0.4" }
+tokio = { version = "1.5", features = ["full"] }
 ```
 *main.*<span></span>*rs*
 ```rust
-use identity::crypto::KeyPair;
-use identity::iota::{Client, Document, Network, Result, TangleRef};
+use std::path::PathBuf;
+
+use identity::account::Account;
+use identity::account::AccountStorage;
+use identity::account::IdentityCreate;
+use identity::account::IdentitySnapshot;
+use identity::account::Result;
+use identity::iota::IotaDID;
+use identity::iota::IotaDocument;
 
-#[smol_potat::main] // Using this allows us to have an async main function.
+#[tokio::main]
 async fn main() -> Result<()> {
+  pretty_env_logger::init();
+
+  // The Stronghold settings for the storage
+  let snapshot: PathBuf = "./example-strong.hodl".into();
+  let password: String = "my-password".into();
 
-  // Create a DID Document (an identity).
-  let keypair: KeyPair = KeyPair::new_ed25519()?;
-  let mut document: Document = Document::from_keypair(&keypair)?;
+  // Create a new Account with Stronghold as the storage adapter
+  let account: Account = Account::builder()
+    .storage(AccountStorage::Stronghold(snapshot, Some(password)))
+    .build()
+    .await?;
 
-  // Sign the DID Document with the default authentication key.
-  document.sign(keypair.secret())?;
+  // Create a new Identity with default settings
+  let snapshot1: IdentitySnapshot = account.create_identity(IdentityCreate::default()).await?;
 
-  // Create a client to interact with the IOTA Tangle.
-  let client: Client = Client::new()?;
+  // Retrieve the DID from the newly created Identity state.
+  let document1: &IotaDID = snapshot1.identity().try_did()?;
 
-  // Use the client to publish the DID Document to the IOTA Tangle.
-  document.publish(&client).await?;
+  println!("[Example] Local Snapshot = {:#?}", snapshot1);
+  println!("[Example] Local Document = {:#?}", snapshot1.identity().to_document()?);
+  println!("[Example] Local Document List = {:#?}", account.list_identities().await);
 
-  // Print the DID Document IOTA transaction link.
-  let network = Network::from_did(document.id());
-  let explore: String = format!("{}/transaction/{}", network.explorer_url(), document.message_id());
-  println!("DID Document Transaction > {}", explore);
+  // Fetch the DID Document from the Tangle
+  //
+  // This is an optional step to ensure DID Document consistency.
+  let resolved: IotaDocument = account.resolve_identity(document1).await?;
+
+  println!("[Example] Tangle Document = {:#?}", resolved);
 
   Ok(())
 }
 ```
 *Example output*
 ```rust
-DID Document Transaction > https://explorer.iota.org/mainnet/transaction/YARETIQBJLER9BC9U9MOAXEBWVIHXYRMJAYFQSJDCPQXXWSEKQOFKGFMXYCNXPLTRAYQZTCLJJRXZ9999
+DID Document Transaction > https://explorer.iota.org/mainnet/message/de795095cc7970c2aa4efabfe9885bd07be6664219464697b4b7506d9a87fbe3
 ```
-The output link points towards the DID Document transaction, viewable through the IOTA Tangle Explorer, see [here](https://explorer.iota.org/mainnet/transaction/YARETIQBJLER9BC9U9MOAXEBWVIHXYRMJAYFQSJDCPQXXWSEKQOFKGFMXYCNXPLTRAYQZTCLJJRXZ9999). You can see the full DID Document as transaction payload.
+The output link points towards the DID Document transaction, viewable through the IOTA Tangle Explorer, see [here](https://explorer.iota.org/mainnet/message/de795095cc7970c2aa4efabfe9885bd07be6664219464697b4b7506d9a87fbe3). You can see the full DID Document as transaction payload.
 
 ## Roadmap and Milestones
 
-For detailed development progress, see also the IOTA Identity development [canban board](https://github.com/iotaledger/identity.rs/projects/3).
+For detailed development progress, see the IOTA Identity development [kanban board](https://github.com/iotaledger/identity.rs/projects/3).
 
 IOTA Identity is in heavy development, and will naturally change as it matures and people use it. The chart below isn't meant to be exhaustive, but rather helps to give an idea for some of the areas of development and their relative completion:
 
 #### Basic Framework
 
 | Feature                   | Not started | In Research | In Development | Done | Notes                                                                |
 | :------------------------- | :---------: | :------: | :---------------: | :-:  | :-------------------------------------------------------------------- |
-| DID Document Manager      |             |          |                        | :heavy_check_mark: | Finished implementation. |
-| IOTA Integration          |             |          |                        | :heavy_check_mark: | Finished implementation. |
-| Resolver                  |             |          |                        | :heavy_check_mark: | Finished implementation. |
-| Stronghold Integration    |             |          | :large_orange_diamond: |                    | Basically done, mostly testing right now. |
-| [DID Comms](https://identity.foundation/didcomm-messaging/spec/)                 |             |          | :large_orange_diamond: |                    | Partially done. |
-| [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/)    |             |          |                        | :heavy_check_mark: | Finished implementation. |
-| VC Comms                  | :large_orange_diamond: | |                      |                    | |
-| Schema Validation         | :large_orange_diamond: | |                      |                    | |
-| C FFI Bindings            | :large_orange_diamond: | |                      |                    | |
-| JavaScript FFI Bindings   |             |          | :large_orange_diamond: |                    | Initial implementation done. |
-| [WASM Bindings](https://github.com/iotaledger/identity.rs/tree/main/bindings/wasm)             |             | :large_orange_diamond: |          |                    | |
-| [Code Examples](https://github.com/iotaledger/identity.rs/tree/main/examples)             |             |          | :large_orange_diamond: |                    | Working on more exhaustive examples. |
-| [API Reference](https://identity-docs.iota.org/docs/identity/index.html)             |             |          | :large_orange_diamond: |                    | |
-| [mdBook Documentation](https://identity-docs.iota.org/welcome.html)      |             |          | :large_orange_diamond: |                    | |
-
-#### Extended Features (2021+)
+| Implement IOTA DID Method | | | | :heavy_check_mark: | Finished implementation. |
+| [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/) | | | | :heavy_check_mark: | Finished implementation. |
+| Account | | | :large_orange_diamond: | | Base implementation done, more features to be added. |
+| [DID Comms](https://identity.foundation/didcomm-messaging/spec/) | | | :large_orange_diamond: | | Initial version done, but more to come |
+| Identity Actor | | :large_orange_diamond: | | | |
+| Selective Disclosure | :large_orange_diamond: | | | | |
+| Zero Knowledge Proofs | | :large_orange_diamond: | | | |
+| Support Embedded Rust | | :large_orange_diamond: | | | |
+| [WASM Bindings](https://github.com/iotaledger/identity.rs/tree/main/bindings/wasm) | | | :large_orange_diamond: | | implemented for low-level APIs |
+| [Code Examples](https://github.com/iotaledger/identity.rs/tree/main/examples) | | | | :large_orange_diamond: | |
+| [API Reference](https://identity-docs.iota.org/docs/identity/index.html) | | | :large_orange_diamond: | | |
+| [mdBook Documentation](https://identity-docs.iota.org/welcome.html) | | | :large_orange_diamond: | | |
 
-| Feature                   | Not started | In Research | In Development | Done | Notes                                                                |
-| :------------------------- | :---------: | :------: | :---------------: | :-:  | :-------------------------------------------------------------------- |
-| Mobile App Wrapper        | :large_orange_diamond: | |                      |                    | |
-| VC Standardization        |             | :large_orange_diamond: |          |                    | Needs quite a bit of research. |
-| Identity Agent            |             | :large_orange_diamond: |          |                    | |
-| Pairwise DID              | :large_orange_diamond: | |                      |                    | |
-| Zero-Knowledge Proofs     | :large_orange_diamond: | |                      |                    | |
-| Trust Fabric              | :large_orange_diamond: | |                      |                    | |
-| eID Integrations          | :large_orange_diamond: | |                      |                    | |
-| IoT Reputation System     | :large_orange_diamond: | |                      |                    | |
-| Identity for Objects      | :large_orange_diamond: | |                      |                    | |
-
-#### Planned Milestones
-
-At the current state, the framework is in alpha. As the framework matures we expect to support more and more types of applications. We recommend no use in real-world applications until the consumed libraries are audited, but experimentation and Proof-of-Concept projects are encouraged at the different stages.
-
-| Milestone                 | Topic                                                      | Completion     | Notes                                                                                              |
-| :----------------- | :-------------------------------------------------------- | :----- | :------------------------------------------------------------------------------------------------ |
-|    1:heavy_check_mark: | [DID](https://www.w3.org/TR/did-core/)                     | Q4 2020 | As the DID standard is implemented and the IOTA ledger is integrated first experimentations are possible. DIDs can be created, updated and ownership can be proven. This allows simple experimentations where ownership of an identity is the main requirement. |
-|    2:heavy_check_mark: | [VCs](https://www.w3.org/TR/vc-data-model/)                | Q4 2020 | With the Verifiable Credentials standard implemented, not only ownership can be proven, but also other attributes. At this stage PoCs are possible similarly to [Selv](https://selv.iota.org). However, the communications between actors are not yet implemented, identities are not easily recognized nor are credential layouts standardized. Real-world applications are possible at this stage (after audit), but require extra effort. |
-|    3:large_orange_diamond: | [DID Comms](https://identity.foundation/didcomm-messaging/spec/) | Q1 2021 | Once the communications between DID actors have been implemented, any application using identity can communicate out-of-the-box in an interoperable manner. This makes applications easier to develop, yet as mentioned in Milestone 2, identities are still not easily recognized nor are the credential layouts standarized. Real-world applications are therefore easier to develop (after audit), but scaling the application outside of a consortium is difficult. |
-|    4+             | TBD                                                        | TBD     | TBD                                                                                                |
+
+#### Next Milestones
+
+At the current state, the framework is in beta. As the framework matures we expect to support more and more types of applications. We recommend no use in real-world applications until the consumed libraries are audited, but experimentation and Proof-of-Concept projects are encouraged at the different stages.
+
+The next milestone is the release of version 1.0, which will stabilize the APIs, support backwards compatibility and versioned identities. This makes updating to future versions much easier. In addition it will provide full documentation coverage and the release will be audited. 
+
+Afterwards, we are already planning a future update containing privacy enhancing features such as Selective Disclosure and Zero Knowledge Proofs.
 
 ## Contributing
 

diff --git a/bindings/wasm/README.md b/bindings/wasm/README.md
@@ -1,17 +1,25 @@
 # IOTA Identity WASM
 
-> This is the alpha version of the official WASM bindings for [IOTA Identity](https://github.com/iotaledger/identity.rs).
+> This is the beta version of the official WASM bindings for [IOTA Identity](https://github.com/iotaledger/identity.rs).
 
 ## [API Reference](docs/api-reference.md)
 
 ## Install the library:
 
+Latest Release: This version matches the main branch of this repository, is stable and will have changelogs.
 ```bash
 $ npm install @iota/identity-wasm
 // or using yarn
 $ yarn add @iota/identity-wasm
 ```
 
+Development Release: This version matches the dev branch of this repository, may see frequent breaking changes and has the latest code changes.
+```bash
+$ npm install @iota/identity-wasm@dev
+// or using yarn
+$ yarn add @iota/identity-wasm@dev
+```
+
 ## NodeJS Setup
 
 ```js

diff --git a/examples/Cargo.toml b/examples/Cargo.toml
@@ -15,32 +15,32 @@ name = "getting_started"
 path = "getting_started.rs"
 
 [[example]]
-name = "create_did_document"
-path = "create_did_document.rs"
+name = "low_create_did"
+path = "low-level-api/create_did_document.rs"
 
 [[example]]
-name = "manipulate_did_document"
-path = "manipulate_did_document.rs"
+name = "low_manipulate_did"
+path = "low-level-api/manipulate_did_document.rs"
 
 [[example]]
-name = "verifiable_credential"
-path = "verifiable_credential.rs"
+name = "low_verifiable_credential"
+path = "low-level-api/verifiable_credential.rs"
 
 [[example]]
-name = "verifiable_presentation"
-path = "verifiable_presentation.rs"
+name = "low_verifiable_presentation"
+path = "low-level-api/verifiable_presentation.rs"
 
 [[example]]
-name = "resolution"
-path = "resolution.rs"
+name = "low_resolution"
+path = "low-level-api/resolution.rs"
 
 [[example]]
-name = "diff_chain"
-path = "diff_chain.rs"
+name = "low_diff_chain"
+path = "low-level-api/diff_chain.rs"
 
 [[example]]
-name = "merkle_key"
-path = "merkle_key.rs"
+name = "low_merkle_key"
+path = "low-level-api/merkle_key.rs"
 
 [[example]]
 name = "account_basic"