Skip to content

Commit a77b228

Browse files
anyxemanyxem
authored
feat: mls-01 token issue (#4)
* feat: add MLS-01 token issue documentation * feat: add sending tokens command * update posititon
1 parent d8f2c07 commit a77b228

2 files changed

Lines changed: 229 additions & 0 deletions

File tree

‎docs/guides/_category_.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"label": "Guides",
3+
"position": 40,
4+
"link": {
5+
"type": "generated-index"
6+
}
7+
}

‎docs/guides/issue-new-token.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# Token Generation Documentation
2+
3+
## Prerequisites
4+
5+
To generate a new token using the `token-issue-new` command, ensure the following prerequisites are met:
6+
7+
1. **Running Node**: You need a synchronized blockchain node running via the `node-daemon`. This node must be operational and connected to the network.
8+
2. **Running Wallet**: You must have the `wallet-cli` tool installed and configured. Ensure your wallet is active and funded with at least **100 Coins** for the issuance fee, plus additional transaction fees.
9+
10+
## Overview
11+
12+
The `token-issue-new` command is used to generate a new token on a blockchain network. This command requires several arguments to define the token's properties and metadata.
13+
14+
## Command Syntax
15+
16+
```bash
17+
token-issue-new <TOKEN_TICKER> <NUMBER_OF_DECIMALS> <METADATA_URI> <DESTINATION_ADDRESS> <TOKEN_SUPPLY> <IS_FREEZABLE>
18+
```
19+
20+
### Required Arguments
21+
22+
The following arguments are mandatory for the `token-issue-new` command:
23+
24+
| Argument | Description |
25+
|-----------------------|-----------------------------------------------------------------------------|
26+
| `<TOKEN_TICKER>` | The unique ticker symbol for the token (e.g., `XYZ`). |
27+
| `<NUMBER_OF_DECIMALS>`| The number of decimal places the token supports (e.g., `18`). |
28+
| `<METADATA_URI>` | A URI pointing to an IPFS-hosted JSON file containing token metadata (see below for details). |
29+
| `<DESTINATION_ADDRESS>` | The authority address that can control the token (e.g., `tmt1qyj...dulgmxyx`). |
30+
| `<TOKEN_SUPPLY>` | The token supply type. Can be `unlimited`, `lockable`, or `fixed(Amount)` where `Amount` is a numeric supply (e.g., `fixed(1000000)`). |
31+
| `<IS_FREEZABLE>` | Indicates if the token can be frozen. Must be `freezable` or `not-freezable`. |
32+
33+
### Error Example
34+
35+
If any required arguments are missing, the following error will be displayed:
36+
37+
```
38+
error: the following required arguments were not provided:
39+
<TOKEN_TICKER>
40+
<NUMBER_OF_DECIMALS>
41+
<METADATA_URI>
42+
<DESTINATION_ADDRESS>
43+
<TOKEN_SUPPLY>
44+
<IS_FREEZABLE>
45+
```
46+
47+
### Success Response
48+
49+
Upon successful execution, you will receive a response like this:
50+
51+
```
52+
A new token has been issued with ID: tmltk1jzgup9....ah0pjffwhpqgsvmuq in tx: f51ddbe5354557....2f1d21a51e
53+
```
54+
55+
- `<TOKEN_ID>`: The unique identifier for the newly issued token (e.g., `tmltk1jzgup9....ah0pjffwhpqgsvmuq`).
56+
- `<tx>`: The transaction hash (e.g., `f51ddbe5354557....2f1d21a51e`).
57+
58+
### Token Issuance Fee
59+
60+
The current fee for issuing a new token is **100 Coins**. Ensure your wallet has sufficient funds to cover this fee.
61+
62+
## Metadata URI
63+
64+
The `<METADATA_URI>` argument must point to a JSON file uploaded to IPFS (InterPlanetary File System). This JSON file contains detailed metadata about the token. Below is the structure and description of the fields in this file:
65+
66+
### JSON Metadata Structure
67+
68+
```json
69+
{
70+
"name": "Token Name",
71+
"symbol": "TOKEN_TICKER",
72+
"description": "A brief description of the token and its purpose.",
73+
"websiteUrl": "https://example.com",
74+
"twitter": "https://twitter.com/example",
75+
"telegram": "https://t.me/example",
76+
"discord": "https://discord.gg/example",
77+
"totalSupply": "1000000",
78+
"initialSupply": "500000",
79+
"tokenDistribution": "Details about how tokens are distributed.",
80+
"whitepaper": "https://example.com/whitepaper.pdf",
81+
"tags": ["defi", "utility", "blockchain"],
82+
"roadmap": "A brief roadmap or link to roadmap details.",
83+
"decimals": 18,
84+
"isFixedSupply": true,
85+
"isFreezable": "freezable",
86+
"facebook": "https://facebook.com/example",
87+
"instagram": "https://instagram.com/example",
88+
"youtube": "https://youtube.com/example",
89+
"linkedin": "https://linkedin.com/company/example",
90+
"twitch": "https://twitch.tv/example",
91+
"tokenIcon": "ipfs://<hash>/token-icon.png",
92+
"bannerImage": "ipfs://<hash>/banner-image.png",
93+
"thumbnailImage": "ipfs://<hash>/thumbnail-image.png",
94+
"projectLogo": "ipfs://<hash>/project-logo.png"
95+
}
96+
```
97+
98+
### Field Descriptions
99+
100+
| Field | Type | Description |
101+
|--------------------|------------|-----------------------------------------------------------------------------|
102+
| `name` | String | The full name of the token (e.g., "Example Token"). |
103+
| `symbol` | String | The token ticker symbol (e.g., "XYZ"). Must match `<TOKEN_TICKER>`. |
104+
| `description` | String | A short description of the token's purpose or project. |
105+
| `websiteUrl` | String | URL to the project's official website. |
106+
| `twitter` | String | URL to the project's Twitter page. |
107+
| `telegram` | String | URL to the project's Telegram group/channel. |
108+
| `discord` | String | URL to the project's Discord server. |
109+
| `totalSupply` | String | The total supply of tokens (e.g., "1000000"). |
110+
| `initialSupply` | String | The initial supply of tokens issued (e.g., "500000"). |
111+
| `tokenDistribution` | String | Details about token distribution (e.g., team, public sale, etc.). |
112+
| `whitepaper` | String | URL to the project's whitepaper document. |
113+
| `tags` | Array | A list of tags or keywords related to the token (e.g., ["defi", "utility"]). |
114+
| `roadmap` | String | A brief roadmap or link to a detailed roadmap. |
115+
| `decimals` | Integer | Number of decimal places (must match `<NUMBER_OF_DECIMALS>`). |
116+
| `isFixedSupply` | Boolean | Indicates if the token supply is fixed (`true`) or mutable (`false`). |
117+
| `isFreezable` | String | Indicates if the token can be frozen. Must be `"freezable"` or `"not-freezable"`. Must match `<IS_FREEZABLE>`. |
118+
| `facebook` | String | URL to the project's Facebook page. |
119+
| `instagram` | String | URL to the project's Instagram page. |
120+
| `youtube` | String | URL to the project's YouTube channel. |
121+
| `linkedin` | String | URL to the project's LinkedIn page. |
122+
| `twitch` | String | URL to the project's Twitch channel. |
123+
| `tokenIcon` | String | IPFS URI to the token's icon image. |
124+
| `bannerImage` | String | IPFS URI to the token's banner image. |
125+
| `thumbnailImage` | String | IPFS URI to the token's thumbnail image. |
126+
| `projectLogo` | String | IPFS URI to the project's logo image. |
127+
128+
### Notes on Metadata
129+
- Fields like `twitter`, `telegram`, `discord`, etc., are optional and can be omitted if not applicable.
130+
- Image fields (`tokenIcon`, `bannerImage`, etc.) should point to valid IPFS resources.
131+
- Ensure that `symbol`, `decimals`, and `isFreezable` in the JSON match the values provided in the command arguments.
132+
133+
## Example Usage
134+
135+
To issue a new token with the ticker "XYZ", 18 decimals, a fixed supply of 1 million, and freezable capability:
136+
137+
```bash
138+
token-issue-new XYZ 18 ipfs://QmExampleHash123 tmt1qyj...dulgmxyx fixed(1000000) freezable
139+
```
140+
141+
In this example:
142+
- The metadata JSON is hosted at `ipfs://QmExampleHash123`.
143+
- The authority address is `tmt1qyj...dulgmxyx`.
144+
- The supply is fixed at 1,000,000 tokens.
145+
146+
Alternatively, for an unlimited supply and not freezable:
147+
148+
```bash
149+
token-issue-new XYZ 18 ipfs://QmExampleHash123 tmt1qyj...dulgmxyx unlimited not-freezable
150+
```
151+
152+
## Troubleshooting
153+
154+
- **Missing Arguments**: Double-check that all required arguments are provided in the correct order.
155+
- **Invalid METADATA_URI**: Verify that the IPFS URI is accessible and points to a valid JSON file.
156+
- **Invalid TOKEN_SUPPLY**: Ensure the supply is specified as `unlimited`, `lockable`, or `fixed(Amount)` with a valid numeric `Amount`.
157+
- **Invalid IS_FREEZABLE**: Use `freezable` or `not-freezable` only.
158+
- **Insufficient Funds**: Confirm your wallet has enough funds for the **100 Coins** fee plus gas.
159+
- **Node/Wallet Issues**: Ensure `node-daemon` is running and `wallet-cli` is properly configured and synced.
160+
161+
## Minting Tokens
162+
163+
Issuing a token with `token-issue-new` does not automatically distribute tokens to a specific address. To receive tokens at a desired address, you must mint them using the `token-mint` command.
164+
165+
### Mint Command Syntax
166+
167+
```bash
168+
token-mint <TOKEN_ID> <ADDRESS> <AMOUNT>
169+
```
170+
171+
#### Required Arguments
172+
173+
| Argument | Description |
174+
|--------------|-----------------------------------------------------------------------------|
175+
| `<TOKEN_ID>` | The token ID received from `token-issue-new` (e.g., `tmltk1jzgup9....ah0pjffwhpqgsvmuq`). |
176+
| `<ADDRESS>` | The address to receive the minted tokens (e.g., `tmt1qyj...dulgmxyx`). |
177+
| `<AMOUNT>` | The amount of tokens to mint (e.g., `500000`). |
178+
179+
#### Error Example
180+
181+
If any required arguments are missing:
182+
183+
```
184+
error: the following required arguments were not provided:
185+
<TOKEN_ID>
186+
<ADDRESS>
187+
<AMOUNT>
188+
```
189+
190+
#### Example Mint Command
191+
192+
To mint 500,000 tokens to an address:
193+
194+
```bash
195+
token-mint tmltk1jzgup9....ah0pjffwhpqgsvmuq tmt1qyj...dulgmxyx 500000
196+
```
197+
198+
## Sending Tokens
199+
200+
Once tokens are minted, you may want to send them to another address. Note that the `address-send` command is **not suitable** for sending tokens. Instead, use the `token-send` command specifically designed for this purpose.
201+
202+
### Send Command Syntax
203+
204+
```bash
205+
token-send <TOKEN_ID> <ADDRESS> <AMOUNT>
206+
```
207+
208+
#### Required Arguments
209+
210+
| Argument | Description |
211+
|--------------|-----------------------------------------------------------------------------|
212+
| `<TOKEN_ID>` | The token ID of the tokens to be sent (e.g., `tmltk1jzgup9....ah0pjffwhpqgsvmuq`). |
213+
| `<ADDRESS>` | The destination address receiving the tokens (e.g., `tmt1qyj...dulgmxyx`). |
214+
| `<AMOUNT>` | The amount of tokens to be sent (e.g., `500`). |
215+
216+
#### Example Send Command
217+
218+
To send 500 tokens to an address:
219+
220+
```bash
221+
token-send tmltk1jzgup9....ah0pjffwhpqgsvmuq tmt1qyj...dulgmxyx 500
222+
```

0 commit comments

Comments
 (0)