From 79f8d0a9f402149753875e3a38bb457b4fb310e9 Mon Sep 17 00:00:00 2001
From: Daniel Porteous <danielporteous1@gmail.com>
Date: Tue, 20 Dec 2022 16:38:46 +0000
Subject: [PATCH] Add FAQ for ANS

---
 .../docs/concepts/aptos-names-service.md      |  6 +++
 .../docs/guides/aptos-names-service-faq.md    | 54 +++++++++++++++++++
 developer-docs-site/sidebars.js               |  8 +++
 3 files changed, 68 insertions(+)
 create mode 100644 developer-docs-site/docs/concepts/aptos-names-service.md
 create mode 100644 developer-docs-site/docs/guides/aptos-names-service-faq.md

diff --git a/developer-docs-site/docs/concepts/aptos-names-service.md b/developer-docs-site/docs/concepts/aptos-names-service.md
new file mode 100644
index 0000000000000..ef7e40feea20b
--- /dev/null
+++ b/developer-docs-site/docs/concepts/aptos-names-service.md
@@ -0,0 +1,6 @@
+---
+title: "Aptos Names Service"
+id: "aptos-names-service"
+---
+
+Aptos Names is a service that allows users to associate a name with an address. Developers may lookup address -> name or name -> address.
diff --git a/developer-docs-site/docs/guides/aptos-names-service-faq.md b/developer-docs-site/docs/guides/aptos-names-service-faq.md
new file mode 100644
index 0000000000000..70e770c6362d1
--- /dev/null
+++ b/developer-docs-site/docs/guides/aptos-names-service-faq.md
@@ -0,0 +1,54 @@
+---
+title: "ANS FAQ"
+id: "aptos-names-service-faq"
+---
+
+todo, this is a bit of a mess bc currently we recommend using aptosnames.com/api, but really we should use a fullnode
+
+## Which query method should I use?
+For now, query via aptosnames.com. SDK support will land soon for querying directly via the fullnode, which is a more reliable approach.
+
+## How do I query name -> address via aptosnames.com/api?
+See https://www.aptosnames.com/about/doc.
+
+## How do I query address -> name via an aptosnames.com/api?
+See https://www.aptosnames.com/about/doc.
+
+## What name is returned if multiple names point to the same address?
+TODO: Answer what the address -> name lookup returns.
+
+## How do I query name -> address via a fullnode?
+Coming soon!
+
+TODO: Provide answers for curl + each of the SDKs (which should use the fullnode).
+
+## How do I query address -> name via a fullnode?
+Coming soon!
+
+TODO: Provide answers for curl + each of the SDKs (which should use the fullnode) (once the contract change lands).
+
+## How do I query name -> address via an indexer?
+If you prefer to do it this way, you can do so with a query like this:
+```
+todo
+```
+
+Note that the fullnode approach is lower latency and has fewer dependencies though, so using a fullnode (which is what the SDKs use) is recommended.
+
+## How do I query address -> name via an indexer?
+If you prefer to do it this way, you can do so with a query like this:
+```
+todo
+```
+
+## Are the endpoints at aptosnames.com/api reliable?
+Consider a lookup via aptosnames.com/api, for example this name to address lookup:
+```ts
+const name = "test";
+const response = await fetch(`https://www.aptosnames.com/api/testnet/v1/address/${name}`);
+const { address } = await response.json();
+```
+
+This takes the following path: Client -> aptosnames.com/api -> Google Cloud Functions -> Public Aptos Indexer. The indexer in turn relies on its own DB and fullnode.
+
+So far this service has never gone down, but if you consider this too many potential points of failure, you may do a lookup via the fullnode directly (coming soon).
diff --git a/developer-docs-site/sidebars.js b/developer-docs-site/sidebars.js
index 6b60c633d4d72..b74e00b3b9328 100644
--- a/developer-docs-site/sidebars.js
+++ b/developer-docs-site/sidebars.js
@@ -147,6 +147,14 @@ const sidebars = {
       collapsed: true,
       items: ["guides/wallet-adapter-for-dapp", "guides/wallet-adapter-for-wallets"],
     },
+    {
+      type: "category",
+      label: "Aptos Names Service",
+      link: { type: "doc", id: "concepts/aptos-names-service" },
+      collapsible: true,
+      collapsed: true,
+      items: ["guides/aptos-names-service-faq"],
+    },
     {
       type: "html",
       value: "Run Nodes",