[first FA] moon coin tutorial (aptos-labs#8830)

Author: lightmark

aptos-move/move-examples/fungible_asset/README.md

@@ -3,7 +3,6 @@
 * Managed fungible asset: A full-fledged fungible asset with customizable management capabilities and associated functions, based on which a light example is provided to show how to issue coin.
     - Coin example: a light example showing how to issue coin based on managed fungible asset.
 * Managed fungible token: A fungible token example that adds token resource to the metadata object.
-* Managed fungible asset: a full-fledged fungible asset with customizable management capabilities and associated functions.
-* Simple managed coin: an all-in-one module implementing managed coin using fungible asset with limited functionalities (only deal with primary fungible stores).
 * Pre-minted managed coin: an example issuing pre-minting coin based on managed fungible asset.
-* Multisig managed coin: how to use multisig account to manage fungible assets.
+* Multisig managed coin: how to use multisig account to manage fungible assets.
+* FA coin: an all-in-one module coin example using manged fungible asset with limited functionalities (only deal with primary fungible stores).

aptos-move/move-examples/fungible_asset/simple_managed_coin/Move.toml renamed to aptos-move/move-examples/fungible_asset/fa_coin/Move.toml

@@ -1,10 +1,10 @@
 [package]
-name = "SimpleManagedCoin"
+name = "Examples"
 version = "0.0.0"
 
 [addresses]
 aptos_framework = "0x1"
-example_addr = "_"
+FACoin = "_"
 
 [dependencies]
 AptosFramework = { local = "../../../framework/aptos-framework" }

aptos-move/move-examples/fungible_asset/simple_managed_coin/sources/simple_managed_coin.move renamed to aptos-move/move-examples/fungible_asset/fa_coin/sources/FACoin.move

@@ -1,7 +1,7 @@
 /// A 2-in-1 module that combines managed_fungible_asset and coin_example into one module that when deployed, the
 /// deployer will be creating a new managed fungible asset with the hardcoded supply config, name, symbol, and decimals.
 /// The address of the asset can be obtained via get_metadata(). As a simple version, it only deal with primary stores.
-module example_addr::simple_managed_coin {
+module FACoin::fa_coin {
     use aptos_framework::fungible_asset::{Self, MintRef, TransferRef, BurnRef, Metadata, FungibleAsset};
     use aptos_framework::object::{Self, Object};
     use aptos_framework::primary_fungible_store;
@@ -13,7 +13,7 @@ module example_addr::simple_managed_coin {
     /// Only fungible asset metadata owner can make changes.
     const ENOT_OWNER: u64 = 1;
 
-    const ASSET_SYMBOL: vector<u8> = b"LBR";
+    const ASSET_SYMBOL: vector<u8> = b"FA";
 
     #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
     /// Hold refs to control the minting, transfer and burning of fungible assets.
@@ -24,12 +24,13 @@ module example_addr::simple_managed_coin {
     }
 
     /// Initialize metadata object and store the refs.
+    // :!:>initialize
     fun init_module(admin: &signer) {
         let constructor_ref = &object::create_named_object(admin, ASSET_SYMBOL);
         primary_fungible_store::create_primary_store_enabled_fungible_asset(
             constructor_ref,
             option::none(),
-            utf8(b"Libra Coin"), /* name */
+            utf8(b"FA Coin"), /* name */
             utf8(ASSET_SYMBOL), /* symbol */
             8, /* decimals */
             utf8(b"http://example.com/favicon.ico"), /* icon */
@@ -44,24 +45,25 @@ module example_addr::simple_managed_coin {
         move_to(
             &metadata_object_signer,
             ManagedFungibleAsset { mint_ref, transfer_ref, burn_ref }
-        )
+        )// <:!:initialize
     }
 
     #[view]
     /// Return the address of the managed fungible asset that's created when this module is deployed.
     public fun get_metadata(): Object<Metadata> {
-        let asset_address = object::create_object_address(&@example_addr, ASSET_SYMBOL);
+        let asset_address = object::create_object_address(&@FACoin, ASSET_SYMBOL);
         object::address_to_object<Metadata>(asset_address)
     }
 
+    // :!:>mint
     /// Mint as the owner of metadata object.
-    public entry fun mint(admin: &signer, amount: u64, to: address) acquires ManagedFungibleAsset {
+    public entry fun mint(admin: &signer, to: address, amount: u64) acquires ManagedFungibleAsset {
         let asset = get_metadata();
         let managed_fungible_asset = authorized_borrow_refs(admin, asset);
         let to_wallet = primary_fungible_store::ensure_primary_store_exists(to, asset);
         let fa = fungible_asset::mint(&managed_fungible_asset.mint_ref, amount);
         fungible_asset::deposit_with_ref(&managed_fungible_asset.transfer_ref, to_wallet, fa);
-    }
+    }// <:!:mint
 
     /// Transfer as the owner of metadata object ignoring `frozen` field.
     public entry fun transfer(admin: &signer, from: address, to: address, amount: u64) acquires ManagedFungibleAsset {
@@ -88,7 +90,7 @@ module example_addr::simple_managed_coin {
         fungible_asset::set_frozen_flag(transfer_ref, wallet, true);
     }
 
-    /// Unfreeze an account so it can transfer or receive fungible assets.
+    /// Freeze an account so it cannot transfer or receive fungible assets.
     public entry fun unfreeze_account(admin: &signer, account: address) acquires ManagedFungibleAsset {
         let asset = get_metadata();
         let transfer_ref = &authorized_borrow_refs(admin, asset).transfer_ref;
@@ -122,15 +124,15 @@ module example_addr::simple_managed_coin {
         borrow_global<ManagedFungibleAsset>(object::object_address(&asset))
     }
 
-    #[test(creator = @example_addr)]
+    #[test(creator = @FACoin)]
     fun test_basic_flow(
         creator: &signer,
     ) acquires ManagedFungibleAsset {
         init_module(creator);
         let creator_address = signer::address_of(creator);
         let aaron_address = @0xface;
 
-        mint(creator, 100, creator_address);
+        mint(creator, creator_address, 100);
         let asset = get_metadata();
         assert!(primary_fungible_store::balance(creator_address, asset) == 100, 4);
         freeze_account(creator, creator_address);
@@ -143,14 +145,14 @@ module example_addr::simple_managed_coin {
         burn(creator, creator_address, 90);
     }
 
-    #[test(creator = @example_addr, aaron = @0xface)]
+    #[test(creator = @FACoin, aaron = @0xface)]
     #[expected_failure(abort_code = 0x50001, location = Self)]
     fun test_permission_denied(
         creator: &signer,
         aaron: &signer
     ) acquires ManagedFungibleAsset {
         init_module(creator);
         let creator_address = signer::address_of(creator);
-        mint(aaron, 100, creator_address);
+        mint(aaron, creator_address, 100);
     }
 }

aptos-move/move-examples/tests/move_unit_tests.rs

@@ -112,10 +112,16 @@ fn test_message_board() {
 
 #[test]
 fn test_fungible_asset() {
-    let named_address = BTreeMap::from([(
-        String::from("example_addr"),
-        AccountAddress::from_hex_literal("0xcafe").unwrap(),
-    )]);
+    let named_address = BTreeMap::from([
+        (
+            String::from("example_addr"),
+            AccountAddress::from_hex_literal("0xcafe").unwrap(),
+        ),
+        (
+            String::from("FACoin"),
+            AccountAddress::from_hex_literal("0xcafe").unwrap(),
+        ),
+    ]);
     run_tests_for_pkg(
         "fungible_asset/managed_fungible_asset",
         named_address.clone(),
@@ -128,7 +134,7 @@ fn test_fungible_asset() {
         "fungible_asset/preminted_managed_coin",
         named_address.clone(),
     );
-    run_tests_for_pkg("fungible_asset/simple_managed_coin", named_address);
+    run_tests_for_pkg("fungible_asset/fa_coin", named_address);
 }
 
 #[test]