-
Notifications
You must be signed in to change notification settings - Fork 11.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] Coin standard (new) and token standard (updates) (#16046)
## Description Creates a Coin standard page. Includes edits for closed-loop token and other content edits to better align terminology. Also includes plug-in for Docusaurus. ## Test Plan How did you test the new or updated feature? --- If your changes are not user-facing and do not break anything, you can skip the following section. Otherwise, please briefly describe what has changed under the Release Notes section. ### Type of Change (Check all that apply) - [ ] protocol change - [ ] user-visible impact - [ ] breaking change for a client SDKs - [ ] breaking change for FNs (FN binary must upgrade) - [ ] breaking change for validators or node operators (must upgrade binaries) - [ ] breaking change for on-chain data layout - [ ] necessitate either a data wipe or data migration ### Release notes
- Loading branch information
1 parent
cbf3c9c
commit 1f84041
Showing
27 changed files
with
905 additions
and
337 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| --- | ||
| title: SUI Coin | ||
| description: The native asset on Sui is called SUI. The coin uses the capitalized version of SUI to distinguish the coin from the Sui network. | ||
| --- | ||
|
|
||
| The native asset on Sui is called SUI. The coin uses the capitalized version of SUI to distinguish the coin from the Sui network. | ||
|
|
||
| The total supply of SUI is capped at **10,000,000,000** (ten billion coins). A share of SUI total supply became liquid at Mainnet launch, with the remaining coins vesting over the coming years, or distributed as future stake reward subsidies. | ||
|
|
||
| The SUI coin serves four purposes on the Sui network: | ||
|
|
||
| - You can stake SUI to participate in the proof-of-stake mechanism. | ||
| - SUI is the asset denomination needed to pay the gas fees required to execute and store transactions or other operations on the Sui network. | ||
| - You can use SUI as a versatile and liquid asset for various applications, including the standard features of money - a unit of account, a medium of exchange, or a store of value - and more complex functionality smart contracts enable, interoperability, and composability across the Sui ecosystem. | ||
| - SUI coins play an important role in governance by acting as a right to participate in on-chain voting on issues such as protocol upgrades. | ||
|
|
||
| There is a finite supply of SUI. The balance must support all economic activities to scale as more and more people migrate to the Sui platform. In addition, the presence of a storage fund creates important monetary dynamics, in that higher on-chain data requirements translate into a larger storage fund, reducing the amount of SUI in circulation. |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
140 changes: 140 additions & 0 deletions
140
docs/content/guides/developer/sui-101/create-coin/in-game-token.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| --- | ||
| title: In-Game Currency | ||
| --- | ||
|
|
||
| Using the Sui [Closed-Loop Token](../../../../standards/closed-loop-token.mdx) standard, you can create in-game currency (such as gems or diamonds in mobile games) that you can grant to players for their actions or make available to purchase. You mint the tokens on Sui, but players can only use the tokens within the economy of the game itself. These types of tokens are usually not transferrable and you would typically mint them in predefined amounts to maintain scarcity and game balance. | ||
|
|
||
| The following example creates an in-game currency called a GEM, which represents a certain number of SUI. In the example, the user can buy fungible GEMs using SUI, which can then be used as currency within the game. Use the code comments to follow the logic of the example. | ||
|
|
||
| ```move title="sui/examples/move/token/sources/gems.move" | ||
| /// This is a simple example of a permissionless module for an imaginary game | ||
| /// that sells swords for Gems. Gems are an in-game currency that can be bought | ||
| /// with SUI. | ||
| module examples::sword { | ||
| use sui::tx_context::TxContext; | ||
| use sui::object::{Self, UID}; | ||
| use sui::token::{Self, Token, ActionRequest}; | ||
| use examples::gem::GEM; | ||
| /// Trying to purchase a sword with an incorrect amount. | ||
| const EWrongAmount: u64 = 0; | ||
| /// The price of a sword in Gems. | ||
| const SWORD_PRICE: u64 = 10; | ||
| /// A game item that can be purchased with Gems. | ||
| struct Sword has key, store { id: UID } | ||
| /// Purchase a sword with Gems. | ||
| public fun buy_sword( | ||
| gems: Token<GEM>, ctx: &mut TxContext | ||
| ): (Sword, ActionRequest<GEM>) { | ||
| assert!(SWORD_PRICE == token::value(&gems), EWrongAmount); | ||
| ( | ||
| Sword { id: object::new(ctx) }, | ||
| token::spend(gems, ctx) | ||
| ) | ||
| } | ||
| } | ||
| /// Module that defines the in-game currency: GEMs which can be purchased with | ||
| /// SUI and used to buy swords (in the `sword` module). | ||
| module examples::gem { | ||
| use std::option::none; | ||
| use std::string::{Self, String}; | ||
| use sui::sui::SUI; | ||
| use sui::transfer; | ||
| use sui::object::{Self, UID}; | ||
| use sui::balance::{Self, Balance}; | ||
| use sui::tx_context::{sender, TxContext}; | ||
| use sui::coin::{Self, Coin, TreasuryCap}; | ||
| use sui::token::{Self, Token, ActionRequest}; | ||
| /// Trying to purchase Gems with an unexpected amount. | ||
| const EUnknownAmount: u64 = 0; | ||
| /// 10 SUI is the price of a small bundle of Gems. | ||
| const SMALL_BUNDLE: u64 = 10_000_000_000; | ||
| const SMALL_AMOUNT: u64 = 100; | ||
| /// 100 SUI is the price of a medium bundle of Gems. | ||
| const MEDIUM_BUNDLE: u64 = 100_000_000_000; | ||
| const MEDIUM_AMOUNT: u64 = 5_000; | ||
| /// 1000 SUI is the price of a large bundle of Gems. | ||
| /// This is the best deal. | ||
| const LARGE_BUNDLE: u64 = 1_000_000_000_000; | ||
| const LARGE_AMOUNT: u64 = 100_000; | ||
| #[allow(lint(coin_field))] | ||
| /// Gems can be purchased through the `Store`. | ||
| struct GemStore has key { | ||
| id: UID, | ||
| /// Profits from selling Gems. | ||
| profits: Balance<SUI>, | ||
| /// The Treasury Cap for the in-game currency. | ||
| gem_treasury: TreasuryCap<GEM>, | ||
| } | ||
| /// The OTW to create the in-game currency. | ||
| struct GEM has drop {} | ||
| // In the module initializer we create the in-game currency and define the | ||
| // rules for different types of actions. | ||
| fun init(otw: GEM, ctx: &mut TxContext) { | ||
| let (treasury_cap, coin_metadata) = coin::create_currency( | ||
| otw, 0, b"GEM", b"Capy Gems", // otw, decimal, symbol, name | ||
| b"In-game currency for Capy Miners", none(), // description, url | ||
| ctx | ||
| ); | ||
| // create a `TokenPolicy` for GEMs | ||
| let (policy, cap) = token::new_policy(&treasury_cap, ctx); | ||
| token::allow(&mut policy, &cap, buy_action(), ctx); | ||
| token::allow(&mut policy, &cap, token::spend_action(), ctx); | ||
| // create and share the GemStore | ||
| transfer::share_object(GemStore { | ||
| id: object::new(ctx), | ||
| gem_treasury: treasury_cap, | ||
| profits: balance::zero() | ||
| }); | ||
| // deal with `TokenPolicy`, `CoinMetadata` and `TokenPolicyCap` | ||
| transfer::public_freeze_object(coin_metadata); | ||
| transfer::public_transfer(cap, sender(ctx)); | ||
| token::share_policy(policy); | ||
| } | ||
| /// Purchase Gems from the GemStore. Very silly value matching against module | ||
| /// constants... | ||
| public fun buy_gems( | ||
| self: &mut GemStore, payment: Coin<SUI>, ctx: &mut TxContext | ||
| ): (Token<GEM>, ActionRequest<GEM>) { | ||
| let amount = coin::value(&payment); | ||
| let purchased = if (amount == SMALL_BUNDLE) { | ||
| SMALL_AMOUNT | ||
| } else if (amount == MEDIUM_BUNDLE) { | ||
| MEDIUM_AMOUNT | ||
| } else if (amount == LARGE_BUNDLE) { | ||
| LARGE_AMOUNT | ||
| } else { | ||
| abort EUnknownAmount | ||
| }; | ||
| coin::put(&mut self.profits, payment); | ||
| // create custom request and mint some Gems | ||
| let gems = token::mint(&mut self.gem_treasury, purchased, ctx); | ||
| let req = token::new_request(buy_action(), purchased, none(), none(), ctx); | ||
| (gems, req) | ||
| } | ||
| /// The name of the `buy` action in the `GemStore`. | ||
| public fun buy_action(): String { string::utf8(b"buy") } | ||
| } | ||
| ``` |
Oops, something went wrong.