[framework] Emits coin::CreatedCurrency metadata + compiles book exam…

…ples (MystenLabs#4558)

* compiles book examples
* coin::CreatedCurrency added
* tip to regenerate expectations in sui-cost

crates/sui-core/src/unit_tests/data/hero/sources/trusted_coin.move

@@ -16,7 +16,7 @@ module examples::trusted_coin {
     fun init(ctx: &mut TxContext) {
         // Get a treasury cap for the coin and give it to the transaction
         // sender
-        let treasury_cap = coin::create_currency<EXAMPLE>(EXAMPLE{}, ctx);
+        let treasury_cap = coin::create_currency<EXAMPLE>(EXAMPLE{}, 2, ctx);
         transfer::transfer(treasury_cap, tx_context::sender(ctx))
     }
 

crates/sui-cost/tests/calibration.rs

@@ -12,7 +12,7 @@ const TEST_MODULE_DATA_DIR: &str = "../sui-framework/tests";
 
 // Execute every entry function in Move framework and examples and ensure costs don't change
 // To review snapshot changes, and fix snapshot differences,
-// 0. Install cargo-insta
+// 0. Install cargo-insta (`cargo install cargo-insta`)
 // 1. Run `cargo insta test --review` under `./sui-cost`.
 // 2. Review, accept or reject changes.
 

crates/sui-cost/tests/data/dummy_modules_publish/sources/trusted_coin.move

@@ -16,7 +16,7 @@ module examples::trusted_coin {
     fun init(witness: TRUSTED_COIN, ctx: &mut TxContext) {
         // Get a treasury cap for the coin and give it to the transaction
         // sender
-        let treasury_cap = coin::create_currency<TRUSTED_COIN>(witness, ctx);
+        let treasury_cap = coin::create_currency<TRUSTED_COIN>(witness, 2, ctx);
         transfer::transfer(treasury_cap, tx_context::sender(ctx))
     }
 

crates/sui-cost/tests/snapshots/empirical_transaction_cost__good_snapshot.snap

@@ -4,12 +4,12 @@ expression: common_costs
 ---
 {
   "MergeCoin": {
-    "computation_cost": 483,
+    "computation_cost": 486,
     "storage_cost": 32,
     "storage_rebate": 0
   },
   "Publish": {
-    "computation_cost": 541,
+    "computation_cost": 547,
     "storage_cost": 83,
     "storage_rebate": 0
   },
@@ -29,7 +29,7 @@ expression: common_costs
     "storage_rebate": 15
   },
   "SplitCoin": {
-    "computation_cost": 594,
+    "computation_cost": 596,
     "storage_cost": 80,
     "storage_rebate": 0
   },

crates/sui-cost/troubleshooting.md

@@ -0,0 +1,13 @@
+# Troubleshooting
+
+## Sui Framework change
+
+If Sui framework code got updated, the expectations need to be changed. Follow these steps:
+
+```bash
+# required; can be omitted if cargo-insta is installed
+$ cargo install cargo-insta
+
+# run in ./sui-cost
+$ cargo insta test --review
+```

crates/sui-framework/sources/coin.move

@@ -9,6 +9,7 @@ module sui::coin {
     use sui::object::{Self, UID};
     use sui::transfer;
     use sui::tx_context::{Self, TxContext};
+    use sui::event;
     use std::vector;
 
     /// For when a type passed to create_supply is not a one-time witness.
@@ -33,6 +34,19 @@ module sui::coin {
         total_supply: Supply<T>
     }
 
+    // === Events ===
+
+    /// Emitted when new currency is created through the `create_currency` call.
+    /// Contains currency metadata for off-chain discovery. Type parameter `T`
+    /// matches the one in `Coin<T>`
+    struct CurrencyCreated<phantom T> has copy, drop {
+        /// Number of decimal places the coin uses. 
+        /// A coin with `value ` N and `decimals` D should be shown as N / 10^D
+        /// E.g., a coin with `value` 7002 and decimals 3 should be displayed as 7.002
+        /// This is metadata for display usage only.
+        decimals: u8
+    }
+
     // === Supply <-> TreasuryCap morphing and accessors  ===
 
     /// Return the total number of `T`'s in circulation.
@@ -153,11 +167,17 @@ module sui::coin {
     /// type, ensuring that there's only one `TreasuryCap` per `T`.
     public fun create_currency<T: drop>(
         witness: T,
+        decimals: u8,
         ctx: &mut TxContext
     ): TreasuryCap<T> {
         // Make sure there's only one instance of the type T
         assert!(sui::types::is_one_time_witness(&witness), EBadWitness);
 
+        // Emit Currency metadata as an event.
+        event::emit(CurrencyCreated<T> {
+            decimals
+        });
+
         TreasuryCap {
             id: object::new(ctx),
             total_supply: balance::create_supply(witness)

crates/sui-framework/sources/governance/genesis.move

@@ -38,7 +38,7 @@ module sui::genesis {
         validator_gas_prices: vector<u64>,
         ctx: &mut TxContext,
     ) {
-        let sui_supply = sui::new();
+        let sui_supply = sui::new(ctx);
         let storage_fund = balance::increase_supply(&mut sui_supply, INIT_STORAGE_FUND);
         let validators = vector::empty();
         let count = vector::length(&validator_pubkeys);
@@ -63,7 +63,7 @@ module sui::genesis {
             vector::push_back(&mut validators, validator::new(
                 sui_address,
                 pubkey,
-                network_pubkey, 
+                network_pubkey,
                 proof_of_possession,
                 name,
                 net_address,

crates/sui-framework/sources/sui.move

@@ -1,21 +1,25 @@
 // Copyright (c) 2022, Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-/// Coin<SUI> is the token used to pay for gas in Sui
+/// Coin<SUI> is the token used to pay for gas in Sui.
+/// It has 9 decimals, and the smallest unit (10^-9) is called "mist".
 module sui::sui {
-    use sui::balance::{Self, Supply};
-    use sui::coin;
+    use sui::tx_context::TxContext;
+    use sui::balance::Supply;
     use sui::transfer;
+    use sui::coin;
 
     friend sui::genesis;
 
     /// Name of the coin
     struct SUI has drop {}
 
-    /// Register the token to acquire its `TreasuryCap`.
+    /// Register the `SUI` Coin to acquire its `Supply`.
     /// This should be called only once during genesis creation.
-    public(friend) fun new(): Supply<SUI> {
-        balance::create_supply(SUI {})
+    public(friend) fun new(ctx: &mut TxContext): Supply<SUI> {
+        coin::treasury_into_supply(
+            coin::create_currency(SUI {}, 9, ctx)
+        )
     }
 
     public entry fun transfer(c: coin::Coin<SUI>, recipient: address) {

crates/sui-framework/src/lib.rs

@@ -266,4 +266,13 @@ mod tests {
             run_move_unit_tests(&path, BuildConfig::default(), None, false).unwrap();
         }
     }
+
+    #[test]
+    #[cfg_attr(msim, ignore)]
+    fn run_book_examples_move_unit_tests() {
+        let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../doc/book/examples");
+
+        build_and_verify_package(&path, BuildConfig::default()).unwrap();
+        run_move_unit_tests(&path, BuildConfig::default(), None, false).unwrap();
+    }
 }

crates/sui/src/unit_tests/data/dummy_modules_publish/sources/trusted_coin.move

@@ -16,7 +16,7 @@ module examples::trusted_coin {
     fun init(witness: TRUSTED_COIN, ctx: &mut TxContext) {
         // Get a treasury cap for the coin and give it to the transaction
         // sender
-        let treasury_cap = coin::create_currency<TRUSTED_COIN>(witness, ctx);
+        let treasury_cap = coin::create_currency<TRUSTED_COIN>(witness, 2, ctx);
         transfer::transfer(treasury_cap, tx_context::sender(ctx))
     }
 

doc/book/examples/Move.toml

@@ -3,7 +3,7 @@ name = "sui-by-example"
 version = "0.1.0"
 
 [dependencies]
-Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework", rev = "main" }
+Sui = { local = "../../../crates/sui-framework" }
 
 [addresses]
 examples = "0x0"

doc/book/examples/Move.toml.example

@@ -0,0 +1,9 @@
+[package]
+name = "sui-by-example"
+version = "0.1.0"
+
+[dependencies]
+Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework", rev = "main" }
+
+[addresses]
+examples = "0x0"

doc/book/examples/sources/samples/coin.move

@@ -15,7 +15,8 @@ module examples::mycoin {
     /// cap is sent to the publisher, who then controls minting and burning
     fun init(witness: MYCOIN, ctx: &mut TxContext) {
         transfer::transfer(
-            coin::create_currency(witness, ctx),
+            // second parameter defines decimals of the Coin: 6
+            coin::create_currency(witness, 6, ctx),
             tx_context::sender(ctx)
         )
     }

doc/book/src/basics/move-toml.md

@@ -7,5 +7,5 @@ Every Move package has a *package manifest* in the form of a `Move.toml` file -
 - `[addresses]` - address aliases (eg `@me` will be treated as a `0x0` address)
 
 ```toml
-{{#include ../../examples/Move.toml}}
+{{#include ../../examples/Move.toml.example}}
 ```

sui_programmability/examples/fungible_tokens/sources/managed.move

@@ -18,7 +18,7 @@ module fungible_tokens::managed {
     /// registered once.
     fun init(witness: MANAGED, ctx: &mut TxContext) {
         // Get a treasury cap for the coin and give it to the transaction sender
-        let treasury_cap = coin::create_currency<MANAGED>(witness, ctx);
+        let treasury_cap = coin::create_currency<MANAGED>(witness, 2, ctx);
         transfer::transfer(treasury_cap, tx_context::sender(ctx))
     }