Doc/resolve (#823)

documentation/docs/decentralized_identifiers/resolve.mdx

@@ -6,19 +6,187 @@ image: /img/Identity_icon.png
 keywords:
 - Resolve
 ---
+import resolve_did_rs from '!!raw-loader!../../../examples/low-level-api/resolve_did.rs';
+import resolve_history_rs from '!!raw-loader!../../../examples/low-level-api/resolve_history.rs';
+import resolve_did_js from '!!raw-loader!../../../bindings/wasm/examples/src/resolve_did.js';
+import resolve_history_js from '!!raw-loader!../../../bindings/wasm/examples/src/resolve_history.js';
 import CodeSnippet from '../../src/components/CodeSnippetComponent'
-import resolution from  '!!raw-loader!../../../examples/low-level-api/resolution.rs';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
 
-TODO: Explain how resolving works including arguments.
 
-## Example
+DID resolution is the process of fetching a [DID Document](https://www.w3.org/TR/did-core/#dfn-did-documents) corresponding to a given [DID](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers). 
+The [IOTA Identity Framework](https://github.com/iotaledger/identity.rs) supports resolving DID Documents that are stored on an IOTA Tangle (public or private). The main tool supplied 
+by the IOTA Identity Framework to handle DID Document resolution in a type safe manner is the `Resolver`. A DID Resolver as defined in the [W3C Decentralized Identifiers specification](https://www.w3.org/TR/did-core/#dfn-did-resolvers)
+enforces the signature of the resolution function in a manner that is more centered around Web/API resolution rather than a strongly typed framework. This is the reason why the `Resolver` provided by the IOTA Identity Framework deviates somewhat from 
+the W3C specification.
 
-A short example that shows how you can resolve a DID Document. This example returns the latest DID Document.
 
-<CodeSnippet 
-    nodeReplitLink="https://repl.it/@IOTAFoundation/resolution?lite=true"
-    rustContent={resolution}
-    nodeGithubLink = "https://github.com/iotaledger/identity.rs/blob/dev/bindings/wasm/examples/src/resolution.js"
-    rustGithubLink = "https://github.com/iotaledger/identity.rs/blob/dev/examples/low-level-api/resolution.rs"
+## Resolving a DID from the main network
+The following example demonstrates how to resolve the DID: "did:iota:H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" from the `main` network. 
+<Tabs>
+<TabItem value="Rust" label="Rust">
+
+```rust
+use identity::iota::Resolver; 
+use identity::iota_core::IotaDID;
+use identity::iota::ResolvedIotaDocument; 
+
+let resolver: Resolver = Resolver::new().await?; 
+let did: IotaDID = IotaDID::parse("did:iota:H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV")?;
+
+let doc: ResolvedIotaDocument = resolver.resolve(&did).await?; 
+
+```
+
+</TabItem>
+<TabItem value="node" label="Node.js">
+
+```js
+const {
+    DID,
+    Resolver,
+    ResolvedDocument,
+} = require('@iota/identity-wasm/node');
+
+ const resolver = new Resolver();
+ const did = DID.parse("did:iota:H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV");
+ const doc = await resolver.resolve(did);
+
+```
+</TabItem>
+</Tabs>
+What happens in this example can be explained on a high level as follows: The Resolver queries the Tangle for the history of the DID Document and utilizes it to recreate and validate the latest state of the DID Document. 
+
+## Resolving from a private tangle 
+Resolving a DID from a private tangle is similar to resolving a DID from the main net. The only difference is that 
+the resolver needs to be configured to have a client capable of operating on said private tangle. Building a `Client` configured for a specified Tangle is explained in [this example in Rust](https://github.com/iotaledger/identity.rs/blob/dev/examples/low-level-api/private_tangle.rs) and [this example in Javascript](https://github.com/iotaledger/identity.rs/blob/dev/bindings/wasm/examples/src/private_tangle.js).
+
+The following example demonstrates how one can setup a `Resolver` with a given `client` and then attempt resolving a specified `did` which may be on any Tangle (public or private). 
+<Tabs>
+<TabItem value="Rust" label="Rust">
+
+```rust 
+use identity::iota::Resolver;
+use identity::iota::ResolverBuilder;  
+use identity::iota_core::IotaDID;
+use identity::iota::Client;
+use identity::iota::Result; 
+
+
+async fn build_and_resolve(client: Client, did: IotaDID) -> Result<ResolvedIotaDocument> {
+    let resolver_builder: ResolverBuilder = ResolverBuilder::new().await?;
+    let resolver: Resolver = resolver_builder.client(client).build().await?;
+    resolver.resolve(did).await
+}
+```
+
+</TabItem>
+<TabItem value="node" label="Node.js">
+
+```js
+const {
+    DID,
+    Resolver,
+    ResolvedDocument,
+    Client, 
+} = require('@iota/identity-wasm/node');
+
+
+async function buildAndResolve(client, did) {
+        const resolver = await Resolver.builder().client(client).build();
+        const resolvedDocument = await resolver.resolve(did);
+        return resolvedDocument;
+}
+
+```
+</TabItem>
+</Tabs>
+
+In the example above the resolver will automatically try to resolve the DID from the network specified in the `did` (See [DID Format](./../specs/did/iota_did_method_spec#did-format)). 
+If the resolver was not built with a client configured for the given network name then an error will be thrown. Note that the `ResolverBuilder` can configure the `Resolver` to use 
+multiple networks as long as they have distinct valid names (max six characters). 
+
+Note that in the context of an identity managed by an `Account` the DID document can also be resolved by simply calling the `resolve` method on the `Account` directly. 
+
+## Resolution in the context of Verifiable Presentations 
+As explained in [Verifiable Presentations](./../verifiable_credentials/verifiable_presentations) one resolves the DID Documents of the credential issuers and presentation holder 
+during verification of a verifiable presentation. Resolving the necessary DID Documents is done automatically when verifying presentations via the `Resolver`, but there are certain 
+advanced use cases where more control is desired. To accommodate for such situations the `Resolver` also comes equipped with additional stand alone methods that enable:
+- resolving a presentation holder's DID Document
+- resolving all DID Documents of the distinct issuers of the credentials contained in the presentation
+- resolving the issuer's DID Document for a given verifiable credential
+
+
+## Resolving the history of a DID Document. 
+The fact that a DID Document [can be updated](./update.mdx) implies that the state of the DID Document can change over time, or in other words the result of resolving a DID 
+also depends on when this operation was carried out. The `Resolver` provides a way to view the entire history of a DID Document (up to the time when the method is called). 
+
+<Tabs>
+<TabItem value="Rust" label="Rust">
+
+```rust 
+use identity::iota::Resolver; 
+use identity::iota_core::IotaDID;
+use identity::iota::DocumentHistory;
+use identity::iota::Result; 
+
+
+async fn call_resolve_history(did: IotaDID) -> Result<DocumentHistory> {
+    let resolver: Resolver = Resolver::new().await?;
+    resolver.resolve_history(did).await?
+}
+```
+
+</TabItem>
+<TabItem value="node" label="Node.js">
+
+```js
+const {
+    DID,
+    Resolver,
+    DocumentHistory,
+} = require('@iota/identity-wasm/node');
+
+
+async function callResolveHistory(did) {
+        const resolver = new Resolver();
+        const documentHistory = await resolver.resolveHistory(did);
+        return documentHistory;
+}
+
+```
+</TabItem>
+</Tabs>
+
+
+## Complete examples 
+This section shows complete examples from the Iota Identity Framework code base. The first example creates a DID Document, publishes it to the Tangle and then resolves it. 
+
+<CodeSnippet 	
+    nodeReplitLink="https://repl.it/@IOTAFoundation/resolve-did?lite=true"
+    rustContent={resolve_did_rs}
+    nodeGithubLink = "https://github.com/iotaledger/identity.rs/blob/dev/bindings/wasm/examples/src/resolve_did.js"
+    rustGithubLink = "https://github.com/iotaledger/identity.rs/blob/dev/examples/low-level-api/resolve_did.rs"
 />
 
+
+This second example demonstrates creating, publishing changes and then resolving the history of a DID Document.
+<Tabs
+  groupId="programming-languages"
+  defaultValue="nodejs"
+  values={[
+    { label: "Node.js", value: "nodejs" },
+    { label: "Rust", value: "rust" }
+  ]}
+>
+  <TabItem value="nodejs">
+    <CodeBlock className="language-javascript">{resolve_history_js}</CodeBlock>
+  </TabItem>
+  <TabItem value="rust">
+    <CodeBlock className="language-rust">{resolve_history_rs}</CodeBlock>
+  </TabItem>
+</Tabs>
+
+Note that this example used the `Client` to resolve the history of the DID Document, but one could also use the `Resolver` for this task.

documentation/sidebars.js

@@ -42,7 +42,6 @@ module.exports = {
                 'decentralized_identifiers/create',
                 'decentralized_identifiers/update',
                 'decentralized_identifiers/resolve',
-                'decentralized_identifiers/resolve_history',
                 'decentralized_identifiers/private_tangle',
             ],
             'Verifiable Credentials': [