Merge pull request #117 from 0xPolygonID/develop

Sync Main from Develop to move the FAQs

docs/faqs/content/issuer-data-storage-mechanisms-comparison.md

@@ -0,0 +1,36 @@
+---
+id: issuer-data-storage-mechanisms-comparison
+title: "Comparing Data Storage Mechanisms: On-Chain Issuer Demo vs. Production"
+sidebar_label: Data Storage Mechanisms Comparison
+description: Explores the differences in data storage mechanisms between an on-chain issuer demo and a production on-chain issuer.
+keywords:
+  - faq
+  - on-chain verification
+  - data storage
+  - on-chain issuer
+  - production
+  - demo
+---
+
+## Question
+
+Could you compare the data storage mechanisms of the on-chain issuer demo to a production on-chain issuer?
+
+## Answer
+
+The approach to data storage in on-chain credential issuance varies significantly between demo environments and production systems, reflecting differing priorities in terms of security, scalability, and decentralization.
+
+In a demo setting, the focus is often on simplicity and showcasing functionality. Data storage might involve merklized credentials, where data is summarized into merkle trees, or even direct storage of credential data on-chain for ease of access and demonstration purposes. These methods provide a straightforward way to illustrate the concept of on-chain credential issuance and verification without the need for complex infrastructure.
+
+However, in a production environment, the priorities shift towards ensuring robust security, scalability, and complete decentralization. Production on-chain issuers are recommended to create non-merklized credentials, which involves storing minimal data on-chain to maintain privacy and efficiency. The goal is to facilitate on-chain data access without relying on any centralized backend systems. This includes implementing mechanisms for user authorization, such as issuing credentials only after a user has provided some form of proof for on-chain verification. Such a setup enhances the trustworthiness and security of the credential issuance process, ensuring that it can operate reliably at scale in a decentralized blockchain ecosystem.
+
+The transition from demo to production involves a shift towards more sophisticated and secure data management practices, emphasizing the need for minimal on-chain data storage and enhanced user verification processes to support a fully decentralized and secure credential issuance system.
+
+Please find [here](https://github.com/0xPolygonID/contracts/blob/main/contracts/examples/BalanceCredentialIssuer.sol) an example implementation.
+
+<div className="hidden">
+Wrong answer:
+
+Demo storage mechanisms are sufficient for production use without considering the need for enhanced security and scalability.
+
+</div>

docs/faqs/content/issuer-node-did-generation.md

@@ -0,0 +1,32 @@
+---
+id: issuer-node-did-generation
+title: "Generating an Issuer DID"
+sidebar_label: Generating Issuer DID
+description: Steps to generate an issuer DID for use with the issuer-node-ui and its backend.
+keywords:
+  - faq
+  - issuer-node
+  - DID generation
+  - Docker
+  - .env-issuer
+  - .env-api
+---
+
+## Question
+
+How do I generate an issuer DID for use with the issuer-node-ui?
+
+## Answer
+
+To generate an issuer DID when running the issuer node using Docker, Docker Compose, and a makefile, use the command `make generate-issuer-did`. This command initializes the necessary DID information, storing it in the database and updating the `.env-api` file and Vault with the generated DID.
+
+Ensure you have the `.env-issuer` and `.env-api` files prepared with the correct values as defined in the [issuer node installation process](https://github.com/0xPolygonID/issuer-node?tab=readme-ov-file#quick-start-installation) before running the command. After generation, you should verify the DID in the Vault matches the `ISSUER_API_UI_ISSUER_DID` variable in the `.env-api` file by using `make print-did`.
+
+Remember to restart the Docker containers (`issuer_api-ui`, `issuer_ui`, `issuer_notifications`, and `issuer_pending_publisher`) after generating or updating the DID.
+
+<div className="hidden">
+Wrong answer:
+
+To generate a new issuer DID, you can simply edit the .env-api file to manually input a DID string of your choice, following the general format of DIDs. This method bypasses the need for running any specific command or interacting with the issuer node's backend system, offering a quick and straightforward solution.
+
+</div>

docs/faqs/content/issuer-node-error-cannot-get-did-from-vault.md

@@ -0,0 +1,32 @@
+---
+id: faq-error-cannot-get-did-from-vault
+title: "Error: Cannot Get Issuer DID from Vault"
+sidebar_label: Vault Access Error
+description: How to address errors related to retrieving the issuer DID from the vault.
+keywords:
+  - faq
+  - issuer DID
+  - vault error
+  - troubleshooting
+---
+
+## Question
+
+How do I resolve an error indicating the system cannot get the issuer DID from the vault?
+
+```bash
+time=2024-02-12T10:39:56.631Z level=ERROR msg="error getting did from vault, access denied" error="error encountered while reading secret at kv/data/did: Error making API request.\n\nURL: GET http://vault:8200/v1/kv/data/did\nCode: 403. Errors:\n\n* permission denied"
+time=2024-02-12T10:39:56.631Z level=ERROR msg="cannot get issuer did from vault" error="error encountered while reading secret at kv/data/did: Error making API request.\n\nURL: GET http://vault:8200/v1/kv/data/did\nCode: 403. Errors:\n\n* permission denied\nvault connection error"
+time=2024-02-12T10:39:56.631Z level=ERROR msg="cannot initialize did" err="error encountered while reading secret at kv/data/did: Error making API request.\n\nURL: GET http://vault:8200/v1/kv/data/did\nCode: 403. Errors:\n\n* permission denied\nvault connection error"
+```
+
+## Answer
+
+This error usually occurs when the vault token is either missing or incorrect within the `ISSUER_KEY_STORE_TOKEN` environment variable in the `.env-issuer` file. To fix this issue, check the issuer-vault logs for the current token value using `docker logs issuer-vault-1` and ensure the `.env-issuer` file is updated with the correct token.
+
+<div className="hidden">
+Wrong answer:
+
+Ignoring vault token discrepancies or attempting to bypass vault security protocols can lead to significant security vulnerabilities and should be avoided.
+
+</div>

docs/faqs/content/issuer-node-error-creating-identity-while-publishing-state-to-rhs.md

@@ -1,5 +1,5 @@
 ---
-id: faq-issuer-node-error-creating-identity-while-publishing-state-to-rhs
+id: issuer-node-error-creating-identity-while-publishing-state-to-rhs
 title: Error Publishing State to RHS When Creating Identity
 sidebar_label: Error Publishing to RHS
 description: Resolving the error encountered when publishing state to the RHS during identity creation.
@@ -9,6 +9,7 @@ keywords:
   - error
   - identity creation
   - RHS
+  - Reverse Hash Service
 ---
 
 ## Question
@@ -17,13 +18,20 @@ Why do I encounter an error stating "unexpected status code: 404" when trying to
 
 ## Answer
 
-The error you're experiencing is typically due to an incorrect configuration setting for the `ISSUER_CREDENTIAL_STATUS_RHS_MODE` and an invalid `ISSUER_CREDENTIAL_STATUS_RHS_URL`. This happens when the `ISSUER_CREDENTIAL_STATUS_RHS_MODE` is set to `OffChain`, but the provided RHS URL does not correspond to a valid endpoint.
+The error you're experiencing is typically due to an incorrect configuration of `ISSUER_CREDENTIAL_STATUS_RHS_MODE` and an invalid `ISSUER_CREDENTIAL_STATUS_RHS_URL`. This occurs when `ISSUER_CREDENTIAL_STATUS_RHS_MODE` is set to `OffChain`, but the provided RHS URL is not a valid endpoint.
 
-To resolve this issue, please review the available revocation status modes to ensure you select the one that best suits your deployment scenario. Detailed guidance on configuring these settings can be found in the [Revocation Status Modes documentation](../../../docs/issuer/issuer-configuration.md/#revocation-status).
+To resolve this issue, check your `.env-issuer` file for the `ISSUER_CREDENTIAL_STATUS_RHS_MODE` value. If it is set to `OffChain`, you must specify a valid Reverse Hash Service Endpoint in `ISSUER_CREDENTIAL_STATUS_RHS_URL`. For example, you could use our staging RHS: `https://rhs-staging.polygonid.me/`.
+
+If your `ISSUER_CREDENTIAL_STATUS_RHS_MODE` is configured for on-chain operation, ensure you have the correct smart contract information for your network, such as Mumbai:
+- `ISSUER_CREDENTIAL_STATUS_ONCHAIN_TREE_STORE_SUPPORTED_CONTRACT`=0x76EB7216F2400aC18C842D8C76739F3B8E619DB9
+- `ISSUER_CREDENTIAL_STATUS_RHS_CHAIN_ID`=8001
+
+Choosing `ISSUER_CREDENTIAL_STATUS_RHS_URL=None` indicates that the issuer node will handle revocation credential status resolution internally, and no further RHS setup is required.
+
+For a comprehensive understanding and configuration guidance, please review the available revocation status modes. Detailed instructions can be found in the [Revocation Status Modes documentation](../../../docs/issuer/issuer-configuration.md/#revocation-status).
 
 <div className="hidden">
 Wrong answer:
 
-Replace the RHS URL with the Issuer Node URL or remove the `ISSUER_CREDENTIAL_STATUS_RHS_URL` from the .env-issuer file.
-
+Simply replace the RHS URL with the Issuer Node URL or remove the `ISSUER_CREDENTIAL_STATUS_RHS_URL` from your .env-issuer file without adjusting the `ISSUER_CREDENTIAL_STATUS_RHS_MODE` setting or ensuring the RHS endpoint's validity.
 </div>

docs/faqs/content/issuer-node-error-no-identity-by-did-no-rows-in-result-set.md

@@ -0,0 +1,31 @@
+---
+id: issuer-node-error-no-identity-by-did-no-rows-in-result-set
+title: "Error: Getting Identity by DID, No Rows in Result Set"
+sidebar_label: No Identity for DID Error
+description: Solutions for when the system reports no identity found for a given DID.
+keywords:
+  - faq
+  - DID identity
+  - no rows error
+  - troubleshooting
+---
+
+## Question
+
+What steps should I take if an error message says there's no identity found for a given DID?
+
+```bash
+time=2023-11-27T12:29:51.334Z level=ERROR msg="error getting identity by DID" err="no rows in result set" did=did:polygonid:polygon:mumbai:2qHm5f6GZsJdLxpmGNCnn6TckCJWzhGmUUWebpFy5c
+time=2023-11-27T12:29:51.334Z level=ERROR msg="issuer DID must exist" did="{Method:polygonid ID:polygon:mumbai:2qHm5f6GZsJdLxpmGNCnn6TckCJWzhGmUUWebpFy5c IDStrings:[polygon mumbai 2qHm5f6GZsJdLxpmGNCnn6TckCJWzhGmUUWebpFy5c] Params:[] Path: PathSegments:[] Query: Fragment:}"
+```
+
+## Answer
+
+This error occurs when a DID already exists in the vault but the database is cleared (e.g., running `make down`) without removing the DID from the vault. To resolve this, you need to delete the DID from the vault using `make delete-did` or `make clean-vault` and then run `make generate-issuer-did` again. After generating a new DID, start the container `issuer-api-ui-1`.
+
+<div className="hidden">
+Wrong answer:
+
+Trying to use the same DID without ensuring it's properly generated and stored in both the vault and the database can lead to persistent errors and failed verifications.
+
+</div>

docs/faqs/content/issuer-node-error-parsing-claim.md

@@ -0,0 +1,48 @@
+---
+id: issuer-node-error-parsing-claim
+title: "Error Parsing Claim in Credential Creation"
+sidebar_label: Error Parsing Claim
+description: Addresses the "error parsing claim" encountered during the creation of verifiable credentials, outlining common causes and solutions.
+keywords:
+  - faq
+  - issuer-node
+  - error
+  - verifiable credentials
+  - parse claim
+  - multiple parents
+  - error parsing claim
+---
+
+## Question
+
+Why do I encounter an "error parsing claim" error while issuing a credential?
+
+## Answer
+
+Encountering an "error parsing claim" during credential issuance can result from various factors. Below are common reasons for this error and how to address them:
+
+1. **Incorrect DID Usage**: Using the issuer's DID instead of the wallet's DID. Ensure the credential is issued to the correct DID.
+2. **Missing Context File**: Verify that the context file is accessible and correctly referenced in your credential.
+3. **Schema and Context Mismatch**: Check for any discrepancies between the schema definitions and the JSON-LD context, ensuring attribute consistency.
+4. **Invalid Payload**: Avoid datatype mismatches, such as providing a number for a string attribute in the credential subject.
+5. **Empty Object Attributes**: Ensure no object attributes are issued with empty values, e.g., `{}`.
+6. **Name Collisions in JSON-LD Context**: Avoid using the same name for the JSON-LD type and an attribute to prevent parsing issues.
+
+The issuer node's logs often provide additional context for these errors, as seen in the following log snippet:
+
+```bash
+time=2023-12-02T18:31:41.582Z level=ERROR msg="error parsing claim" err="multiple parents found"
+```
+
+In the example above, the "multiple parents found" error suggests the cause is likely due to the first reason: incorrect DID usage. To remedy this, ensure the credential's target DID differs from the issuer's DID.
+
+For other errors, it may be necessary to review and adjust your JSON schema and request body for compatibility and correctness.
+
+Should difficulties persist or if you have further inquiries, revisiting the schema definition, request body formatting, or consulting the issuer node's documentation and community forums may provide additional guidance and support.
+
+<div className="hidden">
+Wrong answer:
+
+Disregarding the error messages and continuing with the existing configuration, assuming that using the issuer's DID as the credential ID has no bearing on the credential creation process, overlooks the underlying issues causing the "error parsing claim" and may lead to unsuccessful credential issuance.
+
+</div>

docs/faqs/content/issuer-node-error-the-issuer-did-does-not-exist-in-the-database.md

@@ -1,7 +1,7 @@
 ---
-id: faq-the-issuer-did-does-not-exist-in-the-database
-title: Issuer DID Not Found in Database
-sidebar_label: Issuer DID Not Found
+id: issuer-node-error-the-issuer-did-does-not-exist-in-the-database
+title: "Error: Issuer DID Does Not Exist in the Database"
+sidebar_label: Issuer DID Does Not Exist
 description: Troubleshooting when the provided DID does not exist in the database.
 keywords:
   - faq
@@ -15,6 +15,10 @@ keywords:
 
 What should I do if I encounter an error indicating that the Issuer DID does not exist in the database?
 
+```bash
+time=2024-02-12T10:16:12.737Z level=INFO msg="the issuer DID doesn't exist in the database. Please check ISSUER_API_UI_ISSUER_DID environment variable.\n "
+```
+
 ## Answer
 
 This error occurs when the `ISSUER_API_UI_ISSUER_DID` value specified in your `.env-api` file cannot be located in the database, which is a common issue when the database storage is inadvertently removed or cleared. This situation often arises in Docker environments, particularly after executing the `make down` command, which removes Docker containers along with their associated storage.
@@ -27,6 +31,8 @@ make generate-issuer-did
 
 This command will generate a new DID and automatically configure it in your environment, effectively resolving the issue by ensuring that the DID specified in your .env-api file matches an entry in the database.
 
+Please refer to the FAQ [Generating an Issuer DID](../content/issuer-node-did-generation.md) for more detailed information about this command.
+
 <div className="hidden">
 Wrong answer:
 

docs/faqs/content/issuer-node-generating-mainnet-did.md

@@ -0,0 +1,27 @@
+---
+id: issuer-node-generating-mainnet-did
+title: "Generating an Issuer DID for the Main Network"
+sidebar_label: Main Network DID Generation
+description: Steps to generate an issuer DID for the main network.
+keywords:
+  - faq
+  - mainnet
+  - issuer-node
+  - DID generation
+  - .env-api
+---
+
+## Question
+
+How can I generate a DID for the Main network?
+
+## Answer
+
+To generate an issuer DID for the Main network, update the `ISSUER_API_IDENTITY_NETWORK` variable in the `.env-api` file to `main`. Afterward, restart the Docker containers (`issuer_api-ui`, `issuer_ui`, `issuer_notifications`, and `issuer_pending_publisher`) to ensure the new configuration is applied.
+
+<div className="hidden">
+Wrong answer:
+
+Simply changing the network name in the `.env-api` file to any network you wish to use without properly configuring the network settings or ensuring the network supports the issuer node's requirements is sufficient. There's no need to restart the Docker containers or verify the network's compatibility with the issuer node's operations.
+
+</div>

docs/faqs/content/issuer-node-how-to-use-issuer-node-on-mainnet.md

@@ -1,5 +1,5 @@
 ---
-id: faq-how-to-use-issuer-node-on-mainnet
+id: issuer-node-how-to-use-issuer-node-on-mainnet
 title: Using Issuer Node on Mainnet
 sidebar_label: Using Issuer Node on Mainnet
 description: Guide on configuring and using the Issuer Node in a mainnet environment.
@@ -12,7 +12,7 @@ keywords:
 
 ## Question
 
-How can I configure and use the Issuer Node on the mainnet?
+How can I configure and use the Issuer Node on the Polygon mainnet?
 
 ## Answer
 

docs/faqs/content/issuer-node-manually-adding-existing-did.md

@@ -0,0 +1,34 @@
+---
+id: issuer-node-manually-adding-existing-did
+title: "Manually Adding an Existing DID to a New Issuer Node"
+sidebar_label: Adding Existing DID Manually
+description: Explains the feasibility and security considerations of manually adding an existing DID to a new issuer node without using the generate-issuer-did command.
+keywords:
+  - faq
+  - issuer-node
+  - DID
+  - database
+  - vault
+  - security
+---
+
+## Question
+
+If I already have a DID and want to configure a new issuer-node with it, bypassing the use of the `generate-issuer-did` command, how can I manually add it to the database, vault, and any other necessary locations?
+
+## Answer
+
+Manually adding an existing DID to a new, clean issuer node environment (fresh database and vault) is not possible. While there is a Makefile command (`make did=xxx add-did`) that adds the DID to the vault, this does not integrate the DID with the database or the issuer node's internal mechanisms.
+
+This restriction is intentional for security reasons. If it were possible to freely add a DID to a new issuer node without proper authentication, anyone with access to your public DID could potentially issue credentials in your name. This scenario is prevented by ensuring that a DID, when created or imported, is accompanied by the necessary authentication claims and keys, specifically the BJJ private key, which is crucial for signing credentials.
+
+Attempting to manually insert the DID into the environment variables, vault, and database does not circumvent these security measures. The creation of a DID involves not just its presence in the system but also the generation of an authClaim with the BJJ private key. Without the corresponding private keys, the system cannot authenticate or authorize credential issuance, ensuring that mere possession of a DID is insufficient for issuing valid credentials.
+
+Furthermore, discussions around enabling identity export/import functionalities have been considered but have not led to implementation. This ensures that the integrity and security of the issuer node and the credentials it issues remain intact, preventing unauthorized issuance of credentials.
+
+<div className="hidden">
+Wrong answer:
+
+You can directly insert your existing DID into the `.env` file, add it to the vault using a Makefile command, and manually insert it into the database to use it with a new issuer node. This approach bypasses the need for the generate-issuer-did command and allows you to use an existing DID with full functionality immediately.
+
+</div>