diff --git a/README.md b/README.md index ece88515e2..5223704f31 100644 --- 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,47 +77,64 @@ 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.**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: @@ -129,45 +142,27 @@ IOTA Identity is in heavy development, and will naturally change as it matures a | 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 index 2b0f4089fe..eb4cf31edc 100644 --- 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 index 3a204f787d..97291772b9 100644 --- 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" diff --git a/examples/README.md b/examples/README.md index 6551e0437d..f755ecdbd9 100644 --- a/examples/README.md +++ b/examples/README.md @@ -18,15 +18,26 @@ For Instance, to run the example `getting_started`, use cargo run --example getting_started ``` -The following examples are currently available: +The following examples are avaliable 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 | [create_did_document](create_did_document.rs) | A basic example that generates and publishes a DID Document, the fundamental building block for decentralized identity. | -| 3 | [manipulate_did_documents](manipulate_did_document.rs) | This example goes into more detail regarding the useage of DID Documents. | -| 4 | [verifiable_credential](verifiable_credential.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 | [verifiable_presentation](verifiable_presentation.rs) | This example explains how to create a Verifiable Presentation from a set of credentials and sign it. | -| 6 | [resolution](resolution.rs) | A basic example that generates a DID Document, publishes it to the Tangle, and retrieves information through DID Document resolution/dereferencing. | -| 7 | [diff_chain](diff_chain.rs) | An example that utilizes a diff and integration chain to publish updates to a DID Document. | -| 8 | [merkle_key](merkle_key.rs) | An example that revokes a key and shows how verification fails as a consequence. | \ No newline at end of file +| 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 useage 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. | + + +The following examples are avaliable for using the low-level APIs, which provides more flexibility at the cost of complexity: + +| # | Name | Information | +| :--: | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | +| 1 | [low_create_did](./low-level-api/create_did_document.rs) | A basic example that generates and publishes a DID Document, the fundamental building block for decentralized identity. | +| 2 | [low_manipulate_did](./low-level-api/manipulate_did_document.rs) | This example goes into more detail regarding the usage of DID Documents. | +| 3 | [low_verifiable_credential](./low-level-api/verifiable_credential.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. | +| 4 | [low_verifiable_presentation](./low-level-api/verifiable_presentation.rs) | This example explains how to create a Verifiable Presentation from a set of credentials and sign it. | +| 5 | [low_resolution](./low-level-api/resolution.rs) | A basic example that generates a DID Document, publishes it to the Tangle, and retrieves information through DID Document resolution/dereferencing. | +| 6 | [low_diff_chain](./low-level-api/diff_chain.rs) | An example that utilizes a diff and integration chain to publish updates to a DID Document. | +| 7 | [low_merkle_key](./low-level-api/merkle_key.rs) | An example that revokes a key and shows how verification fails as a consequence. | \ No newline at end of file diff --git a/examples/common.rs b/examples/low-level-api/common.rs similarity index 100% rename from examples/common.rs rename to examples/low-level-api/common.rs diff --git a/examples/create_did_document.rs b/examples/low-level-api/create_did_document.rs similarity index 100% rename from examples/create_did_document.rs rename to examples/low-level-api/create_did_document.rs diff --git a/examples/diff_chain.rs b/examples/low-level-api/diff_chain.rs similarity index 100% rename from examples/diff_chain.rs rename to examples/low-level-api/diff_chain.rs diff --git a/examples/manipulate_did_document.rs b/examples/low-level-api/manipulate_did_document.rs similarity index 100% rename from examples/manipulate_did_document.rs rename to examples/low-level-api/manipulate_did_document.rs diff --git a/examples/merkle_key.rs b/examples/low-level-api/merkle_key.rs similarity index 100% rename from examples/merkle_key.rs rename to examples/low-level-api/merkle_key.rs diff --git a/examples/resolution.rs b/examples/low-level-api/resolution.rs similarity index 100% rename from examples/resolution.rs rename to examples/low-level-api/resolution.rs diff --git a/examples/verifiable_credential.rs b/examples/low-level-api/verifiable_credential.rs similarity index 100% rename from examples/verifiable_credential.rs rename to examples/low-level-api/verifiable_credential.rs diff --git a/examples/verifiable_presentation.rs b/examples/low-level-api/verifiable_presentation.rs similarity index 100% rename from examples/verifiable_presentation.rs rename to examples/low-level-api/verifiable_presentation.rs