From b40a3cb7d2a9ad2ce864d09f204f2c9beee64d7b Mon Sep 17 00:00:00 2001 From: Karlo <88337245+Rqnsom@users.noreply.github.com> Date: Wed, 22 May 2024 16:13:16 +0200 Subject: [PATCH] doc: small updates - fixes for broken url and wrong info --- doc/final-design.md | 8 ++++++-- doc/gas-handling.md | 6 ------ doc/stdlib-doc.md | 19 ++++++++++--------- doc/tech_guide.md | 11 ++++++----- doc/tutorial-multi-signer.md | 4 +++- doc/tutorial.md | 17 +++++++++++++---- .../assets/move-projects/smove-clean-all.sh | 3 +-- pallet/src/mock_utils.rs | 2 +- 8 files changed, 40 insertions(+), 30 deletions(-) diff --git a/doc/final-design.md b/doc/final-design.md index 1407b88..7f37136 100644 --- a/doc/final-design.md +++ b/doc/final-design.md @@ -14,7 +14,7 @@ This article discusses the pallet-move functionality. MoveVM scripts and modules are not allowed to run forever - therefore, the `gas` value is used for that purpose. The provided `gas` gets converted to `Weight`, a mechanism that prevents extriniscs from running forever. The script execution is an atomic operation - if the provided gas is insufficient, the MoveVM within the pallet will reject the script, and no changes shall occur - but the user will pay for the used weight anyway. So, using the gas estimation RPC method is well recommended. -Scripts and modules have limited access to the balance transfer functionality via the `cheque_amount` parameter - the maximum amount of balance the account scripts can transfer from the signer of the extrinsic. +Scripts and modules have limited access to the balance transfer functionality via the `cheque_limit` parameter - the maximum amount of balance the account scripts can transfer from the signer of the extrinsic. ## Extrinsics @@ -69,6 +69,8 @@ Scripts and modules have limited access to the balance transfer functionality vi ## RPC +To quickly access these RPC methods above, it is recommended to use `smove node rpc` set of subcommands. + ### Method `mvm_estimateGasPublishModule` Estimate gas and weight cost for publishing a module. @@ -182,4 +184,6 @@ After each signer has signed by calling the exact same extrinsic call with the s - If all signatures are collected and then the script execution fails (e.g. because of insufficient cheque amount), no change will take place in the MoveVM storage / balance. The only way to re-execute the script is to restart the request and try to collect all signatures once again. - The signer order doesn't matter (it is independent of the order of the script function arguments). - If the script function argument list has a signer in multiple places in the argument list, this signer (user) has to sign the script only once. -- _TODO (Eiger): Add information about gas usage._ +- Only the last signer must provide the `gas_limit` value necessary for execution within the MoveVM. All previous signers can set the `gas_limit` value to zero since the script won't start\the execution until all signatures are collected. + +We recommend you review our quick multi-signer [tutorial](tutorial-multi-signer.md) for more practical info. diff --git a/doc/gas-handling.md b/doc/gas-handling.md index 792355e..8df7130 100644 --- a/doc/gas-handling.md +++ b/doc/gas-handling.md @@ -45,9 +45,3 @@ To better understand the costs, it's best to use the estimation RPC methods. > The same amount of `gas_limit` between different extrinsic doesn't necessarily add the equal weight cost. Future pallet users should monitor and observe gas handling costs once the pallet gets integrated into the actual blockchain and then recalibrate it according to their needs, if necessary, according to the info above. - -[move-stdlib]: https://github.com/eigerco/substrate-move/tree/main/language/move-stdlib -[substrate-move]: https://github.com/eigerco/substrate-move -[substrate-stdlib]: https://github.com/eigerco/substrate-stdlib -[native-fn]: https://move-language.github.io/move/functions.html?highlight=native#native-functions -[smove]: https://github.com/eigerco/smove diff --git a/doc/stdlib-doc.md b/doc/stdlib-doc.md index 9cea2e1..25c8380 100644 --- a/doc/stdlib-doc.md +++ b/doc/stdlib-doc.md @@ -4,8 +4,8 @@ The standard library provides a set of common modules that should be available t All modules within the standard library are published under the special account address `0x01` in the Move storage. The standard library is contained in two repositories: - - [`move-stdlib`](move-stdlib) - commonly known set of standard library modules that can be found across all Move compatible ecosystems. - - [`substrate-stdlib`](substrate-stdlib) - an extended standard library which contains Substrate-specific modules or any module that might be required for specific pallet-move use cases. + - [`move-stdlib`][move-stdlib] - commonly known set of standard library modules that can be found across all Move compatible ecosystems. + - [`substrate-stdlib`][substrate-stdlib] - an extended standard library which contains Substrate-specific modules or any module that might be required for specific pallet-move use cases. If the pallet users want to extend the standard library, we recommend adding new modules to the `subtrate-stdlib` repository to keep the original `move-stdlib` small and simple. @@ -14,33 +14,34 @@ Any new modules can be easily added once the end goal for the pallet user is cle In the following chapters, one can find a set of instructions that can be used to update the standard library when there is a clear need to do so. -Before we delve into the next two chapters, we should mention the special kind of functions called [native functions](native-fn). +Before we delve into the next two chapters, we should mention the special kind of functions called [native functions][native-fn]. These functions don't have a regular function body specified in Move source files like normal functions have, but instead, their implementation is integrated within the MoveVM itself. Native functions are only allowed in standard libraries, as updating them requires updating the MoveVM source code itself. -## Updates adding new Move source code modules +## Move Modules Updates Adding new modules to the standard library is pretty simple. Add a module to the wanted repository and then build it as a bundle with `smove bundle` and also generate doc files with `smove docgen`. If the standard library needs to be updated in post-genesis block settings, the `update_stdlib_bundle` extrinsic can achieve this. +Check usage instructions in the [tech guide](./tech_guide.md#update-standard-libraries). Note: This extrinsic can be used only by the root user. A simple example can be found in this [pull request](https://github.com/eigerco/move-stdlib/pull/5). -## Updates that add native functions +## Native Function Updates Adding new native functions to the standard library requires the implementation of a function body in Rust within the MoveVM code. You can use these PRs as an example of how that can be done: - - in [`substrate-move`](substrate-move): [feat: add native functions for substrate_hash module](https://github.com/eigerco/substrate-move/pull/83) - - in [`substrate-stdlib`](substrate-stdlib): [feat: add new hash module with native functions](https://github.com/eigerco/substrate-stdlib/pull/4) + - in [`substrate-move`][substrate-move]: [feat: add native functions for substrate_hash module](https://github.com/eigerco/substrate-move/pull/83) + - in [`substrate-stdlib`][substrate-stdlib]: [feat: add new hash module with native functions](https://github.com/eigerco/substrate-stdlib/pull/4) -Whenever native functions are added, [smove](smove) needs to update dependencies so it fetches the latest MoveVM changes and then a new version of `smove` should be published. +Whenever native functions are added, [smove][smove] needs to update dependencies so it fetches the latest MoveVM changes and then a new version of `smove` should be published. Hopefully, pallet users won't need to add new native functions after the genesis block, otherwise the node's runtime will require an update containing the new version of the MoveVM instance with the latest code that includes added native functions. -[move-stdlib]: https://github.com/eigerco/substrate-move/tree/main/language/move-stdlib +[move-stdlib]: https://github.com/eigerco/move-stdlib [substrate-move]: https://github.com/eigerco/substrate-move [substrate-stdlib]: https://github.com/eigerco/substrate-stdlib [native-fn]: https://move-language.github.io/move/functions.html?highlight=native#native-functions diff --git a/doc/tech_guide.md b/doc/tech_guide.md index b8db7f8..8c3a339 100644 --- a/doc/tech_guide.md +++ b/doc/tech_guide.md @@ -102,7 +102,7 @@ impl pallet_move::Config for Test { The pallet provides three extrinsic calls. To find about those check the [design document](final-design.md). -Have a look at the [mockup implementation](https://github.com/eigerco/pallet-move/blob/main/tests/mock.rs) for further coding details, or check the crate's Rust documentation: +Have a look at the [mockup implementation](https://github.com/eigerco/pallet-move/blob/main/pallet/src/mock.rs) for further coding details, or check the crate's Rust documentation: ```bash cargo doc --open ``` @@ -166,14 +166,14 @@ All available options are in the [node template](https://docs.substrate.io/refer ## Update Standard Libraries Two standard libraries are provided for pallet-move at the genesis block creation: -- [`move-stdlib`](move-stdlib) - the normal Move standard library inherited from the Move repo. -- [`substrate-stdlib`](substrate-stdlib) - an extension of the standard library with additional modules - where some of those modules are also substrate-specific modules. +- [`move-stdlib`][move-stdlib] - the normal Move standard library inherited from the Move repo. +- [`substrate-stdlib`][substrate-stdlib] - an extension of the standard library with additional modules - where some of those modules are also substrate-specific modules. On rare occasions, those libraries can be updated after the genesis block creation by the root account. **WARNING: THIS CAN BREAK THE MOVE-VM ON-CHAIN STORAGE IF IT INTRODUCES BACKWARD INCOMPATIBLE CHANGES - BE CAREFUL WITH THIS OPERATION** After edits are prepared to the standard library Move packages, compile both bundles using `smove`: ```bash -smove bundle -p substrate-move/language/move-stdlib +smove bundle -p move-stdlib smove bundle -p substrate-stdlib ``` The two generated bundles will be located in the subfolders: @@ -183,7 +183,8 @@ The two generated bundles will be located in the subfolders: Use the extrinsic call `update_stdlib_bundle` as the sudo user to update both of them. ![Update Stdlib](assets/polkadot.js_update_stdlib.png) +For more info about the standard library, check the documentation [here](./stdlib-doc.md). -[move-stdlib]: https://github.com/eigerco/substrate-move/tree/main/language/move-stdlib +[move-stdlib]: https://github.com/eigerco/move-stdlib [substrate-move]: https://github.com/eigerco/substrate-move [substrate-stdlib]: https://github.com/eigerco/substrate-stdlib diff --git a/doc/tutorial-multi-signer.md b/doc/tutorial-multi-signer.md index acd2dd9..5a29b92 100644 --- a/doc/tutorial-multi-signer.md +++ b/doc/tutorial-multi-signer.md @@ -7,7 +7,7 @@ You have already done the [tutorial](tutorial.md) and you are familiar with publ ### Differences to a Single User Script Execution Again, the story starts with the developer, Bob, who publishes a module. -This time, it is the `Dorm.mv` module from our example move project [`multi-signer`](../pallet/srv/tests/assets/move-projects/multi-signer), which allows to rent apartments for groups of three students each. +This time, it is the `Dorm.mv` module from our example move project [`multi-signer`](../pallet/src/tests/assets/move-projects/multiple-signers), which allows to rent apartments for groups of three students each. We assumed that dorms with exactly three rooms are available and can only be rented with three students together. | ![polkadot.js_multisign_bob_publishes_module.png](assets/polkadot.js_multisign_bob_publishes_module.png) | |:--:| @@ -41,3 +41,5 @@ Here, the second was Dave, and the last one was Eve, who signed the extrinsic ca | _Events in a multi signer execution requests in [polkadot.js][polkadotjs]_ | We hope you liked this short introduction about multi-signer script executions. You can find a couple of details more on this more in the [tech guide](tech_guide.md). + +[polkadotjs]: https://polkadot.js.org/apps/ diff --git a/doc/tutorial.md b/doc/tutorial.md index 815475c..3f775fe 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -39,11 +39,11 @@ Prerequisites: - [Install smove](https://github.com/eigerco/smove). - Setup our template node with pallet-move integrated and run it in the background - the instructions can be found in our [tech guide](./tech_guide.md). - Either use [polkadot.js][polkadotjs] or run a local frontend for the node running in the background. -- Switch the current working directory to the code example directory in `pallet-move/tests/assets/move-projects/car-wash-example`. +- Switch the current working directory to the code example directory in `pallet-move/pallet/src/assets/move-projects/car-wash-example`. In our example, a simple car wash is modelized, where washing coins are used to control the usage of the car wash. Users can register, buy washing coins and use them to start the car wash. -For the sake of simplicity, we show here only the function headers of the Move module, the full module can be seen [here](https://github.com/eigerco/pallet-move/blob/main/tests/assets/move-projects/car-wash-example/sources/CarWash.move). +For the sake of simplicity, we show here only the function headers of the Move module, the full module can be seen [here](https://github.com/eigerco/pallet-move/blob/main/pallet/src/assets/move-projects/car-wash-example/sources/CarWash.move). ```move module DeveloperBob::CarWash { @@ -98,7 +98,11 @@ smove node rpc estimate-gas-publish-module --account-id 5FHneW46xGXgs5mUiveU4sbT The successful result will look like: ```sh -Estimated gas: Estimate (gas_used: 732, vm_status_code: EXECUTED) +Gas estimation: + used gas: 732 + total extrinsic weight cost with the above gas: + Weight { ref_time: 14633766974, proof_size: 13927 } + vm_status_code: EXECUTED ``` ### Publication @@ -159,7 +163,12 @@ smove node rpc estimate-gas-execute-script -s build/car-wash-example/script_tran ``` with response: ```sh -Estimated gas: Estimate (gas_used: 343, vm_status_code: EXECUTED) +car-wash-example git:(main) smove node rpc estimate-gas-execute-script -s build/car-wash-example/script_transactions/initial_coin_minting.mvt +Gas estimation: + used gas: 343 + total extrinsic weight cost with the above gas: + Weight { ref_time: 1989666170700, proof_size: 528716 + vm_status_code: EXECUTED ``` ### Execution diff --git a/pallet/src/assets/move-projects/smove-clean-all.sh b/pallet/src/assets/move-projects/smove-clean-all.sh index 75ca9ad..e708571 100755 --- a/pallet/src/assets/move-projects/smove-clean-all.sh +++ b/pallet/src/assets/move-projects/smove-clean-all.sh @@ -4,7 +4,6 @@ cd $(dirname $0) build_dir=( - # Modules "balance" "base58_smove_build" "car-wash-example" @@ -13,7 +12,7 @@ build_dir=( "move-basics" "multiple-signers" "signer-scripts" - # Bundles + "basic_coin" "prohibited-bundle" "testing-move-stdlib" "testing-substrate-stdlib" diff --git a/pallet/src/mock_utils.rs b/pallet/src/mock_utils.rs index 13f245a..97bb89d 100644 --- a/pallet/src/mock_utils.rs +++ b/pallet/src/mock_utils.rs @@ -79,7 +79,7 @@ mod tests_only { /// Can panic if the file doesn't exist. pub fn read_bytes(file_path: &str) -> Vec { std::fs::read(file_path) - .unwrap_or_else(|e| panic!("Can't read {file_path}: {e} - make sure you run pallet-move/tests/assets/move-projects/smove-build-all.sh")) + .unwrap_or_else(|e| panic!("Can't read {file_path}: {e} - make sure you run pallet-move/pallet/src/assets/move-projects/smove-build-all.sh")) } /// Reads a precompiled Move scripts from our assets directory.