From 8ec7fdd2b44f063b021f1531b3f5d17dc839b13b Mon Sep 17 00:00:00 2001
From: lbqds <lbqds@outlook.com>
Date: Wed, 18 Dec 2024 17:27:54 +0800
Subject: [PATCH] Add doc for fetching fungible token metadata

---
 docs/integration/exchange.md | 86 ++++++++++++++++++++++++++++++++++++
 docs/sdk/transaction.md      |  3 ++
 2 files changed, 89 insertions(+)

diff --git a/docs/integration/exchange.md b/docs/integration/exchange.md
index 91d94b4f..ff85840c 100644
--- a/docs/integration/exchange.md
+++ b/docs/integration/exchange.md
@@ -209,6 +209,92 @@ const depositInfo = getDepositInfo(tx)
 
 You can filter the deposit information sent to your exchange address by `targetAddress` and `tokenId`.
 
+## Fetching Fungible Token Metadata
+
+You can use the API provided by the `@alephium/web3 SDK` to fetch fungible token metadata:
+
+```typescript
+import { NodeProvider } from '@alephium/web3'
+
+const tokenId = '1a281053ba8601a658368594da034c2e99a0fb951b86498d05e76aedfe666800'
+const nodeProvider = new NodeProvider('http://127.0.0.1:12973')
+const metadata = await nodeProvider.fetchFungibleTokenMetaData(tokenId)
+// {
+//   symbol: '4159494e',
+//   name: '4159494e',
+//   decimals: 18,
+//   totalSupply: 1693518090594172274149304n
+// }
+```
+
+The `symbol` and `name` are hex-encoded UTF-8 strings.
+
+You can also use the raw endpoint to fetch fungible token metadata:
+
+```shell
+curl -X 'POST' \
+  'http://127.0.0.1:12973/contracts/multicall-contract' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "calls": [
+    {
+      "group": 0,
+      "address": "vT49PY8ksoUL6NcXiZ1t2wAmC7tTPRfFfER8n3UCLvXy",
+      "methodIndex": 0
+    },
+    {
+      "group": 0,
+      "address": "vT49PY8ksoUL6NcXiZ1t2wAmC7tTPRfFfER8n3UCLvXy",
+      "methodIndex": 1
+    },
+    {
+      "group": 0,
+      "address": "vT49PY8ksoUL6NcXiZ1t2wAmC7tTPRfFfER8n3UCLvXy",
+      "methodIndex": 2
+    },
+    {
+      "group": 0,
+      "address": "vT49PY8ksoUL6NcXiZ1t2wAmC7tTPRfFfER8n3UCLvXy",
+      "methodIndex": 3
+    }
+  ]
+}'
+```
+
+All contracts that follow the fungible token standard can use this request to fetch the token metadata. This request calls the contract methods indexed at 0, 1, 2, and 3, which respectively return the token symbol, token name, token decimals, and token total supply.
+
+This request uses the token address instead of the token ID. You can refer to the code below to convert the token ID to the token address:
+
+```typescript
+const tokenAddress = base58.encode([0x03, ...hexToBytes(tokenId)])
+```
+
+The following includes part of the response information for simplicity:
+
+```json
+{
+  "results": [
+    {
+      "type": "CallContractSucceeded",
+      "returns": [{ "type": "ByteVec", "value": "4159494e" }]
+    },
+    {
+      "type": "CallContractSucceeded",
+      "returns": [{ "type": "ByteVec", "value": "4159494e" }]
+    },
+    {
+      "type": "CallContractSucceeded",
+      "returns": [{ "type": "U256", "value": "18" }],
+    },
+    {
+      "type": "CallContractSucceeded",
+      "returns": [{ "type": "U256", "value": "1693518090594172274149304" }]
+    }
+  ]
+}
+```
+
 ## Block APIs
 
 ### Get block hash with transaction ID
diff --git a/docs/sdk/transaction.md b/docs/sdk/transaction.md
index e3e990bb..0044e9d8 100644
--- a/docs/sdk/transaction.md
+++ b/docs/sdk/transaction.md
@@ -95,11 +95,14 @@ console.log('unsigned transaction', buildTxResult.unsignedTx)
 You can also use `builtTransferTx` to build a token transfer transaction:
 
 ```typescript
+import { DUST_AMOUNT } from '@alephium/web3'
+
 const buildTxResult = await builder.buildTransferTx(
   {
     signerAddress: senderAddress,
     destinations: [{
       address: receiverAddress,
+      attoAlphAmount: DUST_AMOUNT,
       tokens: [{
         id: '19246e8c2899bc258a1156e08466e3cdd3323da756d8a543c7fc911847b96f00',
         amount: 1000000000000000000n