Add additional information

source/mainnet/net/web3-id/index.rst

@@ -13,16 +13,29 @@ Web3 ID is an extension of the core protocol identity with other types of creden
 
 Web3 ID credentials, like the existing ones, will contain commitments to a variety of attributes. :ref:`Zero-knowledge proofs<glossary-zero-knowledge-proof>` can be constructed to verify the committed values. The |bw| supports construction of these proofs. The proofs can contain a mix of verifiable credentials and account credentials.
 
-========
 Entities
 ========
 
-The core entities of the Web3ID ecosystem are :ref:`issuers<glossary-issuer>` which issue and manage the lifetime of verifiable credentials, :ref:`holders<glossary-credential-holder>` that have verifiable credentials in their wallets, and use them to prove properties about themselves to :ref:`verifiers<glossary-verifier>`.
-Verifiers ask holders for proofs about their attributes, such as proof of club membership, and holders respond with zero knowledge proofs created using their verifiable credentials.
-Verifiable credentials themselves never leave the user's wallet.
+The core entities of the Web3ID ecosystem are :ref:`issuers<glossary-issuer>` which issue and manage the lifetime of verifiable credentials, and :ref:`holders<glossary-credential-holder>` that have verifiable credentials in their wallets, and use them to prove properties about themselves to :ref:`verifiers<glossary-verifier>`.
+
+The issuer is an entity that issues verifiable credentials. Issuers have a smart contract that holds credential lifetime metadata, a back-end service that has logic for identifying users and sending transactions to the smart contract, and a dApp that interacts with the user’s wallet and the back end to facilitate issuance of credentials.
+
+Verifiers ask holders for proofs about their attributes, such as proof of club membership, and holders respond with zero knowledge proofs created using their verifiable credentials. Verifiers have a back-end service that checks verifiable presentations and provides a service, And a dApp that facilitates interaction with the wallet, making requests.
+
+A user/wallet holds verifiable credentials, produces verifiable presentations, and interacts with the issuer and verifier. Verifiable credentials themselves never leave the user's wallet.
 
 .. image:: ../images/web3id/web3id-entities.png
 
+Issuance flow
+=============
+
+#. A user initiates a request for a verifiable credential from an :ref:`issuer's<glossary-issuer>` dApp.
+#. The issuer makes a request to the user for adding Web3ID credential. The request contains attributes and metadata.
+#. The user accepts or rejects the request. If they accept they generate a fresh credential holder ID.
+#. If the user accepts, the dApp sends the verifiable credential issuance request to the issuer’s back end.
+#. The issuer verifies the request, and if OK, registers the credential in the smart contract.
+#. The issuer returns a verifiable credential to the dApp which then sends it to the wallet, thus making the user a :ref:`holder<glossary-credential-holder>`.
+
 Support for issuers and verifiers
 =================================
 
@@ -42,7 +55,7 @@ An issuer will typically consist of the following components.
 In order to simplify issuance as much as possible Concordium provides a `template smart contract <https://github.com/Concordium/concordium-rust-smart-contracts/tree/main/examples/credential-registry>`_
 that is expected to suffice for most of the issuers, but can be modified if custom logic is required.
 
-Concordium additionally provides an `issuer service <https://github.com/Concordium/concordium-web3id/tree/main/services/web3id-issuer>`_ that is designed to handle all of the chain-specific interactions, and provide a simple REST API, so that only the custom business logic of the issuer must be implemented.
+Concordium additionally provides an `issuer service <https://github.com/Concordium/concordium-web3id/tree/main/services/web3id-issuer>`_ that is designed to handle all of the chain-specific interactions, and provides a simple REST API, so that only the custom business logic of the issuer must be implemented.
 Note that the service must be run by the issuer themselves, since only they have the secret keys necessary to run it.
 
 In addition to the infrastructure listed above, the issuer must also provide JSON schemas for their credentials, and metadata.

source/mainnet/net/web3-id/issuer.rst

@@ -13,17 +13,17 @@ How to become an issuer
 An issuer needs to have the following components.
 
 1. Some way of identifying users to whom the credentials will be issued, e.g., an existing database of users.
-2. JSON schemas and metadata for credentials. These are used by the wallet to display and style the credential.
+2. JSON schemas and metadata for credentials. These are used by the wallet to display and style the credential. This might be a logo, a background color, how the attributes will appear in the credential (e.g., date format, title), and so on.
 3. A smart contract where credential lifetime is managed, together with its metadata such as expiry time.
 4. A dApp where the user will request credentials with the help of the wallet.
-5. A backend which will issue credentials, which involves registering the credential in the smart contract, and returning it to the holder's wallet.
+5. A back end which will issue credentials, which involves registering the credential in the smart contract, and returning it to the holder's wallet.
 
 Concordium Issuer tool
 ----------------------
 
 To make it easier to become an issuer, Concordium provides a generic issuer for Web3ID credentials. It exposes a REST API for registering credentials, and handles the correct formatting of credentials to submit to the chain, and communication with the node.
 
-Concordium provides docker images to make it simple to run the issuer tool, but the issuer themselves have to run it since issuing credentials requires access to private keys of the issuer, and payment of transaction fees.
+Concordium provides Docker images to make it simple to run the issuer tool, but the issuer themselves have to run it since issuing credentials requires access to private keys of the issuer, and payment of transaction fees.
 
 The issuer has the following endpoints:
 
@@ -51,13 +51,13 @@ An example response is
     "success": true
   }
 
-The issue endpoint accepts a JSON body with the request to issue the credential and if successful returns a transaction hash that may be queried for status.
+The issuer endpoint accepts a JSON body with the request to issue the credential and if successful returns a transaction hash that may be queried for status.
 
 JSON Schemas for requests and responses are available at (link).
 
 .. todo
 
-An example request is
+An example request is:
 
 .. code-block:: json
 
@@ -79,7 +79,9 @@ An example request is
      }
    }
 
-an an example response would be
+``validUntil`` makes it possible for creditals to expire. ``validFrom`` allows you to set a start date and time for the credential, such as in the case of a backstage pass for a concert.
+
+An example response would be:
 
 .. code-block:: json
 
@@ -122,7 +124,17 @@ an an example response would be
    }
 
 
-Managing credentials
-====================
 
-    - Revoke
+Revoke
+
+Credential metadata controls how the credential is displayed in the wallet. An example is:
+
+.. code-block:: json
+
+    {
+      "title": "Mixed credential",
+      "logo": {
+        "url": "https://avatars.gibhubusercontent.com/u/39614219?s=200&v=4"
+      },
+      "backgroundColor": "#ffaa00"
+    }