Allowlist tutorial

pages/dev-tutorials/_meta.json

@@ -5,6 +5,7 @@
   "evm-general": "EVM (General)",
   "evm-cli-tutorial": "EVM (CLI)",
   "tokenfactory-tutorial": "Token Factory",
+  "tokenfactory-allow-list": "Token Allowlists",
   "nft-contract-tutorial": "NFT Contracts",
   "pointer-contracts": "Pointer Contracts",
   "multi-sig-accounts": "Multi-Sig Accounts",

pages/dev-tutorials/tokenfactory-allow-list.mdx

@@ -0,0 +1,127 @@
+import { Callout } from 'nextra/components';
+
+# Token Allowlists
+
+The SEI Token Factory module enables token creators to restrict who can interact with their custom tokens through the
+use of allowlists.
+
+This tutorial will walk you through:
+
+1. Creating a new denom with an allowlist.
+2. Updating an existing denom to add or modify an allowlist.
+3. Querying the allowlist of a denom.
+4. Understanding the configuration and limitations of allowlists.
+
+## Prerequisites
+
+To create a token on the devnet, ensure you have the following setup:
+
+- The `seid` CLI installed.
+- A wallet with SEI tokens on devnet.
+- Access to a running Sei blockchain node.
+
+<Callout type='info'>You can obtain devnet tokens from one of the faucets listed [here](../dev-ecosystem-providers/faucets).</Callout>
+
+## Creating a Denom with Allow List
+
+1. First, create a JSON file that contains the list of addresses you want to include in your allow list.
+The format of the allow list is as follows:
+
+	```json
+	{
+		"addresses": [
+			"address1",
+			"address2",
+			"address3"
+		]
+	}
+	```
+
+	> Ensure that all addresses are valid SEI (Bech32) or EVM (0x-prefixed) addresses. Note that 0x addresses will be converted to Bech32 addresses when the allow list is persisted.
+	> The maximum number of addresses allowed in the allow list is 2000 by default. This can be configured by the chain administrator.
+
+2. Create a new denom with the specified allow list.
+
+	```bash
+	seid tx tokenfactory create-denom $SUBDENOM \
+	--allow-list=$ALLOW_LIST_FILE_PATH \
+	--from=$CREATOR_ACCOUNT \
+	--chain-id=$CHAIN_ID \
+	--fees=$FEE_AMOUNT \
+	--gas=$GAS_LIMIT \
+	-y
+	```
+
+	For example:
+
+	```bash
+	seid tx tokenfactory create-denom mytoken \
+	--allow-list=./allow_list.json \
+	--from mykey \
+	--chain-id sei-chain \
+	--fees 10000usei \
+	--gas auto \
+	-y
+	```
+
+### Understanding Command Line Arguments
+
+When executing commands in this tutorial, you'll encounter several arguments. Here's a brief overview of what each means:
+
+- `--allow-list $ALLOW_LIST_FILE_PATH`: This specifies the path to the allow list file that we have created in the previous step. E.g. `allowlist.json`.
+- `--chain-id arctic-1`: This specifies the network where the command will be executed. In this case, `arctic-1` is the identifier for the Sei devnet.
+- `--node https://rpc.arctic-1.seinetwork.io/ `: This points to the RPC URL of the node you are interacting with.
+- `--broadcast-mode block`: This determines how your transaction is broadcasted to the network. The `block` mode means the transaction will wait to be included in a block before returning a response. This is a safer option as it confirms your transaction is processed.
+- `--fees 20000usei`: This is used to specify the transaction fee.
+
+Understanding these arguments will help you execute the commands more confidently and customize them as needed for different scenarios.
+
+<Callout type='info'>For detailed descriptions of these arguments, use `seid help` in the CLI.</Callout>
+
+## Updating an Existing Denom Allowlist
+
+To update the allow list of a token, you can use the following command:
+
+```bash
+seid tx tokenfactory update-denom $DENOM \
+  --allow-list=$ALLOW_LIST_FILE_PATH \
+  --from=$ACCOUNT \
+  --chain-id=$CHAIN_ID \
+  --node=$NODE_RPC_URL \
+  --broadcast-mode=block \
+  --fees=$FEE_AMOUNT \
+  --gas=$GAS_LIMIT \
+  -y
+```
+
+For example:
+```bash
+
+seid tx tokenfactory update-denom mytoken \
+  --allow-list=./updated_allow_list.json \
+  --from mykey \
+  --chain-id arctic-1 \
+  --node https://rpc.arctic-1.seinetwork.io/ \
+  --broadcast-mode=block \
+  --fees 20000usei \
+  --gas auto \
+  -y
+```
+To re-enable all addresses to transfer the token, you can simply submit an empty allowlist.
+
+
+## Querying a Denom Allowlist
+
+You may query the allowlist of a token using the node REST endpoint. E.g.:
+
+```bash
+curl -X 'GET' \
+  'https://rest-arctic-1.sei-apis.com/sei-protocol/seichain/tokenfactory/denoms/allow_list?denom=factory/{ACCOUNT}/{DENOM}' \
+  -H 'accept: application/json'
+```
+
+## EVM Support
+
+To enable seamless use of this token in EVM environments, we can create a pointer contract. The process is described in [Token Factory tutorial](tokenfactory-tutorial.mdx#create-pointer-contract).
+
+For more advanced features and detailed insights, please refer to the [Token Factory module documentation](https://github.com/sei-protocol/sei-chain/tree/main/x/tokenfactory).