Skip to content

Commit 54799c5

Browse files
henry-ngvhenry-ngv
committed
2 parents 1c410a3 + d163a9d commit 54799c5

File tree

1 file changed

+171
-1
lines changed

1 file changed

+171
-1
lines changed

‎docs/unichainToken.md

Lines changed: 171 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,177 @@ interface IURC20 {
3333
```
3434
Please go to smart contract session to learn how to write and deploy smart contract on UniChain network.
3535
36-
## URC-30 token
36+
## URC-30 Native Token
37+
URC-30 token is the native token on UniChain network. It has the same function as the URC-20 token but the big difference is that It does not based on smart contracts. Users can interact with the token by using APIs from blockchain nodes. Unlike URC-20 token, transferring URC-30 token does not require UNW as the transaction fee (gas). Instead, the transaction fee is from the token itself.
38+
The following picture describes how the transaction fee model in URC-30 works.
39+
40+
![URC-30 token fee](../img/urc30_token_fee.png)
41+
42+
Each URC-30 token has the token pool fee providing the transaction fee (in UNW) for all token transfer. The pool is initiated by the token owner and contributed by anyone. When user A transfers a token to user B, for example 100 token X, the following will occur:
43+
44+
- The pool fee of token X will be taken out for executing the transfer transaction. Currently, It costs about 0.000268 UNW
45+
- An amount of token X will be transfer to token owner, for example 1 token X
46+
- User B only receive 99 token X
47+
48+
The token owner can specify the transaction fee in terms of token to balance out with the UNW deposited to the token pool.
49+
50+
The basic functions of URC-30 token as below:
51+
- Create an URC-30 token
52+
- Transfer token from users to users
53+
- Transfer token for future uses (same as lock token)
54+
- Update token information
55+
- Exchange token with UNW
56+
- Mint token (increase the total supply)
57+
- Burnt token (decrease total supply)
58+
- Contribute fee to the token pool
59+
- Transfer ownership
60+
61+
### Issue URC-30 token on UniWallet
62+
Users can issue URC-30 tokens by using wallet-cli, APIs, SDK ... but the simplest way is to use [UniWallet](https://uniwallet.world).
63+
64+
<ul>
65+
<li>Step 1: Go to UniWallet website</li>
66+
<li>Step 2: Login to your wallet</li>
67+
<li>Step 3: Navigate to the Token Tool on the left panel and fill the token information</li>
68+
<li>Step 4: Sumbit and input your wallet password. A txid will be returned if everything is OK </li>
69+
</ul>
70+
71+
![Create URC-30 Token](../img/create_urc30_token.png)
72+
73+
The following describes the token params in details
74+
75+
- Token Name: The name of the token. The name must be unique, less than 32 human readable characters.
76+
- Abbr: Abbreviation of the token, Abbr should less than 32 human readable characters
77+
- Total supply: Total supply is the supply at the token creation. It should be integer number with the range from 1 to 2^63 - 1
78+
- Max supply: The maximum supply of the token. It should be integer number with the range from 1 to 2^63 -1
79+
- Start time: Start time is the time that token can be used. Token can be issued for future uses. - Date and time are from UTC timezone. The default value is now (token can be used after creation)
80+
- End time: End time is the time that token cannot be used. The default value is 50 years and maximum value is 200 years (from now)
81+
- Url: the url to website or information of token creators.
82+
- Extra fee rate: The extra fee rate is the transaction fee calculated in percentage of transferred amount. For example, if the extra fee rate is 1%, when transferring 100 token X from user A to user B, there will be 100 token X transferred from A to B, 1 token X will be transferred to the token creator. Value range of extra fee is from 0 - 100
83+
- Fee: The transaction fee for transferring a token regardless of token amount. Please note that the token transaction fee of transferring a token will be transaction fee and extra fee. For example, if the fee is set to 2, the extra fee rate is set to 1%. The total transaction fee when transfering 100 token X will be 2 + 1% * 100 = 3 token X, total token subtracted from source account will be 100 token X, token owner receives 3 token X fee, target account receives 97 token X.
84+
- Lot: the minimum token amount to transfer in each transaction. It should be integer number with the range from 1 to 2^63 - 1
85+
- Conversion rate: The rate when users exchange UNW to token. This coversion rate is calculated by the number of token and number of UNW in Ginza unit. Please note that 1 UNW = 10^6 Ginza. For example: The *Token quantity = 1* and *Ginza quantity = 1000* (1 token for 0.001 UNW). If calling the exchange API with 10 UNW, users will get 10/0.001 = 10000 token.
86+
- Fee pool: The initial fee pool for token. Minimum value is 10 UNW (enough for 37453 transactions at the moment) and everyone can always contribute a token fee pool later.
87+
- Description: the brief description of the token
88+
89+
*Please note that the transaction fee for issuing token is 500 UNW*
90+
91+
### Transfer URC-30 token
92+
Transfer URC-30 token is just like transfer UNW.
93+
Users click on the *Send* button, choose a token to send and enter the receiver address, token amount then confirm and input the wallet address.
94+
If the *Send Future* is chosen, users must specify the *available time* of the token to be spent. The *Send Future* is the same as the lock function. Although token is in receivers wallet, they can only withdraw and use that token when after the *available time*
95+
![Transfer Token](../img/transfer_urc30_token.png)
96+
97+
To withdraw future token, users login to wallet and select the token on the *Future Token* drop box then click on *Withdraw* button.
98+
![Transfer Token](../img/future_urc30_token.png)
99+
100+
### Update URC-30 token
101+
Most of URC-30 token params can be updated except the token name, token abbreviation, max supply and start time.
102+
When a token is updated, It cannot be used in 180 seconds (users cannot transfer, contribute fee …). This amount of time informs users that some token parameters are changed and users may take a look at token information before transacting.
103+
To update a token: go to UniWallet, login, click to the Token Tool in the left panel then update the token. Please note that only token owners can perform this operation.
104+
105+
### Exchange URC-30 token
106+
Users can exchange (or buy) token by UNW.
107+
Step to exchange token on UniWallet:
108+
- Go to [UniWallet](https://uniwallet.world) and login
109+
- Click on Token Tool
110+
- Search for token you want to buy
111+
- Enter amount of UNW to buy then confirm and input wallet password
112+
![Exchange UNW token](../img/buy_urc30_token.png)
113+
114+
### Transfer token ownership
115+
Token owner’s account can be transferred to another account in many cases such as when the account is compromised or the developer completed the integration and transfer to the operation account … When token ownership is transferred, the transaction fee in terms of token is sent to the new account and only the new account can manage the token (update, burn, mint). Token will be suspended in 180 seconds to inform users from this operation.
116+
117+
### Interact with URC-30 token by APIs
118+
Developers can interact with URC-30 tokens by node’s APIs such as issue token, update token, exchange token, get token, transfer ownership …
119+
The full list API can be found here: [URC-30 APIs](fullNodeAPI#urc30-token)
120+
121+
## URC-20 Native Token : // TODO: NEED UPDATE
122+
URC-30 token is the native token on UniChain network. It has the same function as the URC-20 token but the big difference is that It does not based on smart contracts. Users can interact with the token by using APIs from blockchain nodes. Unlike URC-20 token, transferring URC-30 token does not require UNW as the transaction fee (gas). Instead, the transaction fee is from the token itself.
123+
The following picture describes how the transaction fee model in URC-30 works.
124+
125+
![URC-30 token fee](../img/urc30_token_fee.png)
126+
127+
Each URC-30 token has the token pool fee providing the transaction fee (in UNW) for all token transfer. The pool is initiated by the token owner and contributed by anyone. When user A transfers a token to user B, for example 100 token X, the following will occur:
128+
129+
- The pool fee of token X will be taken out for executing the transfer transaction. Currently, It costs about 0.000268 UNW
130+
- An amount of token X will be transfer to token owner, for example 1 token X
131+
- User B only receive 99 token X
132+
133+
The token owner can specify the transaction fee in terms of token to balance out with the UNW deposited to the token pool.
134+
135+
The basic functions of URC-30 token as below:
136+
- Create an URC-30 token
137+
- Transfer token from users to users
138+
- Transfer token for future uses (same as lock token)
139+
- Update token information
140+
- Exchange token with UNW
141+
- Mint token (increase the total supply)
142+
- Burnt token (decrease total supply)
143+
- Contribute fee to the token pool
144+
- Transfer ownership
145+
146+
### Issue URC-30 token on UniWallet
147+
Users can issue URC-30 tokens by using wallet-cli, APIs, SDK ... but the simplest way is to use [UniWallet](https://uniwallet.world).
148+
149+
<ul>
150+
<li>Step 1: Go to UniWallet website</li>
151+
<li>Step 2: Login to your wallet</li>
152+
<li>Step 3: Navigate to the Token Tool on the left panel and fill the token information</li>
153+
<li>Step 4: Sumbit and input your wallet password. A txid will be returned if everything is OK </li>
154+
</ul>
155+
156+
![Create URC-30 Token](../img/create_urc30_token.png)
157+
158+
The following describes the token params in details
159+
160+
- Token Name: The name of the token. The name must be unique, less than 32 human readable characters.
161+
- Abbr: Abbreviation of the token, Abbr should less than 32 human readable characters
162+
- Total supply: Total supply is the supply at the token creation. It should be integer number with the range from 1 to 2^63 - 1
163+
- Max supply: The maximum supply of the token. It should be integer number with the range from 1 to 2^63 -1
164+
- Start time: Start time is the time that token can be used. Token can be issued for future uses. - Date and time are from UTC timezone. The default value is now (token can be used after creation)
165+
- End time: End time is the time that token cannot be used. The default value is 50 years and maximum value is 200 years (from now)
166+
- Url: the url to website or information of token creators.
167+
- Extra fee rate: The extra fee rate is the transaction fee calculated in percentage of transferred amount. For example, if the extra fee rate is 1%, when transferring 100 token X from user A to user B, there will be 100 token X transferred from A to B, 1 token X will be transferred to the token creator. Value range of extra fee is from 0 - 100
168+
- Fee: The transaction fee for transferring a token regardless of token amount. Please note that the token transaction fee of transferring a token will be transaction fee and extra fee. For example, if the fee is set to 2, the extra fee rate is set to 1%. The total transaction fee when transfering 100 token X will be 2 + 1% * 100 = 3 token X, total token subtracted from source account will be 100 token X, token owner receives 3 token X fee, target account receives 97 token X.
169+
- Lot: the minimum token amount to transfer in each transaction. It should be integer number with the range from 1 to 2^63 - 1
170+
- Conversion rate: The rate when users exchange UNW to token. This coversion rate is calculated by the number of token and number of UNW in Ginza unit. Please note that 1 UNW = 10^6 Ginza. For example: The *Token quantity = 1* and *Ginza quantity = 1000* (1 token for 0.001 UNW). If calling the exchange API with 10 UNW, users will get 10/0.001 = 10000 token.
171+
- Fee pool: The initial fee pool for token. Minimum value is 10 UNW (enough for 37453 transactions at the moment) and everyone can always contribute a token fee pool later.
172+
- Description: the brief description of the token
173+
174+
*Please note that the transaction fee for issuing token is 500 UNW*
175+
176+
### Transfer URC-30 token
177+
Transfer URC-30 token is just like transfer UNW.
178+
Users click on the *Send* button, choose a token to send and enter the receiver address, token amount then confirm and input the wallet address.
179+
If the *Send Future* is chosen, users must specify the *available time* of the token to be spent. The *Send Future* is the same as the lock function. Although token is in receivers wallet, they can only withdraw and use that token when after the *available time*
180+
![Transfer Token](../img/transfer_urc30_token.png)
181+
182+
To withdraw future token, users login to wallet and select the token on the *Future Token* drop box then click on *Withdraw* button.
183+
![Transfer Token](../img/future_urc30_token.png)
184+
185+
### Update URC-30 token
186+
Most of URC-30 token params can be updated except the token name, token abbreviation, max supply and start time.
187+
When a token is updated, It cannot be used in 180 seconds (users cannot transfer, contribute fee …). This amount of time informs users that some token parameters are changed and users may take a look at token information before transacting.
188+
To update a token: go to UniWallet, login, click to the Token Tool in the left panel then update the token. Please note that only token owners can perform this operation.
189+
190+
### Exchange URC-30 token
191+
Users can exchange (or buy) token by UNW.
192+
Step to exchange token on UniWallet:
193+
- Go to [UniWallet](https://uniwallet.world) and login
194+
- Click on Token Tool
195+
- Search for token you want to buy
196+
- Enter amount of UNW to buy then confirm and input wallet password
197+
![Exchange UNW token](../img/buy_urc30_token.png)
198+
199+
### Transfer token ownership
200+
Token owner’s account can be transferred to another account in many cases such as when the account is compromised or the developer completed the integration and transfer to the operation account … When token ownership is transferred, the transaction fee in terms of token is sent to the new account and only the new account can manage the token (update, burn, mint). Token will be suspended in 180 seconds to inform users from this operation.
201+
202+
### Interact with URC-30 token by APIs
203+
Developers can interact with URC-30 tokens by node’s APIs such as issue token, update token, exchange token, get token, transfer ownership …
204+
The full list API can be found here: [URC-30 APIs](fullNodeAPI#urc30-token)
205+
206+
## URC-721 Native Token : // TODO: NEED UPDATE
37207
URC-30 token is the native token on UniChain network. It has the same function as the URC-20 token but the big difference is that It does not based on smart contracts. Users can interact with the token by using APIs from blockchain nodes. Unlike URC-20 token, transferring URC-30 token does not require UNW as the transaction fee (gas). Instead, the transaction fee is from the token itself.
38208
The following picture describes how the transaction fee model in URC-30 works.
39209

0 commit comments

Comments
 (0)