Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allowlist tutorial #135

Merged
merged 18 commits into from
Oct 10, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions pages/dev-tutorials/_meta.json
Original file line number Diff line number Diff line change
@@ -5,6 +5,7 @@
"evm-general": "EVM (General)",
"evm-cli-tutorial": "EVM (CLI)",
"tokenfactory-tutorial": "Token Factory",
"tokenfactory-allow-list": "Token Allow List Add-on",
"nft-contract-tutorial": "NFT Contracts",
"pointer-contracts": "Pointer Contracts",
"multi-sig-accounts": "Multi-Sig Accounts",
84 changes: 84 additions & 0 deletions pages/dev-tutorials/tokenfactory-allow-list.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
import { Callout } from 'nextra/components';

# Introducing Token Add-ons
dssei marked this conversation as resolved.
Show resolved Hide resolved

As you have learned form the [Token Factory tutorial](tokenfactory-tutorial.mdx), the `tokenfactory` module enables any account to create new tokens with a unique identifier based on the creator's address.
Copy link
Collaborator

@seiyan-writer seiyan-writer Sep 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a nice / friendly intro. Since it's a tutorial, we might consider adjusting the writing style to make it more direct, something like:

The Sei Token Factory module enables token creators to restrict who can interact with their custom tokens through the use of allowlists.

And maybe start with a list of what to expect to replace "In this tutorial, we will learn how to create a token with an allow list.". Something like:

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.

Can also link each section with inline references to the respective headers.

Copy link
Collaborator

@seiyan-writer seiyan-writer Sep 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On nomenclature -

  • I believe we can use "allowlist" instead of "allow list", similar to "whitelist" (compound noun).
  • I believe denom is more accurate instead of token, but token is more understandable and probably better for things like SEO. Maybe using token in the title and then denom within the actual tutorial is a good approach.


Introducing Token Add-ons, a set of features that can be added to your token to enhance its functionality.
With the first add-on being an allow list, which restricts the transferability of the token to a specific set of addresses.

In this tutorial, we will learn how to create a token with an allow list.

## Requirements
dssei marked this conversation as resolved.
Show resolved Hide resolved

To create a token on the devnet, ensure you have the following setup:

- The `seid` CLI
dssei marked this conversation as resolved.
Show resolved Hide resolved
- A wallet with SEI tokens on devnet
dssei marked this conversation as resolved.
Show resolved Hide resolved

<Callout type='info'>You can obtain devnet tokens from one of the faucets listed [here](../dev-ecosystem-providers/faucets).</Callout>

seiyan-writer marked this conversation as resolved.
Show resolved Hide resolved
## Creating a Denom with Allow List

First, we need to prepare a list of addresses that are allowed to transfer the token and save it to a JSON file.
dssei marked this conversation as resolved.
Show resolved Hide resolved
The format of the allow list is as follows:

```json
seiyan-writer marked this conversation as resolved.
Show resolved Hide resolved
{
"addresses": [
"address1",
"address2",
"address3"
]
}
```

Where each address is a valid Sei bech32 address or EVM 0x prefixed address. Please note, that 0x addresses will be converted to bech32 addresses when the allow list is persisted.
dssei marked this conversation as resolved.
Show resolved Hide resolved

dssei marked this conversation as resolved.
Show resolved Hide resolved
```bash copy
dssei marked this conversation as resolved.
Show resolved Hide resolved
seid tx tokenfactory create-denom $DENOM --from=$ACCOUNT --allow-list=$ALLOW_LIST_FILE_PATH --chain-id=arctic-1 --node=https://rpc.arctic-1.seinetwork.io/ --broadcast-mode=block --fees=20000usei
dssei marked this conversation as resolved.
Show resolved Hide resolved
```

This command creates a new coin with specific allow list.
dssei marked this conversation as resolved.
Show resolved Hide resolved

### Understanding Command Line Arguments
dssei marked this conversation as resolved.
Show resolved Hide resolved

seiyan-writer marked this conversation as resolved.
Show resolved Hide resolved
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 Token Allow List
dssei marked this conversation as resolved.
Show resolved Hide resolved

To update the allow list of a token, you can use the following command:

```bash copy
dssei marked this conversation as resolved.
Show resolved Hide resolved
seid tx tokenfactory update-denom $DENOM --from=$ACCOUNT --allow-list=$ALLOW_LIST_FILE_PATH --chain-id=arctic-1 --node=https://rpc.arctic-1.seinetwork.io/ --broadcast-mode=block --fees=20000usei
dssei marked this conversation as resolved.
Show resolved Hide resolved
```

This command updates the allow list of a token.
dssei marked this conversation as resolved.
Show resolved Hide resolved

To allow all addresses agian to transfer the token, you can simply submit an empty allow list.
dssei marked this conversation as resolved.
Show resolved Hide resolved

## Querying Token Allow List
dssei marked this conversation as resolved.
Show resolved Hide resolved

You may query the allow list of a token using the node REST endpoint. E.g.:
dssei marked this conversation as resolved.
Show resolved Hide resolved
```bash copy
dssei marked this conversation as resolved.
Show resolved Hide resolved
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'
```

dssei marked this conversation as resolved.
Show resolved Hide resolved

## 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).
Loading