From a09dc49fb6a8667fd61d3a9f8d1ccce114650518 Mon Sep 17 00:00:00 2001 From: deck Date: Wed, 10 Mar 2021 08:45:58 -0500 Subject: [PATCH 1/4] Merge develop into release/2.0.x --- CMakeLists.txt | 14 +- CONTRIBUTING.md | 22 +- README.md | 7 + contracts/CMakeLists.txt | 2 +- .../include/eosio.token/eosio.token.hpp | 8 +- contracts/eosio.token/src/eosio.token.cpp | 2 +- docker/buildContracts.sh | 2 +- docker/unit-test.sh | 4 +- docker/verifyInstallation.sh | 6 +- docs.json | 4 + ...d-and-deploy.md => 01_build-and-deploy.md} | 17 +- docs/01_key-concepts/01_system.md | 24 - docs/01_key-concepts/02_ram.md | 39 - docs/01_key-concepts/03_cpu.md | 10 - docs/01_key-concepts/04_net.md | 10 - docs/01_key-concepts/05_stake.md | 50 - docs/01_key-concepts/06_vote.md | 6 - ...w-to-create-issue-and-transfer-a-token.md} | 6 +- .../01_upgrading-the-eosio.system-contract.md | 229 ----- docs/04_guides/02_how-to-buy-ram.md | 28 - docs/04_guides/03_how-to-stake.md | 33 - docs/04_guides/04_how-to-vote.md | 35 - ...-a-multisig-transaction-with-eosio.msig.md | 188 ---- docs/04_guides/07_how-to-use-eosio.wrap.md | 971 ------------------ ...08_configure-use-powerup-resource-model.md | 271 ----- docs/index.md | 21 +- pipeline.jsonc | 4 + tests/CMakeLists.txt | 11 +- tests/contracts.hpp.in | 20 +- tests/main.cpp | 5 + 30 files changed, 80 insertions(+), 1969 deletions(-) rename docs/{03_build-and-deploy.md => 01_build-and-deploy.md} (50%) delete mode 100644 docs/01_key-concepts/01_system.md delete mode 100644 docs/01_key-concepts/02_ram.md delete mode 100644 docs/01_key-concepts/03_cpu.md delete mode 100644 docs/01_key-concepts/04_net.md delete mode 100644 docs/01_key-concepts/05_stake.md delete mode 100644 docs/01_key-concepts/06_vote.md rename docs/{04_guides/05_how-to-create-issue-and-transfer-a-token.md => 02_guides/01_how-to-create-issue-and-transfer-a-token.md} (94%) delete mode 100644 docs/04_guides/01_upgrading-the-eosio.system-contract.md delete mode 100644 docs/04_guides/02_how-to-buy-ram.md delete mode 100644 docs/04_guides/03_how-to-stake.md delete mode 100644 docs/04_guides/04_how-to-vote.md delete mode 100644 docs/04_guides/06_how-to-sign-a-multisig-transaction-with-eosio.msig.md delete mode 100644 docs/04_guides/07_how-to-use-eosio.wrap.md delete mode 100644 docs/04_guides/08_configure-use-powerup-resource-model.md diff --git a/CMakeLists.txt b/CMakeLists.txt index edc6e2ce..ddbee743 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,11 +1,11 @@ cmake_minimum_required(VERSION 3.5) -project(eosio_contracts) +project(eosio_token) -set(VERSION_MAJOR 1) -set(VERSION_MINOR 9) -set(VERSION_PATCH 2) -#set(VERSION_SUFFIX rc4) +set(VERSION_MAJOR 2) +set(VERSION_MINOR 0) +set(VERSION_PATCH 0) +set(VERSION_SUFFIX rc1) if (VERSION_SUFFIX) set(VERSION_FULL "${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}-${VERSION_SUFFIX}") @@ -17,7 +17,7 @@ include(ExternalProject) find_package(eosio.cdt) -message(STATUS "Building eosio.contracts v${VERSION_FULL}") +message(STATUS "Building eosio.token v${VERSION_FULL}") set(EOSIO_CDT_VERSION_MIN "1.8") set(EOSIO_CDT_VERSION_SOFT_MAX "1.8") @@ -82,7 +82,7 @@ if(BUILD_TESTS) ExternalProject_Add( contracts_unit_tests LIST_SEPARATOR | # Use the alternate list separator - CMAKE_ARGS -DCMAKE_BUILD_TYPE=${TEST_BUILD_TYPE} -DCMAKE_PREFIX_PATH=${TEST_PREFIX_PATH} -DCMAKE_FRAMEWORK_PATH=${TEST_FRAMEWORK_PATH} -DCMAKE_MODULE_PATH=${TEST_MODULE_PATH} -DEOSIO_ROOT=${EOSIO_ROOT} -DLLVM_DIR=${LLVM_DIR} -DBOOST_ROOT=${BOOST_ROOT} + CMAKE_ARGS -DCMAKE_BUILD_TYPE=${TEST_BUILD_TYPE} -DCMAKE_PREFIX_PATH=${TEST_PREFIX_PATH} -DCMAKE_FRAMEWORK_PATH=${TEST_FRAMEWORK_PATH} -DCMAKE_MODULE_PATH=${TEST_MODULE_PATH} -DEOSIO_ROOT=${EOSIO_ROOT} -DLLVM_DIR=${LLVM_DIR} -DBOOST_ROOT=${BOOST_ROOT} -DBUILD_TESTS_PINNED=${BUILD_TESTS_PINNED} -DEOSIO_DIR_PROMPT=${EOSIO_DIR_PROMPT} SOURCE_DIR ${CMAKE_SOURCE_DIR}/tests BINARY_DIR ${CMAKE_BINARY_DIR}/tests BUILD_ALWAYS 1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3413262..e5531c23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to eosio.contracts +# Contributing to eosio.token Interested in contributing? That's awesome! Here are some guidelines to get started quickly and easily: @@ -6,7 +6,7 @@ Interested in contributing? That's awesome! Here are some guidelines to get star - [Bug Reports](#bug-reports) - [Feature Requests](#feature-requests) - [Change Requests](#change-requests) -- [Working on eosio.contracts](#working-on-eosiocontracts) +- [Working on eosio.token](#working-on-eosio.token) - [Feature Branches](#feature-branches) - [Submitting Pull Requests](#submitting-pull-requests) - [Testing and Quality Assurance](#testing-and-quality-assurance) @@ -16,7 +16,7 @@ Interested in contributing? That's awesome! Here are some guidelines to get star ## Reporting An Issue -If you're about to raise an issue because you think you've found a problem with eosio.contracts, or you'd like to make a request for a new feature in the codebase, or any other reason… please read this first. +If you're about to raise an issue because you think you've found a problem with eosio.token, or you'd like to make a request for a new feature in the codebase, or any other reason… please read this first. The GitHub issue tracker is the preferred channel for [bug reports](#bug-reports), [feature requests](#feature-requests), and [submitting pull requests](#submitting-pull-requests), but please respect the following restrictions: @@ -34,12 +34,12 @@ Guidelines for bug reports: reported. 1. **Check if the issue has been fixed** — look for [closed issues in the - current milestone](https://github.com/EOSIO/eosio.contracts/issues?q=is%3Aissue+is%3Aclosed) or try to reproduce it + current milestone](https://github.com/EOSIO/eosio.token/issues?q=is%3Aissue+is%3Aclosed) or try to reproduce it using the latest `develop` branch. A good bug report shouldn't leave others needing to chase you up for more information. Be sure to include the details of your environment and relevant tests that demonstrate the failure. -[Report a bug](https://github.com/EOSIO/eosio.contracts/issues/new?title=Bug%3A) +[Report a bug](https://github.com/EOSIO/eosio.token/issues/new?title=Bug%3A) ### Feature Requests @@ -51,15 +51,15 @@ Feature requests are welcome. Before you submit one be sure to have: ### Change Requests -Change requests cover both architectural and functional changes to how eosio.contracts works. If you have an idea for a new or different dependency, a refactor, or an improvement to a feature, etc - please be sure to: +Change requests cover both architectural and functional changes to how eosio.token works. If you have an idea for a new or different dependency, a refactor, or an improvement to a feature, etc - please be sure to: 1. **Use the GitHub search** and check someone else didn't get there first 1. Take a moment to think about the best way to make a case for, and explain what you're thinking. Are you sure this shouldn't really be a [bug report](#bug-reports) or a [feature request](#feature-requests)? Is it really one idea or is it many? What's the context? What problem are you solving? Why is what you are suggesting better than what's already there? -## Working on eosio.contracts +## Working on eosio.token -Code contributions are welcome and encouraged! If you are looking for a good place to start, check out the [good first issue](https://github.com/EOSIO/eosio.contracts/labels/good%20first%20issue) label in GitHub issues. +Code contributions are welcome and encouraged! If you are looking for a good place to start, check out the [good first issue](https://github.com/EOSIO/eosio.token/labels/good%20first%20issue) label in GitHub issues. Also, please follow these guidelines when submitting code: @@ -67,8 +67,8 @@ Also, please follow these guidelines when submitting code: To get it out of the way: -- **[develop](https://github.com/EOSIO/eosio.contracts/tree/develop)** is the development branch. All work on the next release happens here so you should generally branch off `develop`. Do **NOT** use this branch for a production site. -- **[master](https://github.com/EOSIO/eosio.contracts/tree/master)** contains the latest release of eosio.contracts. This branch may be used in production. Do **NOT** use this branch to work on eosio.contracts's source. +- **[develop](https://github.com/EOSIO/eosio.token/tree/develop)** is the development branch. All work on the next release happens here so you should generally branch off `develop`. Do **NOT** use this branch for a production site. +- **[master](https://github.com/EOSIO/eosio.token/tree/master)** contains the latest release of eosio.token. This branch may be used in production. Do **NOT** use this branch to work on eosio.token's source. ### Submitting Pull Requests @@ -78,7 +78,7 @@ Pull requests are awesome. If you're looking to raise a PR for something which d Never underestimate just how useful quality assurance is. If you're looking to get involved with the code base and don't know where to start, checking out and testing a pull request is one of the most useful things you could do. -Essentially, [check out the latest develop branch](#working-on-eosio.contracts), take it for a spin, and if you find anything odd, please follow the [bug report guidelines](#bug-reports) and let us know! +Essentially, [check out the latest develop branch](#working-on-eosio.token), take it for a spin, and if you find anything odd, please follow the [bug report guidelines](#bug-reports) and let us know! ## Conduct diff --git a/README.md b/README.md index 0190c485..c35e36bf 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,15 @@ # eosio.token +<<<<<<< HEAD ## Version : 1.9.2 The design of the EOSIO blockchain calls for a number of smart contracts that are run at a privileged permission level in order to support functions such as block producer registration and voting, token staking for CPU and network bandwidth, RAM purchasing, multi-sig, etc. These smart contracts are referred to as the bios, boot, system, msig, wrap (formerly known as sudo) and token contracts. +======= +## Version : 2.0.0-develop + +The design of the EOSIO blockchain calls for a number of smart contracts that are run at a privileged permission level in order to support functions such as block producer registration and voting, token staking for CPU and network bandwidth, RAM purchasing, multi-sig, etc. These smart contracts are referred to as the bios, boot, system, msig, wrap (formerly known as sudo) and token contracts. + +>>>>>>> develop This repository contains a reference token example contracts that are useful when deploying a token using an EOSIO blockchain. It is provided for reference purposes: The following unprivileged contract(s) are in this repository. diff --git a/contracts/CMakeLists.txt b/contracts/CMakeLists.txt index 7f02640f..31b8d61b 100644 --- a/contracts/CMakeLists.txt +++ b/contracts/CMakeLists.txt @@ -5,7 +5,7 @@ project(contracts) set(EOSIO_WASM_OLD_BEHAVIOR "Off") find_package(eosio.cdt) -set(ICON_BASE_URL "http://127.0.0.1/ricardian_assets/eosio.contracts/icons") +set(ICON_BASE_URL "http://127.0.0.1/ricardian_assets/eosio.token/icons") set(TOKEN_ICON_URI "token.png#207ff68b0406eaa56618b08bda81d6a0954543f36adc328ab3065f31a5c5d654") set(TRANSFER_ICON_URI "transfer.png#5dfad0df72772ee1ccc155e670c1d124f5c5122f1d5027565df38b418042d1dd") diff --git a/contracts/eosio.token/include/eosio.token/eosio.token.hpp b/contracts/eosio.token/include/eosio.token/eosio.token.hpp index 050a685b..ce8756c7 100644 --- a/contracts/eosio.token/include/eosio.token/eosio.token.hpp +++ b/contracts/eosio.token/include/eosio.token/eosio.token.hpp @@ -18,7 +18,7 @@ namespace eosio { * * The `eosio.token` contract class also implements two useful public static methods: `get_supply` and `get_balance`. The first allows one to check the total supply of a specified token, created by an account and the second allows one to check the balance of a token for a specified account (the token creator account has to be specified as well). * - * The `eosio.token` contract manages the set of tokens, accounts and their corresponding balances, by using two internal multi-index structures: the `accounts` and `stats`. The `accounts` multi-index table holds, for each row, instances of `account` object and the `account` object holds information about the balance of one token. The `accounts` table is scoped to an eosio account, and it keeps the rows indexed based on the token's symbol. This means that when one queries the `accounts` multi-index table for an account name the result is all the tokens that account holds at the moment. + * The `eosio.token` contract manages the set of tokens, accounts and their corresponding balances, by using two internal multi-index structures: the `accounts` and `stats`. The `accounts` multi-index table holds, for each row, instances of `account` object and the `account` object holds information about the balance of one token. The `accounts` table is scoped to an EOSIO account, and it keeps the rows indexed based on the token's symbol. This means that when one queries the `accounts` multi-index table for an account name the result is all the tokens that account holds at the moment. * * Similarly, the `stats` multi-index table, holds instances of `currency_stats` objects for each row, which contains information about current supply, maximum supply, and the creator account for a symbol token. The `stats` table is scoped to the token symbol. Therefore, when one queries the `stats` table for a token symbol the result is one single entry/row corresponding to the queried symbol token if it was previously created, or nothing, otherwise. */ @@ -44,7 +44,7 @@ namespace eosio { * This action issues to `to` account a `quantity` of tokens. * * @param to - the account to issue tokens to, it must be the same as the issuer, - * @param quntity - the amount of tokens to be issued, + * @param quantity - the amount of tokens to be issued, * @memo - the memo string that accompanies the token issue transaction. */ [[eosio::action]] @@ -104,14 +104,14 @@ namespace eosio { static asset get_supply( const name& token_contract_account, const symbol_code& sym_code ) { stats statstable( token_contract_account, sym_code.raw() ); - const auto& st = statstable.get( sym_code.raw() ); + const auto& st = statstable.get( sym_code.raw(), "invalid supply symbol code" ); return st.supply; } static asset get_balance( const name& token_contract_account, const name& owner, const symbol_code& sym_code ) { accounts accountstable( token_contract_account, owner.value ); - const auto& ac = accountstable.get( sym_code.raw() ); + const auto& ac = accountstable.get( sym_code.raw(), "no balance with specified symbol" ); return ac.balance; } diff --git a/contracts/eosio.token/src/eosio.token.cpp b/contracts/eosio.token/src/eosio.token.cpp index 8dda907e..72bbf19d 100644 --- a/contracts/eosio.token/src/eosio.token.cpp +++ b/contracts/eosio.token/src/eosio.token.cpp @@ -84,7 +84,7 @@ void token::transfer( const name& from, check( is_account( to ), "to account does not exist"); auto sym = quantity.symbol.code(); stats statstable( get_self(), sym.raw() ); - const auto& st = statstable.get( sym.raw() ); + const auto& st = statstable.get( sym.raw(), "no balance with specified symbol" ); require_recipient( from ); require_recipient( to ); diff --git a/docker/buildContracts.sh b/docker/buildContracts.sh index d04dab96..6ec4e4de 100755 --- a/docker/buildContracts.sh +++ b/docker/buildContracts.sh @@ -1,6 +1,6 @@ #!/bin/bash set -e # exit on failure of any "simple" command (excludes &&, ||, or | chains) -cd /eosio.contracts +cd /eosio.tokens ./build.sh -c /usr/opt/eosio.cdt -e /opt/eosio -t -y cd build tar -pczf /artifacts/contracts.tar.gz * diff --git a/docker/unit-test.sh b/docker/unit-test.sh index 9348960b..8f6b523d 100755 --- a/docker/unit-test.sh +++ b/docker/unit-test.sh @@ -2,7 +2,7 @@ set -e # exit on failure of any "simple" command (excludes &&, ||, or | chains) CPU_CORES=$(getconf _NPROCESSORS_ONLN) echo "$CPU_CORES cpu cores detected." -cd /eosio.contracts/build/tests +cd /eosio.token/build/tests TEST_COUNT=$(ctest -N | grep -i 'Total Tests: ' | cut -d ':' -f 2 | awk '{print $1}') [[ $TEST_COUNT > 0 ]] && echo "$TEST_COUNT tests found." || (echo "ERROR: No tests registered with ctest! Exiting..." && exit 1) echo "$ ctest -j $CPU_CORES --output-on-failure -T Test" @@ -10,7 +10,7 @@ set +e # defer ctest error handling to end ctest -j $CPU_CORES --output-on-failure -T Test EXIT_STATUS=$? [[ "$EXIT_STATUS" == 0 ]] && set -e -mv /eosio.contracts/build/tests/Testing/$(ls /eosio.contracts/build/tests/Testing/ | grep '20' | tail -n 1)/Test.xml /artifacts/Test.xml +mv /eosio.token/build/tests/Testing/$(ls /eosio.token/build/tests/Testing/ | grep '20' | tail -n 1)/Test.xml /artifacts/Test.xml # ctest error handling if [[ "$EXIT_STATUS" != 0 ]]; then echo "Failing due to non-zero exit status from ctest: $EXIT_STATUS" diff --git a/docker/verifyInstallation.sh b/docker/verifyInstallation.sh index c5e198d1..29080768 100755 --- a/docker/verifyInstallation.sh +++ b/docker/verifyInstallation.sh @@ -7,6 +7,6 @@ set -e # exit on failure of any "simple" command (excludes &&, ||, or | chains) # fail if we didn't find it [[ -z "$CMAKE_FRAMEWORK_PATH" ]] && exit 1 # export variables -echo "" >> /eosio.contracts/docker/environment.Dockerfile # necessary if there is no '\n' at end of file -echo "ENV CMAKE_FRAMEWORK_PATH=$CMAKE_FRAMEWORK_PATH" >> /eosio.contracts/docker/environment.Dockerfile -echo "ENV EOSIO_ROOT=$CMAKE_FRAMEWORK_PATH" >> /eosio.contracts/docker/environment.Dockerfile \ No newline at end of file +echo "" >> /eosio.token/docker/environment.Dockerfile # necessary if there is no '\n' at end of file +echo "ENV CMAKE_FRAMEWORK_PATH=$CMAKE_FRAMEWORK_PATH" >> /eosio.token/docker/environment.Dockerfile +echo "ENV EOSIO_ROOT=$CMAKE_FRAMEWORK_PATH" >> /eosio.token/docker/environment.Dockerfile \ No newline at end of file diff --git a/docs.json b/docs.json index 625bedcf..026d4d3f 100644 --- a/docs.json +++ b/docs.json @@ -11,7 +11,11 @@ "name": "mdjavadoc", "options": { "source_dirs": [ +<<<<<<< HEAD "contracts/eosio.token/include/eosio.token/" +======= + "contracts/eosio.token/include/eosio.token/", +>>>>>>> develop ], "output_dir": "action-reference" } diff --git a/docs/03_build-and-deploy.md b/docs/01_build-and-deploy.md similarity index 50% rename from docs/03_build-and-deploy.md rename to docs/01_build-and-deploy.md index c612d47c..c789bf9b 100644 --- a/docs/03_build-and-deploy.md +++ b/docs/01_build-and-deploy.md @@ -10,6 +10,15 @@ Ensure an appropriate version of `eosio.cdt` is installed. Installing `eosio.cdt eosio-cpp -v ``` +### Build contracts using the build script + +#### To build contracts alone +Run the `build.sh` script in the top directory to build all the contracts. + +#### To build the contract and unit tests +1. Ensure an appropriate version of `eosio` has been built from source and installed. Installing `eosio` from binaries `is not` sufficient. You can find instructions on how to do it in section [Building from Sources](https://developers.eos.io/manuals/eos/latest/install/build-from-source). +2. Run the `build.sh` script in the top directory with the `-t` flag to build all the contracts and the unit tests for these contracts. + ### Build contracts manually To build the `eosio.token` execute the following commands. @@ -36,10 +45,10 @@ make -j$(sysctl -n hw.ncpu) cd .. ``` -### After build: -* If the build was configured to also build unit tests, the unit tests executable is placed in the _build/tests_ folder and is named __unit_test__. -* The contracts (both `.wasm` and `.abi` files) are built into their corresponding _build/contracts/\_ folder. -* Finally, simply use __cleos__ to _set contract_ by pointing to the previously mentioned directory for the specific contract. +### After build: +* If the build was configured to also build unit tests, the unit tests executable is placed in the _build/tests_ folder and is named __unit_test__. +* The contracts (both `.wasm` and `.abi` files) are built into their corresponding _build/contracts/\_ folder. +* Finally, simply use __cleos__ to _set contract_ by pointing to the previously mentioned directory for the specific contract. # How to deploy the eosio.token diff --git a/docs/01_key-concepts/01_system.md b/docs/01_key-concepts/01_system.md deleted file mode 100644 index eb14bb6d..00000000 --- a/docs/01_key-concepts/01_system.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -content_title: System contracts, system accounts, privileged accounts -link_text: System contracts, system accounts, privileged accounts ---- - -At the genesis of an EOSIO-based blockchain, there is only one account present, `eosio` account, which is the main `system account`. There are other `system account`s, created by `eosio` account, which control specific actions of the `system contract`s [mentioned in previous section](../#system-contracts-defined-in-eosio.contracts). __Note__ the terms `system contract` and `system account`. `Privileged accounts` are accounts which can execute a transaction while skipping the standard authorization check. To ensure that this is not a security hole, the permission authority over these accounts is granted to `eosio.prods` system account. - -As you just learned the relation between a `system account` and a `system contract`, it is also important to remember that not all system accounts contain a system contract, but each system account has important roles in the blockchain functionality, as follows: - -|Account|Privileged|Has contract|Description| -|---|---|---|---| -|eosio|Yes|It contains the `eosio.system` contract|The main system account on an EOSIO-based blockchain.| -|eosio.msig|Yes|It contains the `eosio.msig` contract|Allows the signing of a multi-sig transaction proposal for later execution if all required parties sign the proposal before the expiration time.| -|eosio.wrap|Yes|It contains the `eosio.wrap` contract.|Simplifies block producer superuser actions by making them more readable and easier to audit.| -|eosio.token|No|It contains the `eosio.token` contract.|Defines the structures and actions allowing users to create, issue, and manage tokens on EOSIO-based blockchains.| -|eosio.names|No|No|The account which is holding funds from namespace auctions.| -|eosio.bpay|No|No|The account that pays the block producers for producing blocks. It assigns 0.25% of the inflation based on the amount of blocks a block producer created in the last 24 hours.| -|eosio.prods|No|No|The account representing the union of all current active block producers permissions.| -|eosio.ram|No|No|The account that keeps track of the SYS balances based on users actions of buying or selling RAM.| -|eosio.ramfee|No|No|The account that keeps track of the fees collected from users RAM trading actions: 0.5% from the value of each trade goes into this account.| -|eosio.saving|No|No|The account which holds the 4% of network inflation.| -|eosio.stake|No|No|The account that keeps track of all SYS tokens which have been staked for NET or CPU bandwidth.| -|eosio.vpay|No|No|The account that pays the block producers accordingly with the votes won. It assigns 0.75% of inflation based on the amount of votes a block producer won in the last 24 hours.| -|eosio.rex|No|No|The account that keeps track of fees and balances resulted from REX related actions execution.| diff --git a/docs/01_key-concepts/02_ram.md b/docs/01_key-concepts/02_ram.md deleted file mode 100644 index a9d96fcd..00000000 --- a/docs/01_key-concepts/02_ram.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -content_title: RAM as system resource -link_text: RAM as system resource ---- - -## What is RAM - -RAM is the memory, the storage space, where the blockchain stores data. If your contract needs to store data on the blockchain, like in a database, then it can store it in the blockchain's RAM using either a `multi-index table` or a `singleton`. - -### Related documentation articles - -- Multi-index table [explainer documentation page](https://developers.eos.io/manuals/eosio.cdt/latest/group__multiindex) - -- Multi-index table [how to documentation page](https://developers.eos.io/manuals/eosio.cdt/latest/how-to-guides/multi-index) - -- Singleton [reference documentation page](https://developers.eos.io/manuals/eosio.cdt/latest/group__singleton/#singleton-table) - -- Singleton [how to documentation page](https://developers.eos.io/manuals/eosio.cdt/latest/how-to-guides/multi-index/how-to-define-a-singleton) - -## RAM High Performance - -The EOSIO-based blockchains are known for their high performance, which is achieved also because the data stored on the blockchain is using RAM as the storage medium, and thus access to blockchain data is very fast, helping the performance benchmarks to reach levels no other blockchain has been able to. - -## RAM Importance - -RAM is a very important system resource because of the following reasons: - -- It is a limited resource, each EOSIO-based blockchain can have different policies and rules around RAM; for example the public EOS blockchain started with 64GB of RAM and after that the block producers decided to increase the memory with 1KB per block, thus increasing constantly the supply of RAM for its price to not grow too high due to the increased demand from blockchain applications. - -- RAM is used in executing many actions sent to the blockchain; creating a new account action, for example, it needs to store in the blockchain memory the new account's information; also when an account accepts a new type of token a new record has to be created, somewhere in the blockchain memory, that holds the balance of the new token accepted, and that memory, the storage space on the blockchain, has to be purchased either by the account that transfers the token or by the account that accepts the new token type. - -- The smart contract can not store any additional information if it consumes all its allocated RAM. To continue to save data in the blockchain database, one, or both of the following conditions must be met: - - - A portion of the occupied RAM is freed by the smart contract. - - More RAM is allocated to the smart contract account through the RAM buying process. - -RAM is a scarce resource priced according to the unique Bancor liquidity algorithm which is implemented in the system contract [here](https://github.com/EOSIO/eos/blob/905e7c85714aee4286fa180ce946f15ceb4ce73c/contracts/eosio.system/exchange_state.hpp). - -The RAM system resource must be purchased using the system token. Refer to the [cleos manual](https://developers.eos.io/manuals/eos/v2.0/cleos/how-to-guides/how-to-buy-ram) to learn how to buy RAM via the command line interface. diff --git a/docs/01_key-concepts/03_cpu.md b/docs/01_key-concepts/03_cpu.md deleted file mode 100644 index 6f60577f..00000000 --- a/docs/01_key-concepts/03_cpu.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -content_title: CPU as system resource -link_text: CPU as system resource ---- - -The system resource CPU provides processing power to blockchain accounts. The amount of CPU an account has is measured in microseconds and it is referred to as `cpu bandwidth` on the `cleos get account` command output. The `cpu bandwidth` represents the amount of processing time an account has at its disposal when actions sent to its contract are executed by the blockchain. When a transaction is executed by the blockchain it consumes CPU and NET, therefore sufficient CPU must be staked in order for transactions to complete. - -For more details about EOSIO staking refer to the following: -* [Staking Mechanism](https://developers.eos.io/welcome/latest/overview/technical_features#staking-mechanism). -* [Staking on EOSIO-based blockchains](05_stake.md) \ No newline at end of file diff --git a/docs/01_key-concepts/04_net.md b/docs/01_key-concepts/04_net.md deleted file mode 100644 index f4f5b146..00000000 --- a/docs/01_key-concepts/04_net.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -content_title: NET as system resource -link_text: NET as system resource ---- - -NET, as CPU and RAM, is a very important system resource in EOSIO-based blockchains. NET is measured by the byte size of the transactions saved in the blockchain database and it is referred to as `net bandwidth` on the cleos get account command result. When a transaction is executed by the blockchain it consumes CPU and NET, therefore sufficient NET must be staked in order for transactions to complete. - -For more details about EOSIO staking refer to the following: -* [Staking Mechanism](https://developers.eos.io/welcome/latest/overview/technical_features#staking-mechanism). -* [Staking on EOSIO-based blockchains](05_stake.md) diff --git a/docs/01_key-concepts/05_stake.md b/docs/01_key-concepts/05_stake.md deleted file mode 100644 index d8904d9d..00000000 --- a/docs/01_key-concepts/05_stake.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -content_title: Staking on EOSIO-based blockchains -link_text: Staking on EOSIO-based blockchains ---- - -## System Resources - -EOSIO-based blockchains work with three system resources: - -* [RAM](02_ram.md) -* [CPU](03_cpu.md) -* [NET](04_net.md) - -## How To Allocate System Resources - -EOSIO-based blockchain accounts need sufficient system resources, RAM, CPU and NET, to interact with the smart contracts deployed on the blockchain. - -### Stake NET and CPU - -The CPU and NET system resources are allocated by the account owner via the staking mechanism. Refer to the [cleos manual](https://developers.eos.io/manuals/eos/v2.0/cleos/how-to-guides/how-to-stake-resource) on how to do it via the command line interface. - -You will also find that staking/unstaking is at times referred to as delegating/undelegating. The economics of staking is also to provably commit to a promise that you will hold the staked tokens, either for NET or CPU, for a pre-established period of time, in spite of inflation caused by minting new tokens in order to reward BPs for their services every 24 hours. - -When you stake tokens for CPU and NET, you gain access to system resources proportional to the total amount of tokens staked by all other users for the same system resource at the same time. This means you can execute transactions at no cost but in the limits of the staked tokens. The staked tokens guarantee the proportional amount of resources regardless of any variations in the free market. - -If an account consumes all its allocated CPU and NET resources, it has two options: - -* It can wait for the blockchain to replenish the consumed resources. You can read more details below about the [system resources replenish algorithm].(05_stake.md#System-Resources-Replenish-Algorithm). -* It can allocate more resources through the staking mechanism. - -When an account uses the allocated resources, the amount that can be used in one transaction is limited by predefine [maximum CPU](https://developers.eos.io/manuals/eosio.cdt/latest/structeosio_1_1blockchain__parameters#variable-max_transaction_cpu_usage), [minimum CPU](https://developers.eos.io/manuals/eosio.cdt/latest/structeosio_1_1blockchain__parameters#variable-min_transaction_cpu_usage), and [maximum NET](https://developers.eos.io/manuals/eosio.cdt/latest/structeosio_1_1blockchain__parameters#variable-max_transaction_net_usage) limits. Transactions executed by the blockchain contain one or more actions, and each transaction must consume an amount of CPU and NET which is in the limits defined by the aforementioned blockchain settings. - -#### System Resources Replenish Algorithm - -EOSIO-based blockchains replenish automatically the consumed CPU and NET system resources. Before a transaction is executed, by the blockchain, it first calculates how many resources the account executing the transaction can consume. The calculation uses an exponential moving average with linear extrapolation when data is missing, and it multiplies the currently accumulated average by `(number of blocks in the window - number of blocks since last update) / (number of blocks in the window)`. The window is set as 24 hours window. - -This formula has the following outcomes: - -* If an account waited `number of blocks in the window` without executing any transaction it resets to zero usage. - -* If an account issues a transaction with every block it would always be `(number of blocks in the window - 1) / (number of blocks in the window)`, a very small value, very close to zero. Mathematically it _never_ reaches zero but the EOSIO implementation truncates off the tiny numbers to zero. - -* The accounts that execute transactions more often than the ones that execute less transactions, replenish their resources slower than the later. In other words, the more transactions an account executes the slower the replenish of resources. - -[[info]] -| The blockchain calculates and updates the remaining resources, for the accounts which execute transactions, with each block, before each transaction is executed. As time passes, as explained above, the consumed system resources are gradually replenished, and the available system resources increase, or decrease, depending on how many transactions an account executes. After waiting for some time, if you check the available resources balance and expect to see it increased, because your account did not executed any transactions, you will not see it updated. That is because it gets updated only before a transaction is executed. Therefore in order to see the available resources you have to execute a transaction. This is counter intuitive and the next versions will improve this aspect. - -### Buy RAM - -The RAM resource must be bought using the system token. Refer to the [cleos manual](https://developers.eos.io/manuals/eos/v2.0/cleos/how-to-guides/how-to-buy-ram) to learn how to do it via the command line interface. When an account consumes all its allocated RAM can not store any additional information on the blockchain database until it frees some of the occupied RAM or more RAM is allocated to the account through the RAM buying process. diff --git a/docs/01_key-concepts/06_vote.md b/docs/01_key-concepts/06_vote.md deleted file mode 100644 index 4aa8ba6b..00000000 --- a/docs/01_key-concepts/06_vote.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -content_title: Voting on EOSIO-based blockchains -link_text: Voting on EOSIO-based blockchains ---- - -In a EOSIO-based network the blockchain is kept alive by nodes which are interconnected between each other, communicating with each other via peer to peer protocols. Some of these nodes are elected, via a voting process, by the token holders to be producer nodes. They produce blocks, validate them and reach consensus on what transactions are allowed in each block, their order, and what blocks are finalized and stored forever in the blockchain. This way the governance, the mechanism by which collective decisions are made, of the blockchain is achieved through the 21 active block producers which are appointed by token holders' votes. It's the 21 active block producers which continuously create the blockchain by creating blocks, and securing them by validating them, and reaching consensus. Consensus is reached when 2/3+1 active block producers agree on validity of a block, that is all transactions contained in it and their order. The 21 producers is the default value however it can be configured to be higher or smaller to meet each business case requirements. diff --git a/docs/04_guides/05_how-to-create-issue-and-transfer-a-token.md b/docs/02_guides/01_how-to-create-issue-and-transfer-a-token.md similarity index 94% rename from docs/04_guides/05_how-to-create-issue-and-transfer-a-token.md rename to docs/02_guides/01_how-to-create-issue-and-transfer-a-token.md index 0a2bf436..6f33eb4e 100644 --- a/docs/04_guides/05_how-to-create-issue-and-transfer-a-token.md +++ b/docs/02_guides/01_how-to-create-issue-and-transfer-a-token.md @@ -13,11 +13,11 @@ cd CONTRACTS_DIR Pull the source ```sh -git clone https://github.com/EOSIO/eosio.contracts --branch master --single-branch +git clone https://github.com/EOSIO/eosio.token --branch master --single-branch ``` ```sh -cd eosio.contracts/contracts/eosio.token +cd eosio.token/contracts/eosio.token ``` ## Step 2: Create Account for Contract @@ -37,7 +37,7 @@ eosio-cpp -I include -o eosio.token.wasm src/eosio.token.cpp --abigen ## Step 4: Deploy the Token Contract ```shell -cleos set contract eosio.token CONTRACTS_DIR/eosio.contracts/contracts/eosio.token --abi eosio.token.abi -p eosio.token@active +cleos set contract eosio.token CONTRACTS_DIR/eosio.token/contracts/eosio.token --abi eosio.token.abi -p eosio.token@active ``` Result should look similar to the one below: diff --git a/docs/04_guides/01_upgrading-the-eosio.system-contract.md b/docs/04_guides/01_upgrading-the-eosio.system-contract.md deleted file mode 100644 index 8196453f..00000000 --- a/docs/04_guides/01_upgrading-the-eosio.system-contract.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -content_title: Upgrading the system contract -link_text: Upgrading the system contract ---- - -# Indirect method using eosio.msig contract - -Cleos currently provides tools to propose an action with the eosio.msig contract, but it does not provide an easy interface to propose a custom transaction. - -So, at the moment it is difficult to propose an atomic transaction with multiple actions (for example `eosio::setcode` followed by `eosio::setabi`). - -The advantage of the eosio.msig method is that it makes coordination much easier and does not place strict time limits (less than 9 hours) on signature collection. - -The disadvantage of the eosio.msig method is that it requires the proposer to have sufficient RAM to propose the transaction and currently cleos does not provide convenient tools to use it with custom transactions like the one that would be necessary to atomically upgrade the system contract. - -For now, it is recommended to use the direct method to upgrade the system contract. - -# Direct method (avoids using eosio.msig contract) - -Each of the top 21 block producers should do the following: - -1. Get current system contract for later comparison (actual hash and ABI on the main-net blockchain will be different): - -```sh -cleos get code -c original_system_contract.wast -a original_system_contract.abi eosio -``` -```console -code hash: cc0ffc30150a07c487d8247a484ce1caf9c95779521d8c230040c2cb0e2a3a60 -saving wast to original_system_contract.wast -saving abi to original_system_contract.abi -``` - -2. Generate the unsigned transaction which upgrades the system contract: - -```sh -cleos set contract -s -j -d eosio contracts/eosio.system | tail -n +4 > upgrade_system_contract_trx.json -``` - -The first few lines of the generated file should be something similar to (except with very different numbers for `expiration`, `ref_block_num`, and `ref_block_prefix`): - -```json -{ - "expiration": "2018-06-15T22:17:10", - "ref_block_num": 4552, - "ref_block_prefix": 511016679, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "setcode", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], -``` - -and the last few lines should be: - -```json - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -One of the top block producers should be chosen to lead the upgrade process. This lead producer should take their generated `upgrade_system_contract_trx.json`, rename it to `upgrade_system_contract_official_trx.json`, and do the following: - -3. Modify the `expiration` timestamp in `upgrade_system_contract_official_trx.json` to a time that is sufficiently far in the future to give enough time to collect all the necessary signatures, but not more than 9 hours from the time the transaction was generated. Also, keep in mind that the transaction will not be accepted into the blockchain if the expiration is more than 1 hour from the present time. - -4. Pass the `upgrade_system_contract_official_trx.json` file to all the other top 21 block producers. - -Then each of the top 21 block producers should do the following: - -5. Compare their generated `upgrade_system_contract_official_trx.json` file with the `upgrade_system_contract_official_trx.json` provided by the lead producer. The only difference should be in `expiration`, `ref_block_num`, `ref_block_prefix`, for example: - -```sh -diff upgrade_system_contract_official_trx.json upgrade_system_contract_trx.json -``` -```json -2,4c2,4 -< "expiration": "2018-06-15T22:17:10", -< "ref_block_num": 4552, -< "ref_block_prefix": 511016679, ---- -> "expiration": "2018-06-15T21:20:39", -> "ref_block_num": 4972, -> "ref_block_prefix": 195390844, -``` - -6. If the comparison is good, each block producer should proceed with signing the official upgrade transaction with the keys necessary to satisfy their active permission. If the block producer only has a single key (i.e the "active key") in the active permission of their block producing account, then they only need to generate one signature using that active key. This signing process can be done offline for extra security. - -First, the block producer should collect all the necessary information. Let us assume that the block producers active key pair is `(EOS5kBmh5kfo6c6pwB8j77vrznoAaygzoYvBsgLyMMmQ9B6j83i9c, 5JjpkhxAmEfynDgSn7gmEKEVcBqJTtu6HiQFf4AVgGv5A89LfG3)`. The block producer needs their active private key (`5JjpkhxAmEfynDgSn7gmEKEVcBqJTtu6HiQFf4AVgGv5A89LfG3` in this example), the `upgrade_system_contract_official_trx.json`, and the `chain_id` (`d0242fb30b71b82df9966d10ff6d09e4f5eb6be7ba85fd78f796937f1959315e` in this example) which can be retrieved through `cleos get info`. - -Then on a secure computer the producer can sign the transaction (the producer will need to paste in their private key when prompted): - -```sh -cleos sign --chain-id d0242fb30b71b82df9966d10ff6d09e4f5eb6be7ba85fd78f796937f1959315e upgrade_system_contract_trx.json | tail -n 5 -``` -```json -private key: "signatures": [ - "SIG_K1_JzABB9gzDGwUHaRmox68UNcfxMVwMnEXqqS1MvtsyUX8KGTbsZ5aZQZjHD5vREQa5BkZ7ft8CceLBLAj8eZ5erZb9cHuy5" - ], - "context_free_data": [] -} -``` - -Make sure to use the `chain_id` of the actual main-net blockchain that the transaction will be submitted to and not the example `chain_id` provided above. - -The output should include the signature (in this case `"SIG_K1_JzABB9gzDGwUHaRmox68UNcfxMVwMnEXqqS1MvtsyUX8KGTbsZ5aZQZjHD5vREQa5BkZ7ft8CceLBLAj8eZ5erZb9cHuy5"`) which the producer should then send to the lead producer. - -When the lead producer collects 15 producer signatures, the lead producer should do the following: - -7. Make a copy of the `upgrade_system_contract_official_trx.json` and call it `upgrade_system_contract_official_trx_signed.json`, and then modify the `upgrade_system_contract_official_trx_signed.json` so that the `signatures` field includes all 15 collected signatures. So the tail end of `upgrade_system_contract_official_trx_signed.json` could look something like: - -```sh -cat upgrade_system_contract_official_trx_signed.json | tail -n 20 -``` -```json - "transaction_extensions": [], - "signatures": [ - "SIG_K1_JzABB9gzDGwUHaRmox68UNcfxMVwMnEXqqS1MvtsyUX8KGTbsZ5aZQZjHD5vREQa5BkZ7ft8CceLBLAj8eZ5erZb9cHuy5", - "SIG_K1_Kj7XJxnPQSxEXZhMA8uK3Q1zAxp7AExzsRd7Xaa7ywcE4iUrhbVA3B6GWre5Ctgikb4q4CeU6Bvv5qmh9uJjqKEbbjd3sX", - "SIG_K1_KbE7qyz3A9LoQPYWzo4e6kg5ZVojQVAkDKuufUN2EwVUqtFhtjmGoC6QPQqLi8J7ftiysBp52wJBPjtNQUfZiGpGMsnZ1f", - "SIG_K1_KdQsE7ahHA9swE9SDGg4oF6XahpgHmZfEgQAy9KPBLd9HuwrF6c8m6jz43zizK2oo32Ejg1DYuMfoEvJgVfXo81jsqTHvA", - "SIG_K1_K6228Hi2z1WabgVdf5bk2UdKyyDSVFwkMaagTn9oLVDV8rCX7aQcjY94c39ah2CkLTsTEqzTPAYknJ8m2m9B7npPkHaFzc", - "SIG_K1_Jzdx75hBCA2WSaXgrupmrNbcQocUCsP8r1BKkPXMreiAKPZDwX9J3G8fS1HhyqWjc7FbukwZf8sVRdS3wKbJVpytqXe7Nn", - "SIG_K1_KW7Qu2SdPD3zuQKh2ziFLzn9QbKqeMpeiemULky5Bbg1Mst6ijbCX3k2AVFGNFLkNLA36PM1WAT5oipzu1B1K7ymRxTx1Z", - "SIG_K1_KXJf1KZNpz73YFKKE7u6jFgsQ8XcX3yA7rDX6ZmG1Qfnc9FLLmT1WViv4bwcPbxaEYfR6SNWfk5cCR9eao2si1soqkXq92", - "SIG_K1_JynjkHFT5UFGDpEcqdriXTzCGCwS36Xztq4UAWQHLQgRUZT2YFoLhUcc87kvUteqCUGVxsmSbfgWv1KLy24voKN4Qs5zTe", - "SIG_K1_JxhfCaGBhuNShpDHn7j1CryG3iSebvfi7FUnJsfkXNTiwLyq2NDBkeakwjCMWFbzr6qqWuMDLjfXbzdtU17f1wCXMjKSgk", - "SIG_K1_KcMSz89QG1ZRFNrXc69R63d5KXbJA8CBjNPYv1VEA3TRfjqVYuhyaHpGXQN4RSKDq4ygr3UTRYBQQVutkJnR6zZ4Ssgd7R", - "SIG_K1_JuxT6bhUAbDs6Q2ppuKyKauduvbaJLxvh4gBH4e4A9yRhvUBT7w3DcvMyhdaor27Kbu29jnqhTbvXcb57QqKWQDpboLv7e", - "SIG_K1_K8BuFYpCiC5FhpVK8ZAzc3VUg7vz6WwLoWBrGN6nnuqUjngGqvHp3UxDVzcwhqccHdv8kdPXvF6G1NszwF1dd3wjCrHBYw", - "SIG_K1_KfH5ZirPwDk1RQKvJv2AGPfsJyPXvXLegZ7LvcPmRtjtMiErs1STXLNT8kiBfhZr4xkWRA5NR1kMF3d49DFMJiB2iWMXJc", - "SIG_K1_KjJB8jtcqpVe3r5jouFiAa9wJeYqoLMh5xrUV6kBF6UWfbYjimMWBJWz2ZPomGDsk7JtdUESVrYj1AhYbdp3X48KLm5Cev" - ], - "context_free_data": [] -} -``` - -8. Push the signed transaction to the blockchain: - -```sh -cleos push transaction --skip-sign upgrade_system_contract_official_trx_signed.json -``` -```json -{ - "transaction_id": "202888b32e7a0f9de1b8483befac8118188c786380f6e62ced445f93fb2b1041", - "processed": { - "id": "202888b32e7a0f9de1b8483befac8118188c786380f6e62ced445f93fb2b1041", - "receipt": { - "status": "executed", - "cpu_usage_us": 4909, - "net_usage_words": 15124 - }, - "elapsed": 4909, - "net_usage": 120992, - "scheduled": false, - "action_traces": [{ -... -``` - -If you get an error message like the following: - -```console -Error 3090003: provided keys, permissions, and delays do not satisfy declared authorizations -Ensure that you have the related private keys inside your wallet and your wallet is unlocked. -``` - -That means that at least one of the signatures provided were bad. This may be because a producer signed the wrong transaction, used the wrong private key, or used the wrong chain ID. - -If you get an error message like the following: - -```console -Error 3090002: irrelevant signature included -Please remove the unnecessary signature from your transaction! -``` - -That means unnecessary signatures were included. If there are 21 active producers, only signatures from exactly 15 of those 21 active producers are needed. - -If you get an error message like the following: - -```console -Error 3040006: Transaction Expiration Too Far -Please decrease the expiration time of your transaction! -``` - -That means that the expiration time is more than 1 hour in the future and you need to wait some time before being allowed to push the transaction. - -If you get an error message like the following: - -```console -Error 3040005: Expired Transaction -Please increase the expiration time of your transaction! -``` - -That means the expiration time of the signed transaction has passed and this entire process has to restart from step 1. - -9. Assuming the transaction successfully executes, everyone can then verify that the new contract is in place: - -```sh -cleos get code -c new_system_contract.wast -a new_system_contract.abi eosio -``` -```console -code hash: 9fd195bc5a26d3cd82ae76b70bb71d8ce83dcfeb0e5e27e4e740998fdb7b98f8 -saving wast to new_system_contract.wast -saving abi to new_system_contract.abi -``` - -```sh -diff original_system_contract.abi new_system_contract.abi -``` -```json -584,592d583 -< },{ -< "name": "deferred_trx_id", -< "type": "uint32" -< },{ -< "name": "last_unstake_time", -< "type": "time_point_sec" -< },{ -< "name": "unstaking", -< "type": "asset" -``` \ No newline at end of file diff --git a/docs/04_guides/02_how-to-buy-ram.md b/docs/04_guides/02_how-to-buy-ram.md deleted file mode 100644 index dee6776e..00000000 --- a/docs/04_guides/02_how-to-buy-ram.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -content_title: How to buy RAM -link_text: How to buy RAM ---- - -# Goal - -Setup an account that require multiple signatures for signing a transaction - -# Before you begin - -* You have an account - -* Ensure the reference system contracts from `eosio.contracts` repository is deployed and used to manage system resources - -* You have sufficient token allocated to your account - -* Install the currently supported version of cleos - -* Unlock your wallet - -# Steps - -Buys RAM in value of 0.1 SYS tokens for account `alice`: - -```shell -cleos system buyram alice alice "0.1 SYS" -p alice@active -``` \ No newline at end of file diff --git a/docs/04_guides/03_how-to-stake.md b/docs/04_guides/03_how-to-stake.md deleted file mode 100644 index 0413a01a..00000000 --- a/docs/04_guides/03_how-to-stake.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -content_title: How to stake -link_text: How to stake ---- - -# Goal - -Stake resource for your account - -# Before you begin - -* Install the currently supported version of cleos - -* Ensure the reference system contracts from `eosio.contracts` repository is deployed and used to manage system resources - -* Understand the following: - * What is an account - * What is network bandwidth - * What is CPU bandwidth - -# Steps - -Stake 0.01 SYS network bandwidth for `alice` - -```shell -cleos system delegatebw alice alice "0 SYS" "0.01 SYS" -``` - -Stake 0.01 SYS CPU bandwidth for `alice`: - -```shell -cleos system delegatebw alice alice "0.01 SYS" "0 SYS" -``` \ No newline at end of file diff --git a/docs/04_guides/04_how-to-vote.md b/docs/04_guides/04_how-to-vote.md deleted file mode 100644 index ee9e1f96..00000000 --- a/docs/04_guides/04_how-to-vote.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -content_title: How to vote -link_text: How to vote ---- - -# Goal - -Vote for a block producer - -# Before you begin - -* Install the current supported version of cleos - -* Ensure the reference system contracts from `eosio.contracts` repository is deployed and used to manage system resources - -* Understand the following: - * What is a block producer - * How does voting works - -* Unlock your wallet - -# Steps - -Assume you are going to vote for blockproducer1 and blockproducer2 from an account called `eosiotestts2`, execute the following: - -```bash -cleos system voteproducer prods eosiotestts2 blockproducer1 blockproducer2 -``` - -You should see something like below: - -```console -executed transaction: 2d8b58f7387aef52a1746d7a22d304bbbe0304481d7751fc4a50b619df62676d 128 bytes 374 us -# eosio <= eosio::voteproducer {"voter":"eosiotestts2","proxy":"","producers":["blockproducer1","blockproducer2"]} -``` \ No newline at end of file diff --git a/docs/04_guides/06_how-to-sign-a-multisig-transaction-with-eosio.msig.md b/docs/04_guides/06_how-to-sign-a-multisig-transaction-with-eosio.msig.md deleted file mode 100644 index 6014c9ba..00000000 --- a/docs/04_guides/06_how-to-sign-a-multisig-transaction-with-eosio.msig.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -content_title: How to sign a multisig transaction with eosio.msig -link_text: How to sign a multisig transaction with eosio.msig ---- - -### eosio.msig - -### Prerequisites: - - eosio.token contract installed to eosio.token account, eosio.msig contract installed on eosio.msig account which is a priviliged account. - - account 'treasury' is the issuer of SYS token. - - account 'tester' exists. - - keys to accounts 'treasury' and 'tester' imported into local wallet, the wallet is unlocked. - -### One user creates a proposal: -```sh -cleos multisig propose test '[{"actor": "treasury", "permission": "active"}]' '[{"actor": "treasury", "permission": "active"}]' eosio.token issue '{"to": "tester", "quantity": "1000.0000 SYS", "memo": ""}' -p tester -``` -```console -executed transaction: e26f3a3a7cba524a7b15a0b6c77c7daa73d3ba9bf84e83f9c2cdf27fcb183d61 336 bytes 107520 cycles -# eosio.msig <= eosio.msig::propose {"proposer":"tester","proposal_name":"test","requested":[{"actor":"treasury","permission":"active"}]... -``` - -### Another user reviews the transaction: -```sh -cleos multisig review tester test -``` -```json -{ - "proposal_name": "test", - "requested_approvals": [{ - "actor": "treasury", - "permission": "active" - } - ], - "provided_approvals": [], - "packed_transaction": "00aee75a0000000000000000000000000100a6823403ea30550000000000a5317601000000fe6a6cd4cd00000000a8ed323219000000005c95b1ca809698000000000004454f530000000000", - "transaction": { - "expiration": "2018-05-01T00:00:00", - "region": 0, - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_kcpu_usage": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio.token", - "name": "issue", - "authorization": [{ - "actor": "treasury", - "permission": "active" - } - ], - "data": { - "to": "tester", - "quantity": "1000.0000 SYS", - "memo": "" - }, - "hex_data": "000000005c95b1ca809698000000000004454f530000000000" - } - ] - } -} -``` - -### And then approves it: -```sh -cleos multisig approve tester test '{"actor": "treasury", "permission": "active"}' -p treasury -``` -```console -executed transaction: 475970a4b0016368d0503d1ce01577376f91f5a5ba63dd4353683bd95101b88d 256 bytes 108544 cycles -# eosio.msig <= eosio.msig::approve {"proposer":"tester","proposal_name":"test","level":{"actor":"treasury","permission":"active"}} -``` - -### First user initiates execution: -```sh -cleos multisig exec tester test -p tester -``` -```console -executed transaction: 64e5eaceb77362694055f572ae35876111e87b637a55250de315b1b55e56d6c2 248 bytes 109568 cycles -# eosio.msig <= eosio.msig::exec {"proposer":"tester","proposal_name":"test","executer":"tester"} -``` - - -## Cleos usage example for transferring tokens. - -### Prerequisites: - - eosio.token contract installed to eosio.token account, eosio.msig contract installed on eosio.msig account which is a priviliged account. - - account 'treasury' has at least 1.1000 SYS token balance. - - account 'tester' exists. - - keys to accounts 'treasury' and 'tester' imported into local wallet, the wallet is unlocked. - -### One user creates a proposal: -```sh -cleos multisig propose test '[{"actor": "treasury", "permission": "active"}]' '[{"actor": "treasury", "permission": "active"}]' eosio.token transfer '{"from": "treasury", "to": "tester", "quantity": "1.0000 SYS", "memo": ""}' -p tester -``` -```console -executed transaction: e26f3a3a7cba524a7b15a0b6c77c7daa73d3ba9bf84e83f9c2cdf27fcb183d61 336 bytes 107520 cycles -# eosio.msig <= eosio.msig::propose {"proposer":"tester","proposal_name":"test","requested":[{"actor":"treasury","permission":"active"}]... -``` - -### Another user reviews the transaction: -```sh -cleos multisig review tester test -``` -```json -{ - "proposal_name": "test", - "requested_approvals": [{ - "actor": "treasury", - "permission": "active" - } - ], - "provided_approvals": [], - "packed_transaction": "00aee75a0000000000000000000000000100a6823403ea30550000000000a5317601000000fe6a6cd4cd00000000a8ed323219000000005c95b1ca809698000000000004454f530000000000", - "transaction": { - "expiration": "2018-05-01T00:00:00", - "region": 0, - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_kcpu_usage": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio.token", - "name": "transfer", - "authorization": [{ - "actor": "treasury", - "permission": "active" - } - ], - "data": { - "from": "treasury", - "to": "tester", - "quantity": "1.0000 SYS", - "memo": "" - }, - "hex_data": "000000005c95b1ca809698000000000004454f530000000000" - } - ] - } -} -``` - -### And then approves it: -```sh -cleos multisig approve tester test '{"actor": "treasury", "permission": "active"}' -p treasury -``` -```console -executed transaction: 475970a4b0016368d0503d1ce01577376f91f5a5ba63dd4353683bd95101b88d 256 bytes 108544 cycles -# eosio.msig <= eosio.msig::approve {"proposer":"tester","proposal_name":"test","level":{"actor":"treasury","permission":"active"}} -``` - -### First user check account balance before executing the proposed transaction -```sh -cleos get account tester -``` -```console -... -SYS balances: - liquid: 1.0487 SYS - staked: 2.0000 SYS - unstaking: 0.0000 SYS - total: 4.0487 SYS -``` - -### First user initiates execution of proposed transaction: -```sh -cleos multisig exec tester test -p tester -``` -```console -executed transaction: 64e5eaceb77362694055f572ae35876111e87b637a55250de315b1b55e56d6c2 248 bytes 109568 cycles -# eosio.msig <= eosio.msig::exec {"proposer":"tester","proposal_name":"test","executer":"tester"} -``` - -### First user can check account balance, it should be increased by 1.0000 SYS -```sh -cleos get account tester -``` -```console -... -SYS balances: - liquid: 2.0487 SYS - staked: 2.0000 SYS - unstaking: 0.0000 SYS - total: 4.0487 SYS -``` diff --git a/docs/04_guides/07_how-to-use-eosio.wrap.md b/docs/04_guides/07_how-to-use-eosio.wrap.md deleted file mode 100644 index 807441c2..00000000 --- a/docs/04_guides/07_how-to-use-eosio.wrap.md +++ /dev/null @@ -1,971 +0,0 @@ ---- -content_title: How to use eosio.wrap -link_text: How to use eosio.wrap ---- - -# 1. Installing the eosio.wrap contract - -The eosio.wrap contract needs to be installed on a privileged account to function. It is recommended to use the account `eosio.wrap`. - -First, the account `eosio.wrap` needs to be created. Since it has the restricted `eosio.` prefix, only a privileged account can create this account. So this guide will use the `eosio` account to create the `eosio.wrap` account. On typical live blockchain configurations, the `eosio` account can only be controlled by a supermajority of the current active block producers. So, this guide will use the `eosio.msig` contract to help coordinate the approvals of the proposed transaction that creates the `eosio.wrap` account. - -The `eosio.wrap` account also needs to have sufficient RAM to host the contract and sufficient CPU and network bandwidth to deploy the contract. This means that the creator of the account (`eosio`) needs to gift sufficient RAM to the new account and delegate (preferably with transfer) sufficient bandwidth to the new account. To pull this off the `eosio` account needs to have enough of the core system token (the `SYS` token will be used within this guide) in its liquid balance. So prior to continuing with the next steps of this guide, the active block producers of the chain who are coordinating this process need to ensure that a sufficient amount of core system tokens that they are authorized to spend is placed in the liquid balance of the `eosio` account. - -This guide will be using cleos to carry out the process. - -## 1.1 Create the eosio.wrap account - -### 1.1.1 Generate the transaction to create the eosio.wrap account - -The transaction to create the `eosio.wrap` account will need to be proposed to get the necessary approvals from active block producers before executing it. This transaction needs to first be generated and stored as JSON into a file so that it can be used in the cleos command to propose the transaction to the eosio.msig contract. - -A simple way to generate a transaction to create a new account is to use the `cleos system newaccount`. However, that sub-command currently only accepts a single public key as the owner and active authority of the new account. However, the owner and active authorities of the new account should only be satisfied by the `active` permission of `eosio`. One option is to create the new account with the some newly generated key, and then later update the authorities of the new account using `cleos set account permission`. This guide will take an alternative approach which atomically creates the new account in its proper configuration. - -Three unsigned transactions will be generated using cleos and then the actions within those transactions will be appropriately stitched together into a single transaction which will later be proposed using the eosio.msig contract. - -First, generate a transaction to capture the necessary actions involved in creating a new account: -```sh -cleos system newaccount -s -j -d --transfer --stake-net "1.000 SYS" --stake-cpu "1.000 SYS" --buy-ram-kbytes 50 eosio eosio.wrap EOS8MMUW11TAdTDxqdSwSqJodefSoZbFhcprndomgLi9MeR2o8MT4 > generated_account_creation_trx.json -``` -```console -726964ms thread-0 main.cpp:429 create_action ] result: {"binargs":"0000000000ea305500004d1a03ea305500c80000"} arg: {"code":"eosio","action":"buyrambytes","args":{"payer":"eosio","receiver":"eosio.wrap","bytes":51200}} -726967ms thread-0 main.cpp:429 create_action ] result: {"binargs":"0000000000ea305500004d1a03ea3055102700000000000004535953000000001027000000000000045359530000000001"} arg: {"code":"eosio","action":"delegatebw","args":{"from":"eosio","receiver":"eosio.wrap","stake_net_quantity":"1.0000 SYS","stake_cpu_quantity":"1.0000 SYS","transfer":true}} -``` -```sh -cat generated_account_creation_trx.json -``` -```json -{ - "expiration": "2018-06-29T17:11:36", - "ref_block_num": 16349, - "ref_block_prefix": 3248946195, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "newaccount", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "0000000000ea305500004d1a03ea305501000000010003c8162ea04fed738bfd5470527fd1ae7454c2e9ad1acbadec9f9e35bab2f33c660100000001000000010003c8162ea04fed738bfd5470527fd1ae7454c2e9ad1acbadec9f9e35bab2f33c6601000000" - },{ - "account": "eosio", - "name": "buyrambytes", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "0000000000ea305500004d1a03ea305500c80000" - },{ - "account": "eosio", - "name": "delegatebw", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "0000000000ea305500004d1a03ea3055102700000000000004535953000000001027000000000000045359530000000001" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -Adjust the amount of delegated tokens and the amount of RAM bytes to gift as necessary. -The actual public key used is not important since that data is only encoded into the `eosio::newaccount` action which will be replaced soon anyway. - -Second, create a file (e.g. newaccount_payload.json) with the JSON payload for the real `eosio::newaccount` action. It should look like: -```sh -cat newaccount_payload.json -``` -```json -{ - "creator": "eosio", - "name": "eosio.wrap", - "owner": { - "threshold": 1, - "keys": [], - "accounts": [{ - "permission": {"actor": "eosio", "permission": "active"}, - "weight": 1 - }], - "waits": [] - }, - "active": { - "threshold": 1, - "keys": [], - "accounts": [{ - "permission": {"actor": "eosio", "permission": "active"}, - "weight": 1 - }], - "waits": [] - } -} -``` - -Third, generate a transaction containing the actual `eosio::newaccount` action that will be used in the final transaction: -```sh -cleos push action -s -j -d eosio newaccount newaccount_payload.json -p eosio > generated_newaccount_trx.json -cat generated_newaccount_trx.json -``` -```json -{ - "expiration": "2018-06-29T17:11:36", - "ref_block_num": 16349, - "ref_block_prefix": 3248946195, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "newaccount", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "0000000000ea305500004d1a03ea30550100000000010000000000ea305500000000a8ed32320100000100000000010000000000ea305500000000a8ed3232010000" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -Fourth, generate a transaction containing the `eosio::setpriv` action which will make the `eosio.wrap` account privileged: -```sh -cleos push action -s -j -d eosio setpriv '{"account": "eosio.wrap", "is_priv": 1}' -p eosio > generated_setpriv_trx.json -cat generated_setpriv_trx.json -``` -```json -{ - "expiration": "2018-06-29T17:11:36", - "ref_block_num": 16349, - "ref_block_prefix": 3248946195, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "setpriv", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "00004d1a03ea305501" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -Next, the action JSONs of the previously generated transactions will be used to construct a unified transaction which will eventually be proposed with the eosio.msig contract. A good way to get started is to make a copy of the generated_newaccount_trx.json file (call the copied file create_wrap_account_trx.json) and edit the first three fields so it looks something like the following: -```sh -cat create_wrap_account_trx.json -``` -```json -{ - "expiration": "2018-07-06T12:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "newaccount", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "0000000000ea305500004d1a03ea30550100000000010000000000ea305500000000a8ed32320100000100000000010000000000ea305500000000a8ed3232010000" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -The `ref_block_num` and `ref_block_prefix` values were set to 0. The proposed transaction does not need to have a valid TaPoS reference block because it will be reset anyway when scheduled as a deferred transaction during the `eosio.msig::exec` action. The `expiration` field, which was the only other field that was changed, will also be reset when the proposed transaction is scheduled as a deferred transaction during `eosio.msig::exec`. However, this field actually does matter during the propose-approve-exec lifecycle of the proposed transaction. If the present time passes the time in the `expiration` field of the proposed transaction, it will not be possible to execute the proposed transaction even if all necessary approvals are gathered. Therefore, it is important to set the expiration time to some point well enough in the future to give all necessary approvers enough time to review and approve the proposed transaction, but it is otherwise arbitrary. Generally, for reviewing/validation purposes it is important that all potential approvers of the transaction (i.e. the block producers) choose the exact same `expiration` time so that there is not any discrepancy in bytes of the serialized transaction if it was to later be included in payload data of some other action. - -Then, all but the first action JSON object of generated_account_creation_trx.json should be appended to the `actions` array of create_wrap_account_trx.json, and then the single action JSON object of generated_setpriv_trx.json should be appended to the `actions` array of create_wrap_account_trx.json. The final result is a create_wrap_account_trx.json file that looks like the following: -```sh -cat create_wrap_account_trx.json -``` -```json -{ - "expiration": "2018-07-06T12:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "newaccount", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "0000000000ea305500004d1a03ea30550100000000010000000000ea305500000000a8ed32320100000100000000010000000000ea305500000000a8ed3232010000" - },{ - "account": "eosio", - "name": "buyrambytes", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "0000000000ea305500004d1a03ea305500c80000" - },{ - "account": "eosio", - "name": "delegatebw", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "0000000000ea305500004d1a03ea3055102700000000000004535953000000001027000000000000045359530000000001" - },{ - "account": "eosio", - "name": "setpriv", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": "00004d1a03ea305501" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -The transaction in create_wrap_account_trx.json is now ready to be proposed. - -It will be useful to have a JSON of the active permissions of each of the active block producers for later when proposing transactions using the eosio.msig contract. - -This guide will assume that there are 21 active block producers on the chain with account names: `blkproducera`, `blkproducerb`, ..., `blkproduceru`. - -In that case, create a file producer_permissions.json with the content shown in the command below: -```sh -cat producer_permissions.json -``` -```json -[ - {"actor": "blkproducera", "permission": "active"}, - {"actor": "blkproducerb", "permission": "active"}, - {"actor": "blkproducerc", "permission": "active"}, - {"actor": "blkproducerd", "permission": "active"}, - {"actor": "blkproducere", "permission": "active"}, - {"actor": "blkproducerf", "permission": "active"}, - {"actor": "blkproducerg", "permission": "active"}, - {"actor": "blkproducerh", "permission": "active"}, - {"actor": "blkproduceri", "permission": "active"}, - {"actor": "blkproducerj", "permission": "active"}, - {"actor": "blkproducerk", "permission": "active"}, - {"actor": "blkproducerl", "permission": "active"}, - {"actor": "blkproducerm", "permission": "active"}, - {"actor": "blkproducern", "permission": "active"}, - {"actor": "blkproducero", "permission": "active"}, - {"actor": "blkproducerp", "permission": "active"}, - {"actor": "blkproducerq", "permission": "active"}, - {"actor": "blkproducerr", "permission": "active"}, - {"actor": "blkproducers", "permission": "active"}, - {"actor": "blkproducert", "permission": "active"}, - {"actor": "blkproduceru", "permission": "active"} -] -``` - -### 1.1.2 Propose the transaction to create the eosio.wrap account - -Only one of the potential approvers will need to propose the transaction that was created in the previous sub-section. All the other approvers should still follow the steps in the previous sub-section to generate the same create_wrap_account_trx.json file as all the other approvers. They will need this to compare to the actual proposed transaction prior to approving. - -The approvers are typically going to be the active block producers of the chain, so it makes sense that one of the block producers is elected as the leader to propose the actual transaction. Note that this lead block producer will need to incur the temporary RAM cost of proposing the transaction, but they will get the RAM back when the proposal has executed or has been canceled (which only the proposer can do prior to expiration). - -The guide will assume that `blkproducera` was chosen as the lead block producer to propose the transaction. - -The lead block producer (`blkproducera`) should propose the transaction stored in create_wrap_account_trx.json: -```sh -cleos multisig propose_trx createwrap producer_permissions.json create_wrap_account_trx.json blkproducera -``` -```console -executed transaction: bf6aaa06b40e2a35491525cb11431efd2b5ac94e4a7a9c693c5bf0cfed942393 744 bytes 772 us -# eosio.msig <= eosio.msig::propose {"proposer":"blkproducera","proposal_name":"createwrap","requested":[{"actor":"blkproducera","permis... -warning: transaction executed locally, but may not be confirmed by the network yet -``` - -### 1.1.3 Review and approve the transaction to create the eosio.wrap account - -Each of the potential approvers of the proposed transaction (i.e. the active block producers) should first review the proposed transaction to make sure they are not approving anything that they do not agree to. - -The proposed transaction can be reviewed using the `cleos multisig review` command: -```sh -cleos multisig review blkproducera createwrap > create_wrap_account_trx_to_review.json -head -n 30 create_wrap_account_trx_to_review.json -``` -```json -{ - "proposal_name": "createwrap", - "packed_transaction": "c0593f5b00000000000000000000040000000000ea305500409e9a2264b89a010000000000ea305500000000a8ed3232420000000000ea305500004d1a03ea30550100000000010000000000ea305500000000a8ed32320100000100000000010000000000ea305500000000a8ed32320100000000000000ea305500b0cafe4873bd3e010000000000ea305500000000a8ed3232140000000000ea305500004d1a03ea3055002800000000000000ea305500003f2a1ba6a24a010000000000ea305500000000a8ed3232310000000000ea305500004d1a03ea30551027000000000000045359530000000010270000000000000453595300000000010000000000ea305500000060bb5bb3c2010000000000ea305500000000a8ed32320900004d1a03ea30550100", - "transaction": { - "expiration": "2018-07-06T12:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "newaccount", - "authorization": [{ - "actor": "eosio", - "permission": "active" - } - ], - "data": { - "creator": "eosio", - "name": "eosio.wrap", - "owner": { - "threshold": 1, - "keys": [], - "accounts": [{ - "permission": { - "actor": "eosio", - "permission": "active" - }, -``` - -The approvers should go through the full human-readable transaction output and make sure everything looks fine. But they can also use tools to automatically compare the proposed transaction to the one they generated to make sure there are absolutely no differences: -```sh -cleos multisig propose_trx -j -s -d createwrap '[]' create_wrap_account_trx.json blkproducera | grep '"data":' | sed 's/^[ \t]*"data":[ \t]*//;s/[",]//g' | cut -c 35- > expected_create_wrap_trx_serialized.hex -cat expected_create_wrap_trx_serialized.hex -``` -```console -c0593f5b00000000000000000000040000000000ea305500409e9a2264b89a010000000000ea305500000000a8ed3232420000000000ea305500004d1a03ea30550100000000010000000000ea305500000000a8ed32320100000100000000010000000000ea305500000000a8ed32320100000000000000ea305500b0cafe4873bd3e010000000000ea305500000000a8ed3232140000000000ea305500004d1a03ea3055002800000000000000ea305500003f2a1ba6a24a010000000000ea305500000000a8ed3232310000000000ea305500004d1a03ea30551027000000000000045359530000000010270000000000000453595300000000010000000000ea305500000060bb5bb3c2010000000000ea305500000000a8ed32320900004d1a03ea30550100 -``` -```sh -cat create_wrap_account_trx_to_review.json | grep '"packed_transaction":' | sed 's/^[ \t]*"packed_transaction":[ \t]*//;s/[",]//g' > proposed_create_wrap_trx_serialized.hex -cat proposed_create_wrap_trx_serialized.hex -``` -```console -c0593f5b00000000000000000000040000000000ea305500409e9a2264b89a010000000000ea305500000000a8ed3232420000000000ea305500004d1a03ea30550100000000010000000000ea305500000000a8ed32320100000100000000010000000000ea305500000000a8ed32320100000000000000ea305500b0cafe4873bd3e010000000000ea305500000000a8ed3232140000000000ea305500004d1a03ea3055002800000000000000ea305500003f2a1ba6a24a010000000000ea305500000000a8ed3232310000000000ea305500004d1a03ea30551027000000000000045359530000000010270000000000000453595300000000010000000000ea305500000060bb5bb3c2010000000000ea305500000000a8ed32320900004d1a03ea30550100 -``` -```sh -diff expected_create_wrap_trx_serialized.hex proposed_create_wrap_trx_serialized.hex -``` - -When an approver (e.g. `blkproducerb`) is satisfied with the proposed transaction, they can simply approve it: -```sh -cleos multisig approve blkproducera createwrap '{"actor": "blkproducerb", "permission": "active"}' -p blkproducerb -``` -```console -executed transaction: 03a907e2a3192aac0cd040c73db8273c9da7696dc7960de22b1a479ae5ee9f23 128 bytes 472 us -# eosio.msig <= eosio.msig::approve {"proposer":"blkproducera","proposal_name":"createwrap","level":{"actor":"blkproducerb","permission"... -warning: transaction executed locally, but may not be confirmed by the network yet -``` - -### 1.1.4 Execute the transaction to create the eosio.wrap account - -When the necessary approvals are collected (in this example, with 21 block producers, at least 15 of their approvals were required), anyone can push the `eosio.msig::exec` action which executes the approved transaction. It makes a lot of sense for the lead block producer who proposed the transaction to also execute it (this will incur another temporary RAM cost for the deferred transaction that is generated by the eosio.msig contract). - -```sh -cleos multisig exec blkproducera createwrap blkproducera -``` -```console -executed transaction: 7ecc183b99915cc411f96dde7c35c3fe0df6e732507f272af3a039b706482e5a 160 bytes 850 us -# eosio.msig <= eosio.msig::exec {"proposer":"blkproducera","proposal_name":"createwrap","executer":"blkproducera"} -warning: transaction executed locally, but may not be confirmed by the network yet -``` - -Anyone can now verify that the `eosio.wrap` was created: -```sh -cleos get account eosio.wrap -``` -```console -privileged: true -permissions: - owner 1: 1 eosio@active, - active 1: 1 eosio@active, -memory: - quota: 49.74 KiB used: 3.33 KiB - -net bandwidth: - staked: 1.0000 SYS (total stake delegated from account to self) - delegated: 0.0000 SYS (total staked delegated to account from others) - used: 0 bytes - available: 2.304 MiB - limit: 2.304 MiB - -cpu bandwidth: - staked: 1.0000 SYS (total stake delegated from account to self) - delegated: 0.0000 SYS (total staked delegated to account from others) - used: 0 us - available: 460.8 ms - limit: 460.8 ms - -producers: -``` - -## 1.2 Deploy the eosio.wrap contract - -### 1.2.1 Generate the transaction to deploy the eosio.wrap contract - -The transaction to deploy the contract to the `eosio.wrap` account will need to be proposed to get the necessary approvals from active block producers before executing it. This transaction needs to first be generated and stored as JSON into a file so that it can be used in the cleos command to propose the transaction to the eosio.msig contract. - -The easy way to generate this transaction is using cleos: -```sh -cleos set contract -s -j -d eosio.wrap contracts/eosio.wrap/ > deploy_wrap_contract_trx.json -``` -```console -Reading WAST/WASM from contracts/eosio.wrap/eosio.wrap.wasm... -Using already assembled WASM... -Publishing contract... -``` -```sh -cat deploy_wrap_contract_trx.json -``` -```json -{ - "expiration": "2018-06-29T19:55:26", - "ref_block_num": 18544, - "ref_block_prefix": 562790588, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "setcode", - "authorization": [{ - "actor": "eosio.wrap", - "permission": "active" - } - ], - "data": "00004d1a03ea30550000c8180061736d01000000013e0c60017f006000017e60027e7e0060017e006000017f60027f7f017f60027f7f0060037f7f7f017f60057f7e7f7f7f0060000060037e7e7e0060017f017f029d010803656e7610616374696f6e5f646174615f73697a65000403656e760c63757272656e745f74696d65000103656e760c656f73696f5f617373657274000603656e76066d656d637079000703656e7610726561645f616374696f6e5f64617461000503656e760c726571756972655f61757468000303656e760d726571756972655f6175746832000203656e760d73656e645f64656665727265640008030f0e0505050400000a05070b050b000904050170010202050301000107c7010b066d656d6f72790200165f5a6571524b3131636865636b73756d32353653315f0008165f5a6571524b3131636865636b73756d31363053315f0009165f5a6e65524b3131636865636b73756d31363053315f000a036e6f77000b305f5a4e35656f73696f3132726571756972655f6175746845524b4e535f31367065726d697373696f6e5f6c6576656c45000c155f5a4e35656f73696f347375646f34657865634576000d056170706c79000e066d656d636d700010066d616c6c6f630011046672656500140908010041000b02150d0a9a130e0b002000200141201010450b0b002000200141201010450b0d0020002001412010104100470b0a00100142c0843d80a70b0e002000290300200029030810060b9e0102017e027f410028020441206b2202210341002002360204200029030010050240024010002200418104490d002000101121020c010b410020022000410f6a4170716b22023602040b2002200010041a200041074b41101002200341186a2002410810031a2003290318100520032903182101200310013703002003200137030820032003290318200241086a2000410010074100200341206a3602040bfd0403027f047e017f4100410028020441206b220936020442002106423b2105412021044200210703400240024002400240024020064206560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b024020072002520d0042002106423b2105413021044200210703400240024002400240024020064204560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b200720015141c00010020b0240024020012000510d0042002106423b2105412021044200210703400240024002400240024020064206560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b20072002520d010b20092000370318200242808080808080a0aad700520d00200941003602142009410136021020092009290310370208200941186a200941086a100f1a0b4100200941206a3602040b8c0101047f4100280204220521042001280204210220012802002101024010002203450d00024020034180044d0d00200310112205200310041a200510140c010b410020052003410f6a4170716b22053602042005200310041a0b200020024101756a210302402002410171450d00200328020020016a28020021010b200320011100004100200436020441010b4901037f4100210502402002450d000240034020002d0000220320012d00002204470d01200141016a2101200041016a21002002417f6a22020d000c020b0b200320046b21050b20050b0900418001200010120bcd04010c7f02402001450d00024020002802c041220d0d004110210d200041c0c1006a41103602000b200141086a200141046a41077122026b200120021b210202400240024020002802c441220a200d4f0d002000200a410c6c6a4180c0006a21010240200a0d0020004184c0006a220d2802000d0020014180c000360200200d20003602000b200241046a210a034002402001280208220d200a6a20012802004b0d002001280204200d6a220d200d28020041808080807871200272360200200141086a22012001280200200a6a360200200d200d28020041808080807872360200200d41046a22010d030b2000101322010d000b0b41fcffffff0720026b2104200041c8c1006a210b200041c0c1006a210c20002802c8412203210d03402000200d410c6c6a22014188c0006a28020020014180c0006a22052802004641d0c200100220014184c0006a280200220641046a210d0340200620052802006a2107200d417c6a2208280200220941ffffffff07712101024020094100480d000240200120024f0d000340200d20016a220a20074f0d01200a280200220a4100480d012001200a41ffffffff07716a41046a22012002490d000b0b20082001200220012002491b200941808080807871723602000240200120024d0d00200d20026a200420016a41ffffffff07713602000b200120024f0d040b200d20016a41046a220d2007490d000b41002101200b4100200b28020041016a220d200d200c280200461b220d360200200d2003470d000b0b20010f0b2008200828020041808080807872360200200d0f0b41000b870501087f20002802c44121010240024041002d00a643450d0041002802a84321070c010b3f002107410041013a00a6434100200741107422073602a8430b200721030240024002400240200741ffff036a41107622023f0022084d0d00200220086b40001a4100210820023f00470d0141002802a84321030b41002108410020033602a84320074100480d0020002001410c6c6a210220074180800441808008200741ffff037122084181f8034922061b6a2008200741ffff077120061b6b20076b2107024041002d00a6430d003f002103410041013a00a6434100200341107422033602a8430b20024180c0006a210220074100480d01200321060240200741076a417871220520036a41ffff036a41107622083f0022044d0d00200820046b40001a20083f00470d0241002802a84321060b4100200620056a3602a8432003417f460d0120002001410c6c6a22014184c0006a2802002206200228020022086a2003460d020240200820014188c0006a22052802002201460d00200620016a2206200628020041808080807871417c20016b20086a72360200200520022802003602002006200628020041ffffffff07713602000b200041c4c1006a2202200228020041016a220236020020002002410c6c6a22004184c0006a200336020020004180c0006a220820073602000b20080f0b02402002280200220820002001410c6c6a22034188c0006a22012802002207460d0020034184c0006a28020020076a2203200328020041808080807871417c20076b20086a72360200200120022802003602002003200328020041ffffffff07713602000b2000200041c4c1006a220728020041016a22033602c0412007200336020041000f0b2002200820076a36020020020b7b01037f024002402000450d0041002802c04222024101480d004180c10021032002410c6c4180c1006a21010340200341046a2802002202450d010240200241046a20004b0d00200220032802006a20004b0d030b2003410c6a22032001490d000b0b0f0b2000417c6a2203200328020041ffffffff07713602000b0300000b0bcf01060041040b04b04900000041100b0572656164000041200b086f6e6572726f72000041300b06656f73696f000041c0000b406f6e6572726f7220616374696f6e277320617265206f6e6c792076616c69642066726f6d207468652022656f73696f222073797374656d206163636f756e74000041d0c2000b566d616c6c6f635f66726f6d5f6672656564207761732064657369676e656420746f206f6e6c792062652063616c6c6564206166746572205f686561702077617320636f6d706c6574656c7920616c6c6f636174656400" - },{ - "account": "eosio", - "name": "setabi", - "authorization": [{ - "actor": "eosio.wrap", - "permission": "active" - } - ], - "data": "00004d1a03ea3055df040e656f73696f3a3a6162692f312e30030c6163636f756e745f6e616d65046e616d650f7065726d697373696f6e5f6e616d65046e616d650b616374696f6e5f6e616d65046e616d6506107065726d697373696f6e5f6c6576656c0002056163746f720c6163636f756e745f6e616d650a7065726d697373696f6e0f7065726d697373696f6e5f6e616d6506616374696f6e0004076163636f756e740c6163636f756e745f6e616d65046e616d650b616374696f6e5f6e616d650d617574686f72697a6174696f6e127065726d697373696f6e5f6c6576656c5b5d0464617461056279746573127472616e73616374696f6e5f68656164657200060a65787069726174696f6e0e74696d655f706f696e745f7365630d7265665f626c6f636b5f6e756d0675696e743136107265665f626c6f636b5f7072656669780675696e743332136d61785f6e65745f75736167655f776f7264730976617275696e743332106d61785f6370755f75736167655f6d730575696e74380964656c61795f7365630976617275696e74333209657874656e73696f6e000204747970650675696e74313604646174610562797465730b7472616e73616374696f6e127472616e73616374696f6e5f6865616465720314636f6e746578745f667265655f616374696f6e7308616374696f6e5b5d07616374696f6e7308616374696f6e5b5d167472616e73616374696f6e5f657874656e73696f6e730b657874656e73696f6e5b5d046578656300020865786563757465720c6163636f756e745f6e616d65037472780b7472616e73616374696f6e01000000000080545704657865630000000000" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -Once again, as described in sub-section 2.1.1, edit the values of the `ref_block_num` and `ref_block_prefix` fields to be 0 and edit the time of the `expiration` field to some point in the future that provides enough time to approve and execute the proposed transaction. After editing deploy_wrap_contract_trx.json the first few lines of it may look something like the following: -```sh -head -n 9 deploy_wrap_contract_trx.json -``` -```json -{ - "expiration": "2018-07-06T12:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ -``` - -This guide will assume that there are 21 active block producers on the chain with account names: `blkproducera`, `blkproducerb`, ..., `blkproduceru`. The end of sub-section 2.1.1 displayed what the JSON of the active permissions of each of the active block producers would look like given the assumptions about the active block producer set. That JSON was stored in the file producer_permissions.json; if the approvers (i.e. block producers) have not created that file already, they should create that file now as shown at the end of sub-section 2.1.1. - -### 1.2.2 Propose the transaction to deploy the eosio.wrap contract - -Only one of the potential approvers will need to propose the transaction that was created in the previous sub-section. All the other approvers should still follow the steps in the previous sub-section to generate the same deploy_wrap_contract_trx.json file as all the other approvers. They will need this to compare to the actual proposed transaction prior to approving. - -The approvers are typically going to be the active block producers of the chain, so it makes sense that one of the block producers is elected as the leader to propose the actual transaction. Note that this lead block producer will need to incur the temporary RAM cost of proposing the transaction, but they will get the RAM back when the proposal has executed or has been canceled (which only the proposer can do prior to expiration). - -This guide will assume that `blkproducera` was chosen as the lead block producer to propose the transaction. - -The lead block producer (`blkproducera`) should propose the transaction stored in deploy_wrap_contract_trx.json: -```sh -cleos multisig propose_trx deploywrap producer_permissions.json deploy_wrap_contract_trx.json blkproducera -``` -```console -executed transaction: 9e50dd40eba25583a657ee8114986a921d413b917002c8fb2d02e2d670f720a8 4312 bytes 871 us -# eosio.msig <= eosio.msig::propose {"proposer":"blkproducera","proposal_name":"deploywrap","requested":[{"actor":"blkproducera","permis... -warning: transaction executed locally, but may not be confirmed by the network yet -``` - -### 1.2.3 Review and approve the transaction to deploy the eosio.wrap contract - -Each of the potential approvers of the proposed transaction (i.e. the active block producers) should first review the proposed transaction to make sure they are not approving anything that they do not agree to. - -The proposed transaction can be reviewed using the `cleos multisig review` command: -```sh -cleos multisig review blkproducera deploywrap > deploy_wrap_contract_trx_to_review.json -cat deploy_wrap_contract_trx_to_review.json -``` -```json -{ - "proposal_name": "deploywrap", - "packed_transaction": "c0593f5b00000000000000000000020000000000ea305500000040258ab2c20100004d1a03ea305500000000a8ed3232d41800004d1a03ea30550000c8180061736d01000000013e0c60017f006000017e60027e7e0060017e006000017f60027f7f017f60027f7f0060037f7f7f017f60057f7e7f7f7f0060000060037e7e7e0060017f017f029d010803656e7610616374696f6e5f646174615f73697a65000403656e760c63757272656e745f74696d65000103656e760c656f73696f5f617373657274000603656e76066d656d637079000703656e7610726561645f616374696f6e5f64617461000503656e760c726571756972655f61757468000303656e760d726571756972655f6175746832000203656e760d73656e645f64656665727265640008030f0e0505050400000a05070b050b000904050170010202050301000107c7010b066d656d6f72790200165f5a6571524b3131636865636b73756d32353653315f0008165f5a6571524b3131636865636b73756d31363053315f0009165f5a6e65524b3131636865636b73756d31363053315f000a036e6f77000b305f5a4e35656f73696f3132726571756972655f6175746845524b4e535f31367065726d697373696f6e5f6c6576656c45000c155f5a4e35656f73696f347375646f34657865634576000d056170706c79000e066d656d636d700010066d616c6c6f630011046672656500140908010041000b02150d0a9a130e0b002000200141201010450b0b002000200141201010450b0d0020002001412010104100470b0a00100142c0843d80a70b0e002000290300200029030810060b9e0102017e027f410028020441206b2202210341002002360204200029030010050240024010002200418104490d002000101121020c010b410020022000410f6a4170716b22023602040b2002200010041a200041074b41101002200341186a2002410810031a2003290318100520032903182101200310013703002003200137030820032003290318200241086a2000410010074100200341206a3602040bfd0403027f047e017f4100410028020441206b220936020442002106423b2105412021044200210703400240024002400240024020064206560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b024020072002520d0042002106423b2105413021044200210703400240024002400240024020064204560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b200720015141c00010020b0240024020012000510d0042002106423b2105412021044200210703400240024002400240024020064206560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b20072002520d010b20092000370318200242808080808080a0aad700520d00200941003602142009410136021020092009290310370208200941186a200941086a100f1a0b4100200941206a3602040b8c0101047f4100280204220521042001280204210220012802002101024010002203450d00024020034180044d0d00200310112205200310041a200510140c010b410020052003410f6a4170716b22053602042005200310041a0b200020024101756a210302402002410171450d00200328020020016a28020021010b200320011100004100200436020441010b4901037f4100210502402002450d000240034020002d0000220320012d00002204470d01200141016a2101200041016a21002002417f6a22020d000c020b0b200320046b21050b20050b0900418001200010120bcd04010c7f02402001450d00024020002802c041220d0d004110210d200041c0c1006a41103602000b200141086a200141046a41077122026b200120021b210202400240024020002802c441220a200d4f0d002000200a410c6c6a4180c0006a21010240200a0d0020004184c0006a220d2802000d0020014180c000360200200d20003602000b200241046a210a034002402001280208220d200a6a20012802004b0d002001280204200d6a220d200d28020041808080807871200272360200200141086a22012001280200200a6a360200200d200d28020041808080807872360200200d41046a22010d030b2000101322010d000b0b41fcffffff0720026b2104200041c8c1006a210b200041c0c1006a210c20002802c8412203210d03402000200d410c6c6a22014188c0006a28020020014180c0006a22052802004641d0c200100220014184c0006a280200220641046a210d0340200620052802006a2107200d417c6a2208280200220941ffffffff07712101024020094100480d000240200120024f0d000340200d20016a220a20074f0d01200a280200220a4100480d012001200a41ffffffff07716a41046a22012002490d000b0b20082001200220012002491b200941808080807871723602000240200120024d0d00200d20026a200420016a41ffffffff07713602000b200120024f0d040b200d20016a41046a220d2007490d000b41002101200b4100200b28020041016a220d200d200c280200461b220d360200200d2003470d000b0b20010f0b2008200828020041808080807872360200200d0f0b41000b870501087f20002802c44121010240024041002d00a643450d0041002802a84321070c010b3f002107410041013a00a6434100200741107422073602a8430b200721030240024002400240200741ffff036a41107622023f0022084d0d00200220086b40001a4100210820023f00470d0141002802a84321030b41002108410020033602a84320074100480d0020002001410c6c6a210220074180800441808008200741ffff037122084181f8034922061b6a2008200741ffff077120061b6b20076b2107024041002d00a6430d003f002103410041013a00a6434100200341107422033602a8430b20024180c0006a210220074100480d01200321060240200741076a417871220520036a41ffff036a41107622083f0022044d0d00200820046b40001a20083f00470d0241002802a84321060b4100200620056a3602a8432003417f460d0120002001410c6c6a22014184c0006a2802002206200228020022086a2003460d020240200820014188c0006a22052802002201460d00200620016a2206200628020041808080807871417c20016b20086a72360200200520022802003602002006200628020041ffffffff07713602000b200041c4c1006a2202200228020041016a220236020020002002410c6c6a22004184c0006a200336020020004180c0006a220820073602000b20080f0b02402002280200220820002001410c6c6a22034188c0006a22012802002207460d0020034184c0006a28020020076a2203200328020041808080807871417c20076b20086a72360200200120022802003602002003200328020041ffffffff07713602000b2000200041c4c1006a220728020041016a22033602c0412007200336020041000f0b2002200820076a36020020020b7b01037f024002402000450d0041002802c04222024101480d004180c10021032002410c6c4180c1006a21010340200341046a2802002202450d010240200241046a20004b0d00200220032802006a20004b0d030b2003410c6a22032001490d000b0b0f0b2000417c6a2203200328020041ffffffff07713602000b0300000b0bcf01060041040b04b04900000041100b0572656164000041200b086f6e6572726f72000041300b06656f73696f000041c0000b406f6e6572726f7220616374696f6e277320617265206f6e6c792076616c69642066726f6d207468652022656f73696f222073797374656d206163636f756e74000041d0c2000b566d616c6c6f635f66726f6d5f6672656564207761732064657369676e656420746f206f6e6c792062652063616c6c6564206166746572205f686561702077617320636f6d706c6574656c7920616c6c6f6361746564000000000000ea305500000000b863b2c20100004d1a03ea305500000000a8ed3232e90400004d1a03ea3055df040e656f73696f3a3a6162692f312e30030c6163636f756e745f6e616d65046e616d650f7065726d697373696f6e5f6e616d65046e616d650b616374696f6e5f6e616d65046e616d6506107065726d697373696f6e5f6c6576656c0002056163746f720c6163636f756e745f6e616d650a7065726d697373696f6e0f7065726d697373696f6e5f6e616d6506616374696f6e0004076163636f756e740c6163636f756e745f6e616d65046e616d650b616374696f6e5f6e616d650d617574686f72697a6174696f6e127065726d697373696f6e5f6c6576656c5b5d0464617461056279746573127472616e73616374696f6e5f68656164657200060a65787069726174696f6e0e74696d655f706f696e745f7365630d7265665f626c6f636b5f6e756d0675696e743136107265665f626c6f636b5f7072656669780675696e743332136d61785f6e65745f75736167655f776f7264730976617275696e743332106d61785f6370755f75736167655f6d730575696e74380964656c61795f7365630976617275696e74333209657874656e73696f6e000204747970650675696e74313604646174610562797465730b7472616e73616374696f6e127472616e73616374696f6e5f6865616465720314636f6e746578745f667265655f616374696f6e7308616374696f6e5b5d07616374696f6e7308616374696f6e5b5d167472616e73616374696f6e5f657874656e73696f6e730b657874656e73696f6e5b5d046578656300020865786563757465720c6163636f756e745f6e616d65037472780b7472616e73616374696f6e0100000000008054570465786563000000000000", - "transaction": { - "expiration": "2018-07-06T12:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "setcode", - "authorization": [{ - "actor": "eosio.wrap", - "permission": "active" - } - ], - "data": { - "account": "eosio.wrap", - "vmtype": 0, - "vmversion": 0, - "code": "0061736d01000000013e0c60017f006000017e60027e7e0060017e006000017f60027f7f017f60027f7f0060037f7f7f017f60057f7e7f7f7f0060000060037e7e7e0060017f017f029d010803656e7610616374696f6e5f646174615f73697a65000403656e760c63757272656e745f74696d65000103656e760c656f73696f5f617373657274000603656e76066d656d637079000703656e7610726561645f616374696f6e5f64617461000503656e760c726571756972655f61757468000303656e760d726571756972655f6175746832000203656e760d73656e645f64656665727265640008030f0e0505050400000a05070b050b000904050170010202050301000107c7010b066d656d6f72790200165f5a6571524b3131636865636b73756d32353653315f0008165f5a6571524b3131636865636b73756d31363053315f0009165f5a6e65524b3131636865636b73756d31363053315f000a036e6f77000b305f5a4e35656f73696f3132726571756972655f6175746845524b4e535f31367065726d697373696f6e5f6c6576656c45000c155f5a4e35656f73696f347375646f34657865634576000d056170706c79000e066d656d636d700010066d616c6c6f630011046672656500140908010041000b02150d0a9a130e0b002000200141201010450b0b002000200141201010450b0d0020002001412010104100470b0a00100142c0843d80a70b0e002000290300200029030810060b9e0102017e027f410028020441206b2202210341002002360204200029030010050240024010002200418104490d002000101121020c010b410020022000410f6a4170716b22023602040b2002200010041a200041074b41101002200341186a2002410810031a2003290318100520032903182101200310013703002003200137030820032003290318200241086a2000410010074100200341206a3602040bfd0403027f047e017f4100410028020441206b220936020442002106423b2105412021044200210703400240024002400240024020064206560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b024020072002520d0042002106423b2105413021044200210703400240024002400240024020064204560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b200720015141c00010020b0240024020012000510d0042002106423b2105412021044200210703400240024002400240024020064206560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b20072002520d010b20092000370318200242808080808080a0aad700520d00200941003602142009410136021020092009290310370208200941186a200941086a100f1a0b4100200941206a3602040b8c0101047f4100280204220521042001280204210220012802002101024010002203450d00024020034180044d0d00200310112205200310041a200510140c010b410020052003410f6a4170716b22053602042005200310041a0b200020024101756a210302402002410171450d00200328020020016a28020021010b200320011100004100200436020441010b4901037f4100210502402002450d000240034020002d0000220320012d00002204470d01200141016a2101200041016a21002002417f6a22020d000c020b0b200320046b21050b20050b0900418001200010120bcd04010c7f02402001450d00024020002802c041220d0d004110210d200041c0c1006a41103602000b200141086a200141046a41077122026b200120021b210202400240024020002802c441220a200d4f0d002000200a410c6c6a4180c0006a21010240200a0d0020004184c0006a220d2802000d0020014180c000360200200d20003602000b200241046a210a034002402001280208220d200a6a20012802004b0d002001280204200d6a220d200d28020041808080807871200272360200200141086a22012001280200200a6a360200200d200d28020041808080807872360200200d41046a22010d030b2000101322010d000b0b41fcffffff0720026b2104200041c8c1006a210b200041c0c1006a210c20002802c8412203210d03402000200d410c6c6a22014188c0006a28020020014180c0006a22052802004641d0c200100220014184c0006a280200220641046a210d0340200620052802006a2107200d417c6a2208280200220941ffffffff07712101024020094100480d000240200120024f0d000340200d20016a220a20074f0d01200a280200220a4100480d012001200a41ffffffff07716a41046a22012002490d000b0b20082001200220012002491b200941808080807871723602000240200120024d0d00200d20026a200420016a41ffffffff07713602000b200120024f0d040b200d20016a41046a220d2007490d000b41002101200b4100200b28020041016a220d200d200c280200461b220d360200200d2003470d000b0b20010f0b2008200828020041808080807872360200200d0f0b41000b870501087f20002802c44121010240024041002d00a643450d0041002802a84321070c010b3f002107410041013a00a6434100200741107422073602a8430b200721030240024002400240200741ffff036a41107622023f0022084d0d00200220086b40001a4100210820023f00470d0141002802a84321030b41002108410020033602a84320074100480d0020002001410c6c6a210220074180800441808008200741ffff037122084181f8034922061b6a2008200741ffff077120061b6b20076b2107024041002d00a6430d003f002103410041013a00a6434100200341107422033602a8430b20024180c0006a210220074100480d01200321060240200741076a417871220520036a41ffff036a41107622083f0022044d0d00200820046b40001a20083f00470d0241002802a84321060b4100200620056a3602a8432003417f460d0120002001410c6c6a22014184c0006a2802002206200228020022086a2003460d020240200820014188c0006a22052802002201460d00200620016a2206200628020041808080807871417c20016b20086a72360200200520022802003602002006200628020041ffffffff07713602000b200041c4c1006a2202200228020041016a220236020020002002410c6c6a22004184c0006a200336020020004180c0006a220820073602000b20080f0b02402002280200220820002001410c6c6a22034188c0006a22012802002207460d0020034184c0006a28020020076a2203200328020041808080807871417c20076b20086a72360200200120022802003602002003200328020041ffffffff07713602000b2000200041c4c1006a220728020041016a22033602c0412007200336020041000f0b2002200820076a36020020020b7b01037f024002402000450d0041002802c04222024101480d004180c10021032002410c6c4180c1006a21010340200341046a2802002202450d010240200241046a20004b0d00200220032802006a20004b0d030b2003410c6a22032001490d000b0b0f0b2000417c6a2203200328020041ffffffff07713602000b0300000b0bcf01060041040b04b04900000041100b0572656164000041200b086f6e6572726f72000041300b06656f73696f000041c0000b406f6e6572726f7220616374696f6e277320617265206f6e6c792076616c69642066726f6d207468652022656f73696f222073797374656d206163636f756e74000041d0c2000b566d616c6c6f635f66726f6d5f6672656564207761732064657369676e656420746f206f6e6c792062652063616c6c6564206166746572205f686561702077617320636f6d706c6574656c7920616c6c6f636174656400" - }, - "hex_data": "00004d1a03ea30550000c8180061736d01000000013e0c60017f006000017e60027e7e0060017e006000017f60027f7f017f60027f7f0060037f7f7f017f60057f7e7f7f7f0060000060037e7e7e0060017f017f029d010803656e7610616374696f6e5f646174615f73697a65000403656e760c63757272656e745f74696d65000103656e760c656f73696f5f617373657274000603656e76066d656d637079000703656e7610726561645f616374696f6e5f64617461000503656e760c726571756972655f61757468000303656e760d726571756972655f6175746832000203656e760d73656e645f64656665727265640008030f0e0505050400000a05070b050b000904050170010202050301000107c7010b066d656d6f72790200165f5a6571524b3131636865636b73756d32353653315f0008165f5a6571524b3131636865636b73756d31363053315f0009165f5a6e65524b3131636865636b73756d31363053315f000a036e6f77000b305f5a4e35656f73696f3132726571756972655f6175746845524b4e535f31367065726d697373696f6e5f6c6576656c45000c155f5a4e35656f73696f347375646f34657865634576000d056170706c79000e066d656d636d700010066d616c6c6f630011046672656500140908010041000b02150d0a9a130e0b002000200141201010450b0b002000200141201010450b0d0020002001412010104100470b0a00100142c0843d80a70b0e002000290300200029030810060b9e0102017e027f410028020441206b2202210341002002360204200029030010050240024010002200418104490d002000101121020c010b410020022000410f6a4170716b22023602040b2002200010041a200041074b41101002200341186a2002410810031a2003290318100520032903182101200310013703002003200137030820032003290318200241086a2000410010074100200341206a3602040bfd0403027f047e017f4100410028020441206b220936020442002106423b2105412021044200210703400240024002400240024020064206560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b024020072002520d0042002106423b2105413021044200210703400240024002400240024020064204560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b200720015141c00010020b0240024020012000510d0042002106423b2105412021044200210703400240024002400240024020064206560d0020042c00002203419f7f6a41ff017141194b0d01200341a5016a21030c020b420021082006420b580d020c030b200341d0016a41002003414f6a41ff01714105491b21030b2003ad42388642388721080b2008421f83200542ffffffff0f838621080b200441016a2104200642017c2106200820078421072005427b7c2205427a520d000b20072002520d010b20092000370318200242808080808080a0aad700520d00200941003602142009410136021020092009290310370208200941186a200941086a100f1a0b4100200941206a3602040b8c0101047f4100280204220521042001280204210220012802002101024010002203450d00024020034180044d0d00200310112205200310041a200510140c010b410020052003410f6a4170716b22053602042005200310041a0b200020024101756a210302402002410171450d00200328020020016a28020021010b200320011100004100200436020441010b4901037f4100210502402002450d000240034020002d0000220320012d00002204470d01200141016a2101200041016a21002002417f6a22020d000c020b0b200320046b21050b20050b0900418001200010120bcd04010c7f02402001450d00024020002802c041220d0d004110210d200041c0c1006a41103602000b200141086a200141046a41077122026b200120021b210202400240024020002802c441220a200d4f0d002000200a410c6c6a4180c0006a21010240200a0d0020004184c0006a220d2802000d0020014180c000360200200d20003602000b200241046a210a034002402001280208220d200a6a20012802004b0d002001280204200d6a220d200d28020041808080807871200272360200200141086a22012001280200200a6a360200200d200d28020041808080807872360200200d41046a22010d030b2000101322010d000b0b41fcffffff0720026b2104200041c8c1006a210b200041c0c1006a210c20002802c8412203210d03402000200d410c6c6a22014188c0006a28020020014180c0006a22052802004641d0c200100220014184c0006a280200220641046a210d0340200620052802006a2107200d417c6a2208280200220941ffffffff07712101024020094100480d000240200120024f0d000340200d20016a220a20074f0d01200a280200220a4100480d012001200a41ffffffff07716a41046a22012002490d000b0b20082001200220012002491b200941808080807871723602000240200120024d0d00200d20026a200420016a41ffffffff07713602000b200120024f0d040b200d20016a41046a220d2007490d000b41002101200b4100200b28020041016a220d200d200c280200461b220d360200200d2003470d000b0b20010f0b2008200828020041808080807872360200200d0f0b41000b870501087f20002802c44121010240024041002d00a643450d0041002802a84321070c010b3f002107410041013a00a6434100200741107422073602a8430b200721030240024002400240200741ffff036a41107622023f0022084d0d00200220086b40001a4100210820023f00470d0141002802a84321030b41002108410020033602a84320074100480d0020002001410c6c6a210220074180800441808008200741ffff037122084181f8034922061b6a2008200741ffff077120061b6b20076b2107024041002d00a6430d003f002103410041013a00a6434100200341107422033602a8430b20024180c0006a210220074100480d01200321060240200741076a417871220520036a41ffff036a41107622083f0022044d0d00200820046b40001a20083f00470d0241002802a84321060b4100200620056a3602a8432003417f460d0120002001410c6c6a22014184c0006a2802002206200228020022086a2003460d020240200820014188c0006a22052802002201460d00200620016a2206200628020041808080807871417c20016b20086a72360200200520022802003602002006200628020041ffffffff07713602000b200041c4c1006a2202200228020041016a220236020020002002410c6c6a22004184c0006a200336020020004180c0006a220820073602000b20080f0b02402002280200220820002001410c6c6a22034188c0006a22012802002207460d0020034184c0006a28020020076a2203200328020041808080807871417c20076b20086a72360200200120022802003602002003200328020041ffffffff07713602000b2000200041c4c1006a220728020041016a22033602c0412007200336020041000f0b2002200820076a36020020020b7b01037f024002402000450d0041002802c04222024101480d004180c10021032002410c6c4180c1006a21010340200341046a2802002202450d010240200241046a20004b0d00200220032802006a20004b0d030b2003410c6a22032001490d000b0b0f0b2000417c6a2203200328020041ffffffff07713602000b0300000b0bcf01060041040b04b04900000041100b0572656164000041200b086f6e6572726f72000041300b06656f73696f000041c0000b406f6e6572726f7220616374696f6e277320617265206f6e6c792076616c69642066726f6d207468652022656f73696f222073797374656d206163636f756e74000041d0c2000b566d616c6c6f635f66726f6d5f6672656564207761732064657369676e656420746f206f6e6c792062652063616c6c6564206166746572205f686561702077617320636f6d706c6574656c7920616c6c6f636174656400" - },{ - "account": "eosio", - "name": "setabi", - "authorization": [{ - "actor": "eosio.wrap", - "permission": "active" - } - ], - "data": { - "account": "eosio.wrap", - "abi": "0e656f73696f3a3a6162692f312e30030c6163636f756e745f6e616d65046e616d650f7065726d697373696f6e5f6e616d65046e616d650b616374696f6e5f6e616d65046e616d6506107065726d697373696f6e5f6c6576656c0002056163746f720c6163636f756e745f6e616d650a7065726d697373696f6e0f7065726d697373696f6e5f6e616d6506616374696f6e0004076163636f756e740c6163636f756e745f6e616d65046e616d650b616374696f6e5f6e616d650d617574686f72697a6174696f6e127065726d697373696f6e5f6c6576656c5b5d0464617461056279746573127472616e73616374696f6e5f68656164657200060a65787069726174696f6e0e74696d655f706f696e745f7365630d7265665f626c6f636b5f6e756d0675696e743136107265665f626c6f636b5f7072656669780675696e743332136d61785f6e65745f75736167655f776f7264730976617275696e743332106d61785f6370755f75736167655f6d730575696e74380964656c61795f7365630976617275696e74333209657874656e73696f6e000204747970650675696e74313604646174610562797465730b7472616e73616374696f6e127472616e73616374696f6e5f6865616465720314636f6e746578745f667265655f616374696f6e7308616374696f6e5b5d07616374696f6e7308616374696f6e5b5d167472616e73616374696f6e5f657874656e73696f6e730b657874656e73696f6e5b5d046578656300020865786563757465720c6163636f756e745f6e616d65037472780b7472616e73616374696f6e01000000000080545704657865630000000000" - }, - "hex_data": "00004d1a03ea3055df040e656f73696f3a3a6162692f312e30030c6163636f756e745f6e616d65046e616d650f7065726d697373696f6e5f6e616d65046e616d650b616374696f6e5f6e616d65046e616d6506107065726d697373696f6e5f6c6576656c0002056163746f720c6163636f756e745f6e616d650a7065726d697373696f6e0f7065726d697373696f6e5f6e616d6506616374696f6e0004076163636f756e740c6163636f756e745f6e616d65046e616d650b616374696f6e5f6e616d650d617574686f72697a6174696f6e127065726d697373696f6e5f6c6576656c5b5d0464617461056279746573127472616e73616374696f6e5f68656164657200060a65787069726174696f6e0e74696d655f706f696e745f7365630d7265665f626c6f636b5f6e756d0675696e743136107265665f626c6f636b5f7072656669780675696e743332136d61785f6e65745f75736167655f776f7264730976617275696e743332106d61785f6370755f75736167655f6d730575696e74380964656c61795f7365630976617275696e74333209657874656e73696f6e000204747970650675696e74313604646174610562797465730b7472616e73616374696f6e127472616e73616374696f6e5f6865616465720314636f6e746578745f667265655f616374696f6e7308616374696f6e5b5d07616374696f6e7308616374696f6e5b5d167472616e73616374696f6e5f657874656e73696f6e730b657874656e73696f6e5b5d046578656300020865786563757465720c6163636f756e745f6e616d65037472780b7472616e73616374696f6e01000000000080545704657865630000000000" - } - ], - "transaction_extensions": [] - } -} -``` - -Each approver should be able to see that the proposed transaction is setting the code and ABI of the `eosio.wrap` contract. But the data is just hex data and therefore not very meaningful to the approver. And considering that `eosio.wrap` at this point should be a privileged contract, it would be very dangerous for block producers to just allow a contract to be deployed to a privileged account without knowing exactly which WebAssembly code they are deploying and also auditing the source code that generated that WebAssembly code to ensure it is safe to deploy. - -This guide assumes that each approver has already audited the source code of the contract to be deployed and has already compiled that code to generate the WebAssembly code that should be byte-for-byte identical to the code that every other approver following the same process should have generated. The guide also assumes that this generated code and its associated ABI were provided in the steps in sub-section 2.2.1 that generated the transaction in the deploy_wrap_contract_trx.json file. It then becomes quite simple to verify that the proposed transaction is identical to the one the potential approver could have proposed with the code and ABI that they already audited: -```sh -cleos multisig propose_trx -j -s -d deploywrap '[]' deploy_wrap_contract_trx.json blkproducera | grep '"data":' | sed 's/^[ \t]*"data":[ \t]*//;s/[",]//g' | cut -c 35- > expected_deploy_wrap_trx_serialized.hex -cat expected_deploy_wrap_trx_serialized.hex | cut -c -50 -``` -```console -c0593f5b00000000000000000000020000000000ea30550000 -``` -```sh -cat deploy_wrap_account_trx_to_review.json | grep '"packed_transaction":' | sed 's/^[ \t]*"packed_transaction":[ \t]*//;s/[",]//g' > proposed_deploy_wrap_trx_serialized.hex -cat proposed_deploy_wrap_trx_serialized.hex | cut -c -50 -``` -```console -c0593f5b00000000000000000000020000000000ea30550000 -``` -```sh -diff expected_deploy_wrap_trx_serialized.hex proposed_deploy_wrap_trx_serialized.hex -``` - -When an approver (e.g. `blkproducerb`) is satisfied with the proposed transaction, they can simply approve it: -```sh -cleos multisig approve blkproducera deploywrap '{"actor": "blkproducerb", "permission": "active"}' -p blkproducerb -``` -```console -executed transaction: d1e424e05ee4d96eb079fcd5190dd0bf35eca8c27dd7231b59df8e464881abfd 128 bytes 483 us -# eosio.msig <= eosio.msig::approve {"proposer":"blkproducera","proposal_name":"deploywrap","level":{"actor":"blkproducerb","permission"... -warning: transaction executed locally, but may not be confirmed by the network yet -``` - -### 1.2.4 Execute the transaction to create the eosio.wrap account - -When the necessary approvals are collected (in this example, with 21 block producers, at least 15 of their approvals were required), anyone can push the `eosio.msig::exec` action which executes the approved transaction. It makes a lot of sense for the lead block producer who proposed the transaction to also execute it (this will incur another temporary RAM cost for the deferred transaction that is generated by the eosio.msig contract). - -```sh -cleos multisig exec blkproducera deploywrap blkproducera -``` -```console -executed transaction: e8da14c6f1fdc3255b5413adccfd0d89b18f832a4cc18c4324ea2beec6abd483 160 bytes 1877 us -# eosio.msig <= eosio.msig::exec {"proposer":"blkproducera","proposal_name":"deploywrap","executer":"blkproducera"} -``` - -Anyone can now verify that the `eosio.wrap` contract was deployed correctly. - -```sh -cleos get code -a retrieved-eosio.wrap.abi eosio.wrap -``` -```console -code hash: 1b3456a5eca28bcaca7a2a3360fbb2a72b9772a416c8e11a303bcb26bfe3263c -saving abi to retrieved-eosio.wrap.abi -``` -```sh -sha256sum contracts/eosio.wrap/eosio.wrap.wasm -``` -```console -1b3456a5eca28bcaca7a2a3360fbb2a72b9772a416c8e11a303bcb26bfe3263c contracts/eosio.wrap/eosio.wrap.wasm -``` - -If the two hashes match then the local WebAssembly code is the one deployed on the blockchain. The retrieved ABI, which was stored in the file retrieved-eosio.wrap.abi, can then be compared to the original ABI of the contract (contracts/eosio.wrap/eosio.wrap.abi) to ensure they are semantically the same. - -# 2. Using the eosio.wrap contract - -## 2.1 Example: Updating owner authority of an arbitrary account - -This example will demonstrate how to use the deployed eosio.wrap contract together with the eosio.msig contract to allow a greater than two-thirds supermajority of block producers of an EOSIO blockchain to change the owner authority of an arbitrary account. The example will use cleos: in particular, the `cleos multisig` command, the `cleos set account permission` sub-command, and the `cleos wrap exec` sub-command. However, the guide also demonstrates what to do if the `cleos wrap exec` sub-command is not available. - -This guide assumes that there are 21 active block producers on the chain with account names: `blkproducera`, `blkproducerb`, ..., `blkproduceru`. Block producer `blkproducera` will act as the lead block producer handling the proposal of the transaction. - -The producer permissions will later come in handy when proposing a transaction that must be approved by a supermajority of the producers. So a file producer_permissions.json containing those permission (see contents below) should be created to be used later in this guide: -```sh -cat producer_permissions.json -``` -```json -[ - {"actor": "blkproducera", "permission": "active"}, - {"actor": "blkproducerb", "permission": "active"}, - {"actor": "blkproducerc", "permission": "active"}, - {"actor": "blkproducerd", "permission": "active"}, - {"actor": "blkproducere", "permission": "active"}, - {"actor": "blkproducerf", "permission": "active"}, - {"actor": "blkproducerg", "permission": "active"}, - {"actor": "blkproducerh", "permission": "active"}, - {"actor": "blkproduceri", "permission": "active"}, - {"actor": "blkproducerj", "permission": "active"}, - {"actor": "blkproducerk", "permission": "active"}, - {"actor": "blkproducerl", "permission": "active"}, - {"actor": "blkproducerm", "permission": "active"}, - {"actor": "blkproducern", "permission": "active"}, - {"actor": "blkproducero", "permission": "active"}, - {"actor": "blkproducerp", "permission": "active"}, - {"actor": "blkproducerq", "permission": "active"}, - {"actor": "blkproducerr", "permission": "active"}, - {"actor": "blkproducers", "permission": "active"}, - {"actor": "blkproducert", "permission": "active"}, - {"actor": "blkproduceru", "permission": "active"} -] -``` - -### 2.1.1 Generate the transaction to change the owner permission of an account - -The goal of this example is for the block producers to change the owner permission of the account `alice`. - -The initial status of the `alice` account might be: -```console -permissions: - owner 1: 1 EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV - active 1: 1 EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV -memory: - quota: 49.74 KiB used: 3.365 KiB - -net bandwidth: - staked: 1.0000 SYS (total stake delegated from account to self) - delegated: 0.0000 SYS (total staked delegated to account from others) - used: 0 bytes - available: 2.304 MiB - limit: 2.304 MiB - -cpu bandwidth: - staked: 1.0000 SYS (total stake delegated from account to self) - delegated: 0.0000 SYS (total staked delegated to account from others) - used: 0 us - available: 460.8 ms - limit: 460.8 ms - -producers: -``` - -Assume that none of the block producers know the private key corresponding to the public key `EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV` which, as can be seen above, is initially securing access to the `alice` account. - -The first step is to generate the transaction changing the owner permission of the `alice` account as if `alice` is authorizing the change: -```sh -cleos set account permission -s -j -d alice owner '{"threshold": 1, "accounts": [{"permission": {"actor": "eosio", "permission": "active"}, "weight": 1}]}' > update_alice_owner_trx.json -``` - -Then modify update_alice_owner_trx.json so that the values for the `ref_block_num` and `ref_block_prefix` fields are both 0 and the value of the `expiration` field is `"1970-01-01T00:00:00"`: -```sh -cat update_alice_owner_trx.json -``` -```console -{ - "expiration": "1970-01-01T00:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "updateauth", - "authorization": [{ - "actor": "alice", - "permission": "active" - } - ], - "data": "0000000000855c340000000080ab26a700000000000000000100000000010000000000ea305500000000a8ed3232010000" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -The next step is to generate the transaction containing the `eosio.wrap::exec` action. This action will contain the transaction in update_alice_owner_trx.json as part of its action payload data. - -```sh -cleos wrap exec -s -j -d blkproducera update_alice_owner_trx.json > wrap_update_alice_owner_trx.json -``` - -Once again modify wrap_update_alice_owner_trx.json so that the value for the `ref_block_num` and `ref_block_prefix` fields are both 0. However, instead of changing the value of the expiration field to `"1970-01-01T00:00:00"`, it should be changed to a time that is far enough in the future to allow enough time for the proposed transaction to be approved and executed. -```sh -cat wrap_update_alice_owner_trx.json -``` -```json -{ - "expiration": "2018-07-06T12:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio.wrap", - "name": "exec", - "authorization": [{ - "actor": "blkproducera", - "permission": "active" - },{ - "actor": "eosio.wrap", - "permission": "active" - } - ], - "data": "60ae423ad15b613c0000000000000000000000000000010000000000ea30550040cbdaa86c52d5010000000000855c3400000000a8ed3232310000000000855c340000000080ab26a700000000000000000100000000010000000000ea305500000000a8ed323201000000" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -If the `cleos wrap` command is not available, there is an alternative way to generate the above transaction. There is no need to continue reading the remaining of sub-section 3.1.1 if the wrap_update_alice_owner_trx.json file was already generated with content similar to the above using the `cleos wrap exec` sub-command method. - -First the hex encoding of the binary serialization of the transaction in update_alice_owner_trx.json must be obtained. One way of obtaining this data is through the following command: -```sh -cleos multisig propose_trx -s -j -d nothing '[]' update_alice_owner_trx.json nothing | grep '"data":' | sed 's/^[ \t]*"data":[ \t]*//;s/[",]//g' | cut -c 35- > update_alice_owner_trx_serialized.hex -cat update_alice_owner_trx_serialized.hex -``` -```console -0000000000000000000000000000010000000000ea30550040cbdaa86c52d5010000000000855c3400000000a8ed3232310000000000855c340000000080ab26a700000000000000000100000000010000000000ea305500000000a8ed323201000000 -``` - -Then generate the template for the transaction containing the `eosio.wrap::exec` action: -```sh -cleos push action -s -j -d eosio.wrap exec '{"executer": "blkproducera", "trx": ""}' > wrap_update_alice_owner_trx.json -cat wrap_update_alice_owner_trx.json -``` -```json -{ - "expiration": "2018-06-29T23:34:01", - "ref_block_num": 23708, - "ref_block_prefix": 3605208482, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio.wrap", - "name": "exec", - "authorization": [], - "data": "60ae423ad15b613c" - } - ], - "transaction_extensions": [], - "signatures": [], - "context_free_data": [] -} -``` - -Then modify the transaction in wrap_update_alice_owner_trx.json as follows: - * replace the values of the `ref_block_num` and `ref_block_prefix` fields to 0; - * replace the time of the `expiration` field to the desired expiration time as described above (e.g. `"2018-07-06T12:00:00"`); - * append the hex data from update_alice_owner_trx_serialized.hex to the end of the existing hex data in the `data` field in wrap_update_alice_owner_trx.json. - - -### 2.1.2 Propose the transaction to change the owner permission of an account - -The lead block producer (`blkproducera`) should propose the transaction stored in wrap_update_alice_owner_trx.json: -```sh -cleos multisig propose_trx updatealice producer_permissions.json wrap_update_alice_owner_trx.json blkproducera -``` -```console -executed transaction: 10474f52c9e3fc8e729469a577cd2fc9e4330e25b3fd402fc738ddde26605c13 624 bytes 782 us -# eosio.msig <= eosio.msig::propose {"proposer":"blkproducera","proposal_name":"updatealice","requested":[{"actor":"blkproducera","permi... -warning: transaction executed locally, but may not be confirmed by the network yet -``` - -### 2.1.3 Review and approve the transaction to change the owner permission of an account - -Each of the potential approvers of the proposed transaction (i.e. the active block producers) should first review the proposed transaction to make sure they are not approving anything that they do not agree to. -```sh -cleos multisig review blkproducera updatealice > wrap_update_alice_owner_trx_to_review.json -cat wrap_update_alice_owner_trx_to_review.json -``` -```json -{ - "proposal_name": "updatealice", - "packed_transaction": "c0593f5b000000000000000000000100004d1a03ea305500000000008054570260ae423ad15b613c00000000a8ed323200004d1a03ea305500000000a8ed32326b60ae423ad15b613c0000000000000000000000000000010000000000ea30550040cbdaa86c52d5010000000000855c3400000000a8ed3232310000000000855c340000000080ab26a700000000000000000100000000010000000000ea305500000000a8ed32320100000000", - "transaction": { - "expiration": "2018-07-06T12:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio.wrap", - "name": "exec", - "authorization": [{ - "actor": "blkproducera", - "permission": "active" - },{ - "actor": "eosio.wrap", - "permission": "active" - } - ], - "data": { - "executer": "blkproducera", - "trx": { - "expiration": "1970-01-01T00:00:00", - "ref_block_num": 0, - "ref_block_prefix": 0, - "max_net_usage_words": 0, - "max_cpu_usage_ms": 0, - "delay_sec": 0, - "context_free_actions": [], - "actions": [{ - "account": "eosio", - "name": "updateauth", - "authorization": [{ - "actor": "alice", - "permission": "active" - } - ], - "data": "0000000000855c340000000080ab26a700000000000000000100000000010000000000ea305500000000a8ed3232010000" - } - ], - "transaction_extensions": [] - } - }, - "hex_data": "60ae423ad15b613c0000000000000000000000000000010000000000ea30550040cbdaa86c52d5010000000000855c3400000000a8ed3232310000000000855c340000000080ab26a700000000000000000100000000010000000000ea305500000000a8ed323201000000" - } - ], - "transaction_extensions": [] - } -} -``` - -The approvers should go through the human-readable transaction output and make sure everything looks fine. However, due to a current limitation of nodeos/cleos, the JSONification of action payload data does not occur recursively. So while both the `hex_data` and the human-readable JSON `data` of the payload of the `eosio.wrap::exec` action is available in the output of the `cleos multisig review` command, only the hex data is available of the payload of the inner `eosio::updateauth` action. So it is not clear what the `updateauth` will actually do. - -Furthermore, even if this usability issue was fixed in nodeos/cleos, there will still be cases where there is no sensible human-readable version of an action data payload within a transaction. An example of this is the proposed transaction in sub-section 2.2.3 which used the `eosio::setcode` action to set the contract code of the `eosio.wrap` account. The best thing to do in such situations is for the reviewer to compare the proposed transaction to one generated by them through a process they trust. - -Since each block producer generated a transaction in sub-section 3.1.1 (stored in the file wrap_update_alice_owner_trx.json) which should be identical to the transaction proposed by the lead block producer, they can each simply check to see if the two transactions are identical: -```sh -cleos multisig propose_trx -j -s -d updatealice '[]' wrap_update_alice_owner_trx.json blkproducera | grep '"data":' | sed 's/^[ \t]*"data":[ \t]*//;s/[",]//g' | cut -c 35- > expected_wrap_update_alice_owner_trx_serialized.hex -cat expected_wrap_update_alice_owner_trx_serialized.hex -``` -```console -c0593f5b000000000000000000000100004d1a03ea305500000000008054570260ae423ad15b613c00000000a8ed323200004d1a03ea305500000000a8ed32326b60ae423ad15b613c0000000000000000000000000000010000000000ea30550040cbdaa86c52d5010000000000855c3400000000a8ed3232310000000000855c340000000080ab26a700000000000000000100000000010000000000ea305500000000a8ed32320100000000 -``` -```sh -cat wrap_update_alice_owner_trx_to_review.json | grep '"packed_transaction":' | sed 's/^[ \t]*"packed_transaction":[ \t]*//;s/[",]//g' > proposed_wrap_update_alice_owner_trx_serialized.hex -cat proposed_wrap_update_alice_owner_trx_serialized.hex -``` -```console -c0593f5b000000000000000000000100004d1a03ea305500000000008054570260ae423ad15b613c00000000a8ed323200004d1a03ea305500000000a8ed32326b60ae423ad15b613c0000000000000000000000000000010000000000ea30550040cbdaa86c52d5010000000000855c3400000000a8ed3232310000000000855c340000000080ab26a700000000000000000100000000010000000000ea305500000000a8ed32320100000000 -``` -```sh -diff expected_wrap_update_alice_owner_trx_serialized.hex proposed_wrap_update_alice_owner_trx_serialized.hex -``` - -When an approver (e.g. `blkproducerb`) is satisfied with the proposed transaction, they can simply approve it: -```sh -cleos multisig approve blkproducera updatealice '{"actor": "blkproducerb", "permission": "active"}' -p blkproducerb -``` -```console -executed transaction: 2bddc7747e0660ba26babf95035225895b134bfb2ede32ba0a2bb6091c7dab56 128 bytes 543 us -# eosio.msig <= eosio.msig::approve {"proposer":"blkproducera","proposal_name":"updatealice","level":{"actor":"blkproducerb","permission... -warning: transaction executed locally, but may not be confirmed by the network yet -``` - -### 2.1.4 Execute the transaction to change the owner permission of an account - -When the necessary approvals are collected (in this example, with 21 block producers, at least 15 of their approvals were required), anyone can push the `eosio.msig::exec` action which executes the approved transaction. It makes a lot of sense for the lead block producer who proposed the transaction to also execute it (this will incur another temporary RAM cost for the deferred transaction that is generated by the eosio.msig contract). - -```sh -cleos multisig exec blkproducera updatealice blkproducera -``` -```console -executed transaction: 7127a66ae307fbef6415bf60c3e91a88b79bcb46030da983c683deb2a1a8e0d0 160 bytes 820 us -# eosio.msig <= eosio.msig::exec {"proposer":"blkproducera","proposal_name":"updatealice","executer":"blkproducera"} -warning: transaction executed locally, but may not be confirmed by the network yet -``` - -Anyone can now verify that the owner authority of `alice` was successfully changed: -```sh -cleos get account alice -``` -```console -permissions: - owner 1: 1 eosio@active, - active 1: 1 EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV -memory: - quota: 49.74 KiB used: 3.348 KiB - -net bandwidth: - staked: 1.0000 SYS (total stake delegated from account to self) - delegated: 0.0000 SYS (total staked delegated to account from others) - used: 0 bytes - available: 2.304 MiB - limit: 2.304 MiB - -cpu bandwidth: - staked: 1.0000 SYS (total stake delegated from account to self) - delegated: 0.0000 SYS (total staked delegated to account from others) - used: 413 us - available: 460.4 ms - limit: 460.8 ms - -producers: - -``` \ No newline at end of file diff --git a/docs/04_guides/08_configure-use-powerup-resource-model.md b/docs/04_guides/08_configure-use-powerup-resource-model.md deleted file mode 100644 index 35a6c933..00000000 --- a/docs/04_guides/08_configure-use-powerup-resource-model.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -content_title: How to configure PowerUp resource model -link_text: How to configure PowerUp resource model ---- -# Configure and Use the PowerUp Resource Model - -## Overview -This new system will create a new optional NET and CPU marketplace which displaces (over time) -the existing staking system and REX market. Under the old model, system token holders -own NET and CPU and may choose to use it themselves, delegate it to others, or make -it available for others to rent using the REX market. Under this new model, the chain -owns almost all NET and CPU resources and the only way to access these resources is -through the new `powerup` action. It channels fees to the REX pool to enable token holders -to profit off the new market. - -## Configuration - -### Definitions - -#### Configuration -```c++ -// configure the `powerup` market. The market becomes available the first time this action is invoked -void cfgpowerup( powerup_config& args ); - -struct powerup_config_resource { - std::optional current_weight_ratio; // Immediately set weight_ratio to this amount. 1x = 10^15. 0.01x = 10^13. - // Do not specify to preserve the existing setting or use the default; - // this avoids sudden price jumps. For new chains which don't need - // to gradually phase out staking and REX, 0.01x (10^13) is a good - // value for both current_weight_ratio and target_weight_ratio. - std::optional target_weight_ratio; // Linearly shrink weight_ratio to this amount. 1x = 10^15. 0.01x = 10^13. - // Do not specify to preserve the existing setting or use the default. - std::optional assumed_stake_weight; // Assumed stake weight for ratio calculations. Use the sum of total - // staked and total rented by REX at the time the power market - // is first activated. Do not specify to preserve the existing - // setting (no default exists); this avoids sudden price jumps. - // For new chains which don't need to phase out staking and REX, - // 10^12 is probably a good value. - std::optional target_timestamp; // Stop automatic weight_ratio shrinkage at this time. Once this - // time hits, weight_ratio will be target_weight_ratio. Ignored - // if current_weight_ratio == target_weight_ratio. Do not specify - // this to preserve the existing setting (no default exists). - std::optional exponent; // Exponent of resource price curve. Must be >= 1. Do not specify - // to preserve the existing setting or use the default. - std::optional decay_secs; // Number of seconds for the gap between adjusted resource - // utilization and instantaneous resource utilization to shrink - // by 63%. Do not specify to preserve the existing setting or - // use the default. - std::optional min_price; // Fee needed to reserve the entire resource market weight at the - // minimum price. For example, this could be set to 0.005% of - // total token supply. Do not specify to preserve the existing - // setting or use the default. - std::optional max_price; // Fee needed to reserve the entire resource market weight at the - // maximum price. For example, this could be set to 10% of total - // token supply. Do not specify to preserve the existing - // setting (no default exists). - - }; - -struct powerup_config { - powerup_config_resource net; // NET market configuration - powerup_config_resource cpu; // CPU market configuration - std::optional powerup_days; // `powerup` `days` argument must match this. Do not specify to preserve the - // existing setting or use the default. - std::optional min_powerup_fee; // Powerup fees below this amount are rejected. Do not specify to preserve the - // existing setting (no default exists). -}; -``` -#### State - -Definitions useful to help understand the configuration, including defaults: -```c++ -inline constexpr int64_t powerup_frac = 1'000'000'000'000'000ll; // 1.0 = 10^15 - -struct powerup_state_resource { - static constexpr double default_exponent = 2.0; // Exponent of 2.0 means that the price to reserve a - // tiny amount of resources increases linearly - // with utilization. - static constexpr uint32_t default_decay_secs = 1 * seconds_per_day; // 1 day; if 100% of bandwidth resources are in a - // single loan, then, assuming no further powerup usage, - // 1 day after it expires the adjusted utilization - // will be at approximately 37% and after 3 days - // the adjusted utilization will be less than 5%. - - uint8_t version = 0; - int64_t weight = 0; // resource market weight. calculated; varies over time. - // 1 represents the same amount of resources as 1 - // satoshi of SYS staked. - int64_t weight_ratio = 0; // resource market weight ratio: - // assumed_stake_weight / (assumed_stake_weight + weight). - // calculated; varies over time. 1x = 10^15. 0.01x = 10^13. - int64_t assumed_stake_weight = 0; // Assumed stake weight for ratio calculations. - int64_t initial_weight_ratio = powerup_frac; // Initial weight_ratio used for linear shrinkage. - int64_t target_weight_ratio = powerup_frac / 100; // Linearly shrink the weight_ratio to this amount. - time_point_sec initial_timestamp = {}; // When weight_ratio shrinkage started - time_point_sec target_timestamp = {}; // Stop automatic weight_ratio shrinkage at this time. Once this - // time hits, weight_ratio will be target_weight_ratio. - double exponent = default_exponent; // Exponent of resource price curve. - uint32_t decay_secs = default_decay_secs; // Number of seconds for the gap between adjusted resource - // utilization and instantaneous utilization to shrink by 63%. - asset min_price = {}; // Fee needed to reserve the entire resource market weight at - // the minimum price (defaults to 0). - asset max_price = {}; // Fee needed to reserve the entire resource market weight at - // the maximum price. - int64_t utilization = 0; // Instantaneous resource utilization. This is the current - // amount sold. utilization <= weight. - int64_t adjusted_utilization = 0; // Adjusted resource utilization. This is >= utilization and - // <= weight. It grows instantly but decays exponentially. - time_point_sec utilization_timestamp = {}; // When adjusted_utilization was last updated -}; - -struct powerup_state { - static constexpr uint32_t default_powerup_days = 30; // 30 day resource powerups - - uint8_t version = 0; - powerup_state_resource net = {}; // NET market state - powerup_state_resource cpu = {}; // CPU market state - uint32_t powerup_days = default_powerup_days; // `powerup` `days` argument must match this. - asset min_powerup_fee = {}; // fees below this amount are rejected - - uint64_t primary_key()const { return 0; } -}; -``` - -### Preparation for Upgrade -1. Build [eosio.contracts](https://github.com/EOSIO/eosio.contracts) with `powerup` code. Version **1.9.x** or greater . -2. Deploy eosio.system contract to `eosio`. -3. Create account `eosio.reserv` and ensure the account has enough RAM, at least 4 KiB. -4. Deploy `powup.results.abi` to `eosio.reserv` account using `setabi`. The ABI can be found in the `build/contracts/eosio.system/.powerup/` directory. -5. Enable the REX system (if not enabled). - -### Configuring PowerUp - -#### Config file -```json -# config.json -{ - "net": { - "assumed_stake_weight": 944076307, - "current_weight_ratio": 1000000000000000, - "decay_secs": 86400, - "exponent": 2, - "max_price": "10000000.0000 TST", - "min_price": "0.0000 TST", - "target_timestamp": "2022-01-01T00:00:00.000", - "target_weight_ratio": 10000000000000 - }, - "cpu": { - "assumed_stake_weight": 3776305228, - "current_weight_ratio": 1000000000000000, - "decay_secs": 86400, - "exponent": 2, - "max_price": "10000000.0000 TST", - "min_price": "0.0000 TST", - "target_timestamp": "2022-01-01T00:00:00.000", - "target_weight_ratio": 10000000000000 - }, - "min_powerup_fee": "0.0001 TST", - "powerup_days": 1 -} -``` - -#### cfgpowerup Action Call -```sh -# call to `cfgpowerup` -cleos push action eosio cfgpowerup "[`cat ./config.json`]" -p eosio -``` - -#### Check state -```sh -cleos get table eosio 0 powup.state -``` -```json -{ - "rows": [{ - "version": 0, - "net": { - "version": 0, - "weight": 0, - "weight_ratio": "1000000000000000", - "assumed_stake_weight": 944076307, - "initial_weight_ratio": "1000000000000000", - "target_weight_ratio": "10000000000000", - "initial_timestamp": "2020-11-16T19:52:50", - "target_timestamp": "2022-01-01T00:00:00", - "exponent": "2.00000000000000000", - "decay_secs": 3600, - "min_price": "0.0000 TST", - "max_price": "10000000.0000 TST", - "utilization": 0, - "adjusted_utilization": 0, - "utilization_timestamp": "2020-11-16T19:52:50" - }, - "cpu": { - "version": 0, - "weight": 0, - "weight_ratio": "1000000000000000", - "assumed_stake_weight": 3776305228, - "initial_weight_ratio": "1000000000000000", - "target_weight_ratio": "10000000000000", - "initial_timestamp": "2020-11-16T19:52:50", - "target_timestamp": "2022-01-01T00:00:00", - "exponent": "2.00000000000000000", - "decay_secs": 3600, - "min_price": "0.0000 TST", - "max_price": "10000000.0000 TST", - "utilization": 0, - "adjusted_utilization": 0, - "utilization_timestamp": "2020-11-16T19:52:50" - }, - "powerup_days": 1, - "min_powerup_fee": "0.0001 TST" - } - ], - "more": false, - "next_key": "" -} -``` - -### Using PowerUp - -#### Executing an order -The action to power up an account is `powerup`. It takes a `payer` of the fee and a `receiver` of the resources. The `days` must always match `state.powerup_days`. `net_frac` and `cpu_frac` are the percentage of the resources that you need. The easiest way to caclulate the percentage is to multiple 10^15 (100%) by the desired percentage. For example: 10^15 * 0.01 = 10^13. -```sh -cleos push action eosio powerup '[user, user, 1, 10000000000000, 10000000000000, "1000.0000 TST"]' -p user -``` -``` -executed transaction: 82b7124601612b371b812e3bf65cf63bb44616802d3cd33a2c0422b58399f54f 144 bytes 521 us -# eosio <= eosio::powerup {"payer":"user","receiver":"user","days":1,"net_frac":"10000000000000","cpu_frac":"10000000000000","... -# eosio.token <= eosio.token::transfer {"from":"user","to":"eosio.rex","quantity":"999.9901 TST","memo":"transfer from user to eosio.rex"} -# eosio.reserv <= eosio.reserv::powupresult {"fee":"999.9901 TST","powup_net_weight":"16354","powup_cpu_weight":"65416"} -# user <= eosio.token::transfer {"from":"user","to":"eosio.rex","quantity":"999.9901 TST","memo":"transfer from user to eosio.rex"} -# eosio.rex <= eosio.token::transfer {"from":"user","to":"eosio.rex","quantity":"999.9901 TST","memo":"transfer from user to eosio.rex"} -``` -You can see how much NET and CPU weight was received as well as the fee by looking at the `eosio.reserv::powupresult` informational action. - -*It is worth mentioning that the network being used for the example has not fully transitioned so the available resources are minimal therefore 1% of the resources are quite expensive. As the system continues the transition more resources are available to the `PowerUp` resource model and will become more affordable.* - -#### Processing Expired Orders -The resources in loans that expire do not automatically get reclaimed by the system. The expired loans sit in a queue that must be processed. Anyone calling the `powerup` action will help with processing this queue (limited to processing at most two expired loans at a time) so that normally the expired loans will be automatically processed in a timely manner. However, in some cases it may be necessary to manual process expired loans in the queue to make resources available to the system again and thus make prices cheaper. In such a scenario, any account may process up to an arbitrary number of expired loans by calling the `powerupexec` action. - -The orders table `powup.order` can be viewed by calling: -```sh -cleos get table eosio 0 powup.order -``` -```json -{ - "rows": [{ - "version": 0, - "id": 0, - "owner": "user", - "net_weight": 16354, - "cpu_weight": 65416, - "expires": "2020-11-18T13:04:33" - } - ], - "more": false, - "next_key": "" -} -``` - -Example `powerupexec` call: - -```sh -cleos push action eosio powerupexec '[user, 2]' -p user -``` -```console -executed transaction: 93ab4ac900a7902e4e59e5e925e8b54622715328965150db10774aa09855dc98 104 bytes 363 us -# eosio <= eosio::powerupexec {"user":"user","max":2} -warning: transaction executed locally, but may not be confirmed by the network yet ] -``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 37759d12..3e00234e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,27 +1,14 @@ --- -content_title: About System Contracts +content_title: About the Token Contract --- The EOSIO blockchain platform is unique in that the features and characteristics of the blockchain built on it are flexible, that is, they can be changed, or modified completely to suit each business case requirement. Core blockchain features such as consensus, fee schedules, account creation and modification, token economics, block producer registration, voting, multi-sig, etc., are implemented inside smart contracts which are deployed on the blockchain built on the EOSIO platform. -## System contracts defined in eosio.contracts +## Contracts defined in eosio.token Block.one implements and maintains EOSIO open source platform which contains, as an example, the system contracts encapsulating the base functionality for an EOSIO based blockchain. -1. [eosio.bios](action-reference/eosio.bios) -2. [eosio.system](action-reference/eosio.system) -3. [eosio.msig](action-reference/eosio.msig) -4. [eosio.token](action-reference/eosio.token) -5. [eosio.wrap](action-reference/eosio.wrap) - -## Key Concepts Implemented by eosio.system - -1. [System](01_key-concepts/01_system.md) -2. [RAM](01_key-concepts/02_ram.md) -3. [CPU](01_key-concepts/03_cpu.md) -4. [NET](01_key-concepts/04_net.md) -5. [Stake](01_key-concepts/05_stake.md) -6. [Vote](01_key-concepts/06_vote.md) +1. [eosio.token](action-reference/eosio.token) ## Build and deploy -To build and deploy the system contract follow the instruction from [Build and deploy](03_build-and-deploy.md) section. \ No newline at end of file +To build and deploy the system contract follow the instruction from [Build and deploy](01_build-and-deploy.md) section. diff --git a/pipeline.jsonc b/pipeline.jsonc index 9cbda157..712ecae9 100644 --- a/pipeline.jsonc +++ b/pipeline.jsonc @@ -4,7 +4,11 @@ "pipeline-branch": "master", "dependencies": // dependencies to pull for a build of contracts, by branch, tag, or commit hash { +<<<<<<< HEAD "eosio": "v2.1.0-rc3", +======= + "eosio": "develop", +>>>>>>> develop "eosio.cdt": "v1.8.0-rc1" } } diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 2048afff..ab59c20e 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -1,9 +1,15 @@ cmake_minimum_required( VERSION 3.5 ) -set(EOSIO_VERSION_MIN "2.0") -set(EOSIO_VERSION_SOFT_MAX "2.0") +project(contract_tests) +if(${BUILD_TESTS_PINNED}) + include(${EOSIO_DIR_PROMPT}/pinned_toolchain.cmake) +endif() + +set(EOSIO_VERSION_MIN "2.1") +set(EOSIO_VERSION_SOFT_MAX "2.1") #set(EOSIO_VERSION_HARD_MAX "") + find_package(eosio) ### Check the version of eosio @@ -31,6 +37,7 @@ enable_testing() file(GLOB UNIT_TESTS "*.cpp" "*.hpp") # find all unit test suites add_eosio_test_executable(unit_test ${UNIT_TESTS}) # build unit tests as one executable # mark test suites for execution + foreach(TEST_SUITE ${UNIT_TESTS}) # create an independent target for each test suite execute_process(COMMAND bash -c "grep -E 'BOOST_AUTO_TEST_SUITE\\s*[(]' ${TEST_SUITE} | grep -vE '//.*BOOST_AUTO_TEST_SUITE\\s*[(]' | cut -d ')' -f 1 | cut -d '(' -f 2" OUTPUT_VARIABLE SUITE_NAME OUTPUT_STRIP_TRAILING_WHITESPACE) # get the test suite name from the *.cpp file if (NOT "" STREQUAL "${SUITE_NAME}") # ignore empty lines diff --git a/tests/contracts.hpp.in b/tests/contracts.hpp.in index ad6e090d..bbbdc72a 100644 --- a/tests/contracts.hpp.in +++ b/tests/contracts.hpp.in @@ -4,26 +4,8 @@ namespace eosio { namespace testing { struct contracts { - static std::vector system_wasm() { return read_wasm("${CMAKE_BINARY_DIR}/../contracts/eosio.system/eosio.system.wasm"); } - static std::vector system_abi() { return read_abi("${CMAKE_BINARY_DIR}/../contracts/eosio.system/eosio.system.abi"); } static std::vector token_wasm() { return read_wasm("${CMAKE_BINARY_DIR}/../contracts/eosio.token/eosio.token.wasm"); } static std::vector token_abi() { return read_abi("${CMAKE_BINARY_DIR}/../contracts/eosio.token/eosio.token.abi"); } - static std::vector msig_wasm() { return read_wasm("${CMAKE_BINARY_DIR}/../contracts/eosio.msig/eosio.msig.wasm"); } - static std::vector msig_abi() { return read_abi("${CMAKE_BINARY_DIR}/../contracts/eosio.msig/eosio.msig.abi"); } - static std::vector wrap_wasm() { return read_wasm("${CMAKE_BINARY_DIR}/../contracts/eosio.wrap/eosio.wrap.wasm"); } - static std::vector wrap_abi() { return read_abi("${CMAKE_BINARY_DIR}/../contracts/eosio.wrap/eosio.wrap.abi"); } - static std::vector bios_wasm() { return read_wasm("${CMAKE_BINARY_DIR}/../contracts/eosio.bios/eosio.bios.wasm"); } - static std::vector bios_abi() { return read_abi("${CMAKE_BINARY_DIR}/../contracts/eosio.bios/eosio.bios.abi"); } - - struct util { - static std::vector reject_all_wasm() { return read_wasm("${CMAKE_SOURCE_DIR}/test_contracts/reject_all.wasm"); } - static std::vector exchange_wasm() { return read_wasm("${CMAKE_SOURCE_DIR}/test_contracts/exchange.wasm"); } - static std::vector system_wasm_v1_8() { return read_wasm("${CMAKE_SOURCE_DIR}/test_contracts/old_versions/v1.8.3/eosio.system/eosio.system.wasm"); } - static std::vector system_abi_v1_8() { return read_abi("${CMAKE_SOURCE_DIR}/test_contracts/old_versions/v1.8.3/eosio.system/eosio.system.abi"); } - static std::vector system_wasm_old() { return read_wasm("${CMAKE_SOURCE_DIR}/test_contracts/old_versions/v1.2.1/eosio.system/eosio.system.wasm"); } - static std::vector system_abi_old() { return read_abi("${CMAKE_SOURCE_DIR}/test_contracts/old_versions/v1.2.1/eosio.system/eosio.system.abi"); } - static std::vector msig_wasm_old() { return read_wasm("${CMAKE_SOURCE_DIR}/test_contracts/old_versions/v1.2.1/eosio.msig/eosio.msig.wasm"); } - static std::vector msig_abi_old() { return read_abi("${CMAKE_SOURCE_DIR}/test_contracts/old_versions/v1.2.1/eosio.msig/eosio.msig.abi"); } - }; + }; }} //ns eosio::testing diff --git a/tests/main.cpp b/tests/main.cpp index f1f23ace..ce4b97d4 100644 --- a/tests/main.cpp +++ b/tests/main.cpp @@ -10,6 +10,11 @@ #include #include +<<<<<<< HEAD +======= +// #include "eosio.system_tester.hpp" + +>>>>>>> develop // using namespace eosio_system; #define BOOST_TEST_STATIC_LINK From ef6cb64d37f4d5351fbc23423eb263726f1dd57c Mon Sep 17 00:00:00 2001 From: deck Date: Wed, 10 Mar 2021 08:48:37 -0500 Subject: [PATCH 2/4] fix conflicts --- README.md | 9 +-------- docs.json | 4 ---- pipeline.jsonc | 4 ---- tests/main.cpp | 5 ----- 4 files changed, 1 insertion(+), 21 deletions(-) diff --git a/README.md b/README.md index c35e36bf..e0966faf 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,8 @@ # eosio.token -<<<<<<< HEAD -## Version : 1.9.2 +## Version : 2.0.0-rc1 The design of the EOSIO blockchain calls for a number of smart contracts that are run at a privileged permission level in order to support functions such as block producer registration and voting, token staking for CPU and network bandwidth, RAM purchasing, multi-sig, etc. These smart contracts are referred to as the bios, boot, system, msig, wrap (formerly known as sudo) and token contracts. -======= -## Version : 2.0.0-develop - -The design of the EOSIO blockchain calls for a number of smart contracts that are run at a privileged permission level in order to support functions such as block producer registration and voting, token staking for CPU and network bandwidth, RAM purchasing, multi-sig, etc. These smart contracts are referred to as the bios, boot, system, msig, wrap (formerly known as sudo) and token contracts. - ->>>>>>> develop This repository contains a reference token example contracts that are useful when deploying a token using an EOSIO blockchain. It is provided for reference purposes: The following unprivileged contract(s) are in this repository. diff --git a/docs.json b/docs.json index 026d4d3f..625bedcf 100644 --- a/docs.json +++ b/docs.json @@ -11,11 +11,7 @@ "name": "mdjavadoc", "options": { "source_dirs": [ -<<<<<<< HEAD "contracts/eosio.token/include/eosio.token/" -======= - "contracts/eosio.token/include/eosio.token/", ->>>>>>> develop ], "output_dir": "action-reference" } diff --git a/pipeline.jsonc b/pipeline.jsonc index 712ecae9..9cbda157 100644 --- a/pipeline.jsonc +++ b/pipeline.jsonc @@ -4,11 +4,7 @@ "pipeline-branch": "master", "dependencies": // dependencies to pull for a build of contracts, by branch, tag, or commit hash { -<<<<<<< HEAD "eosio": "v2.1.0-rc3", -======= - "eosio": "develop", ->>>>>>> develop "eosio.cdt": "v1.8.0-rc1" } } diff --git a/tests/main.cpp b/tests/main.cpp index ce4b97d4..f1f23ace 100644 --- a/tests/main.cpp +++ b/tests/main.cpp @@ -10,11 +10,6 @@ #include #include -<<<<<<< HEAD -======= -// #include "eosio.system_tester.hpp" - ->>>>>>> develop // using namespace eosio_system; #define BOOST_TEST_STATIC_LINK From 20b0d2ea21c9ba966288a15ac6f5ae04cceefb96 Mon Sep 17 00:00:00 2001 From: deck Date: Wed, 10 Mar 2021 08:52:18 -0500 Subject: [PATCH 3/4] remove references to the build.sh --- docs/01_build-and-deploy.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/01_build-and-deploy.md b/docs/01_build-and-deploy.md index c789bf9b..35630a19 100644 --- a/docs/01_build-and-deploy.md +++ b/docs/01_build-and-deploy.md @@ -10,15 +10,6 @@ Ensure an appropriate version of `eosio.cdt` is installed. Installing `eosio.cdt eosio-cpp -v ``` -### Build contracts using the build script - -#### To build contracts alone -Run the `build.sh` script in the top directory to build all the contracts. - -#### To build the contract and unit tests -1. Ensure an appropriate version of `eosio` has been built from source and installed. Installing `eosio` from binaries `is not` sufficient. You can find instructions on how to do it in section [Building from Sources](https://developers.eos.io/manuals/eos/latest/install/build-from-source). -2. Run the `build.sh` script in the top directory with the `-t` flag to build all the contracts and the unit tests for these contracts. - ### Build contracts manually To build the `eosio.token` execute the following commands. @@ -45,6 +36,17 @@ make -j$(sysctl -n hw.ncpu) cd .. ``` +#### To build the contract and unit tests +1. Ensure an appropriate version of `eosio` has been built from source and installed. Installing `eosio` from binaries `is not` sufficient. You can find instructions on how to do it in section [Building from Sources](https://developers.eos.io/manuals/eos/latest/install/build-from-source). +2. Run the below command to build all the contracts and the unit tests for these contracts. +``` +rm -fr build +mkdir build +cd build +cmake -DBUILD_TESTS=true .. +make +``` + ### After build: * If the build was configured to also build unit tests, the unit tests executable is placed in the _build/tests_ folder and is named __unit_test__. * The contracts (both `.wasm` and `.abi` files) are built into their corresponding _build/contracts/\_ folder. From ebf148d0c73ba9930a542b9b06bbb503ebfb48cd Mon Sep 17 00:00:00 2001 From: deck Date: Wed, 10 Mar 2021 09:33:51 -0500 Subject: [PATCH 4/4] fix build link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e0966faf..1a59f5ea 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Dependencies: ## Build -To build the contracts follow the instructions in [Build and deploy](https://developers.eos.io/manuals/eosio.token/latest/build-and-deploy) section. +To build the contracts follow the instructions in [Build and deploy](./docs/01_build-and-deploy.md) section. ## Contributing