From 6c3cfcc33add15dbccbd7c2e89fd087e468569b1 Mon Sep 17 00:00:00 2001
From: thephez <thephez@users.noreply.github.com>
Date: Mon, 28 Oct 2024 15:30:54 -0400
Subject: [PATCH] docs: add dpns faq items, rename and move faq (#87)

* docs: dpns faqs

* refactor: rename and move faq

* docs: faq about normalization

* docs: sidebar update

* docs: more faqs

* docs: reorder faq
---
 _templates/sidebar-main.html                 |  30 +++---
 docs/index.md                                |   2 +-
 docs/reference/frequently-asked-questions.md |  39 -------
 docs/resources/faq.md                        | 103 +++++++++++++++++++
 4 files changed, 117 insertions(+), 57 deletions(-)
 delete mode 100644 docs/reference/frequently-asked-questions.md
 create mode 100644 docs/resources/faq.md

diff --git a/_templates/sidebar-main.html b/_templates/sidebar-main.html
index 6589b81f3..e90924b03 100644
--- a/_templates/sidebar-main.html
+++ b/_templates/sidebar-main.html
@@ -231,8 +231,6 @@
                     <li class="toctree-l1"><a class="reference internal"
                             href="docs/reference/glossary.html">Glossary</a>
                     </li>
-                    <li class="toctree-l1"><a class="reference internal"
-                            href="docs/reference/frequently-asked-questions.html">Frequently Asked Questions</a></li>
                 </ul>
                 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Platform Protocol
                         Reference</span>
@@ -262,21 +260,19 @@
                 </ul>
                 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Resources</span></p>
                 <ul class="nav bd-sidenav">
-                    <li class="toctree-l1"><a class="reference internal"
-                            href="docs/resources/repository-overview.html">Repository
-                            Overview</a></li>
-                    <li class="toctree-l1"><a class="reference external"
-                            href="https://platform-explorer.com/">Platform Explorer</a></li>
-                    <li class="toctree-l1"><a class="reference external"
-                            href="https://testnet-insight.dashevo.org/insight/">Testnet Block Explorer</a></li>
-                    <li class="toctree-l1"><a class="reference external"
-                            href="http://faucet.testnet.networks.dash.org/">Testnet
-                            Faucet</a></li>
-
-                    <li class="toctree-l1"><a class="reference internal" href="docs/resources/source-code.html">Source
-                            Code</a></li>
-                    <li class="toctree-l1"><a class="reference external"
-                            href="https://dashplatform.readme.io/v0.23.0/docs">Previous Version of Docs</a></li>
+                <li class="toctree-l1"><a class="reference internal" href="docs/resources/faq.html">FAQ</a></li>
+                <li class="toctree-l1"><a class="reference internal" href="docs/resources/repository-overview.html">Repository
+                                Overview</a></li>
+                <li class="toctree-l1"><a class="reference external" href="https://platform-explorer.com/">Platform Explorer</a></li>
+                <li class="toctree-l1"><a class="reference external" href="https://testnet-insight.dashevo.org/insight/">Testnet Block
+                                Explorer</a></li>
+                <li class="toctree-l1"><a class="reference external" href="http://faucet.testnet.networks.dash.org/">Testnet
+                                Faucet</a></li>
+                
+                <li class="toctree-l1"><a class="reference internal" href="docs/resources/source-code.html">Source
+                                Code</a></li>
+                <li class="toctree-l1"><a class="reference external" href="https://dashplatform.readme.io/v0.23.0/docs">Previous Version
+                                of Docs</a></li>
                 </ul>
                 <p aria-level="2" class="caption" role="heading"><span class="caption-text">JavaScript SDK</span></p>
                 <ul class="nav bd-sidenav">
diff --git a/docs/index.md b/docs/index.md
index 08451dd6c..5254aa0d1 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -147,7 +147,6 @@ reference/dapi-endpoints
 reference/query-syntax
 reference/data-contracts
 reference/glossary
-reference/frequently-asked-questions
 ```
 
 ```{toctree}
@@ -171,6 +170,7 @@ protocol-ref/errors
 :caption: Resources
 :hidden:
 
+resources/faq
 resources/repository-overview
 Platform Explorer <https://platform-explorer.com/>
 Testnet Block Explorer <https://insight.testnet.networks.dash.org:3002/insight/>
diff --git a/docs/reference/frequently-asked-questions.md b/docs/reference/frequently-asked-questions.md
deleted file mode 100644
index 3a5af57fa..000000000
--- a/docs/reference/frequently-asked-questions.md
+++ /dev/null
@@ -1,39 +0,0 @@
-```{eval-rst}
-.. _reference-faq:
-```
-
-# Frequently Asked Questions
-
-## What is Evolution?
-
-"Evolution" is a codename used to reference various products. It includes "Dash Platform," a FireBase-like platform for developing backends for websites and applications, hosted on the masternode network.
-
-Also, the term " Evolution" refers to several other products that we are going to develop on top of the platform. An example of such an app is DashPay - an easy to use payment solution with usernames and contact lists.
-
-## How does a DAPI client discover the IP address of masternodes hosting DAPI endpoints?
-
-The DNS seed will provide a deterministic masternode list (DML) to the client. More on the deterministic MN list can be found here:
-
-- DML spec: https://github.com/dashpay/dips/blob/master/dip-0003.md
-- DML verification: https://github.com/dashpay/dips/blob/master/dip-0004.md
-
-## Why can't I connect to DAPI from a page served over HTTPS?
-
-Modern browsers block connections to insecure content when the main page is loaded securely. At the moment, there are technical obstacles to serving DAPI content over HTTPS. Until then, the only way to test DAPI from a web page is to serve the web page insecurely. Dash Core team is evaluating different ways to work around this browser restriction and have a trustworthy connection to DAPI.
-
-## Will it be possible to use apps with only an identity, or will a DPNS name have to be registered first?
-
-Apps can interact with an identity whether or not it has a DPNS name registered. Someone may create an app that requires one, but it's not a platform restriction.
-
-## Should it be possible to create multiple identities using a single private key?
-
-It may not be a very good practice, but this is not restricted.
-
-## Will DAPI RPCs always be free? How will DoS attacks be mitigated?
-
-Right now there's only IP based rate limits. Generally Core team wants platform data to be available for everyone, so there are no plans today to have paid queries.
-
-## When I try to load the Dash javascript library, why is there is a syntax error "Invalid regular expression"?
-
-This can be caused by loading the script with the wrong character encoding. The `dash` npm package uses UTF-8 encoding. Try this:
-`<script src="https://unpkg.com/dash" encoding="UTF-8"></script>`
diff --git a/docs/resources/faq.md b/docs/resources/faq.md
new file mode 100644
index 000000000..605c0d373
--- /dev/null
+++ b/docs/resources/faq.md
@@ -0,0 +1,103 @@
+```{eval-rst}
+.. _reference-faq:
+```
+
+# FAQ
+
+## DPNS names
+
+:::{tip}
+See the [Name Service (DPNS)](../explanations/dpns.md) page for additional information on the
+Dash Platform Name Service (DPNS).
+:::
+
+:::{dropdown} How can I register a name?
+
+Currently, names can be registered using several technical tools; however, the upcoming [DashPay
+Android](https://play.google.com/store/apps/details?id=hashengineering.darkcoin.wallet) update will
+provide a much easier way to do this.
+
+Developers and other technical users may want to experiment with registering names using the [JS
+SDK](https://docs.dash.org/projects/platform/en/stable/docs/tutorials/identities-and-names/register-a-name-for-an-identity.html)
+or [Platform TUI](https://github.com/dashpay/platform-tui/).
+:::
+
+:::{dropdown} How long does it take to register and receive a name?
+
+Regular (non-premium) names are registered and received immediately. [Premium
+names](../explanations/dpns.md#conflict-resolution) must go through a two-week voting period before
+receiving the name.
+:::
+
+::::{dropdown} Can I register multiple names?
+
+:::{note}
+**Note**: the mobile apps do not currently support registering more than one name under the same
+mnemonic.
+:::
+
+Yes, each [identity](../explanations/identity.md) can have multiple names.
+::::
+
+:::{dropdown} What characters are valid in names?
+
+Names can contain the characters `0-9`, `-` (hyphen), and `A-Z` (case insensitive). Names cannot
+begin or end with a hyphen (e.g. `-name` or `name-`).
+:::
+
+:::{dropdown} Why do names have "0" and "1" in them when viewed in some apps?
+
+Some apps display the normalized name instead of the requested (display) name. To mitigate
+[homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), `o` is replaced with `0`
+and `i`/`l` are replaced with `1` internally for validation. For example, "Alice" is normalized to
+"a11ce".
+
+Once any iteration of the normalized name is registered, the alternatives cannot be registered. For
+example, once "Alice" is registered, none of the following will be available:
+
+* alice
+* a1ice
+* a11ce
+* al1ce
+
+:::
+
+:::{dropdown} What is a contested (premium) name?
+
+Any name meeting the following criteria is considered premium:
+
+* Less than 20 characters long (i.e. "alice", "quantumexplorer") AND
+* Contain no numbers or only contain the number(s) 0 and/or 1 (i.e. "bob", "carol01")
+
+These names require a two-week waiting period during which masternodes and evonodes vote to
+determine who (if anyone) receives the name. To pay for the voting, anyone requesting the name must
+pay a 0.2 DASH name request fee.
+:::
+
+:::{dropdown} What happens if no one votes for a contested username request?
+
+If no one votes, the first identity requesting the name will receive it.
+:::
+
+:::{dropdown} Can locked names be requested by someone else later?
+
+Locked names can no longer be requested or awarded in Dash Platform v1. The plan is to change this
+in future updates, but the exact details have not been defined.
+:::
+
+:::{dropdown} What happens if there is a tie vote?
+
+If there is a tie, the first identity requesting the name will receive it. This applies even if
+there is a tie between votes for an identity and votes to lock the name.
+:::
+
+:::{dropdown} How many times can a masternode change their vote for a name?
+
+Masternodes and evonodes can vote a total of 5 times per name. At the end of the voting period, the
+most recent vote is the one that is counted.
+:::
+
+:::{dropdown} Is it necessary to have a DPNS name to use Platform apps?
+
+No, apps can interact with an identity whether or not it has a DPNS name registered. Someone may create an app that requires names, but it is not a platform requirement.
+:::