Skip to content

Contracts v3.1.0-rc1 Release Notes

Pre-release
Pre-release
Compare
Choose a tag to compare
@arhag arhag released this 08 Jul 00:14
· 140 commits to main since this release
v3.1.0-rc1
02fe258
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

This is a RELEASE CANDIDATE for version 3.1.0. The latest STABLE release is v1.9.2.

Release 3.1.0-rc1 includes several changes to the core contract. It also introduces the boot contract. Other contracts remain unchanged in behavior since the last stable release.

Read on for details.

New features

Boot contract

The boot contract [20] is a new contract introduced in this release that serves the purpose of bootstrapping a new blockchain, especially for testing purposes.

The core contract in its current state now depends on several host functions that are only made available on the blockchain after activation of certain protocol features. Without activation of the protocol features that make available the necessary host functions, it is not possible to deploy a contract that requires those host functions. However, activation of nearly all protocol features (with the exception of PREACTIVATE_FEATURE) require a privileged call to the preactivate_feature host function which is made accessible to users through the activate action within the core contract.

To break this Catch-22, the boot contract includes a similar activate action (which creates a dependency on the PREACTIVATE_FEATURE protocol feature), but it does not include any other features that would introduce dependencies on further protocol features. Therefore, it should always be possible to activate the PREACTIVATE_FEATURE protocol feature on a fresh EOSIO blockchain, deploy the boot contract to the privileged eosio account, and then use its activate action to activate additional protocol features that are needed for the deployment of the core contract.

Core contract

The core contract refers to the contract meant to be deployed to the privileged eosio account which provides many of the functions that users have come to expect from popular EOSIO blockchains, such as delegate proof of stake (DPoS), PowerUp, and more.

This release adds new functionality to the core contract.

Optionally restrict permission changes [1]

The new action limitauthchg allows an account to opt into or out of restrictions on permission changes to their account through authorization additional constraints on the actions updateauth, deleteauth, linkauth, and unlinkauth. Each of those four auth-related actions now have a new binary extension argument: authorized_by (which is the name of a permission on the account). This may be either absent or empty for accounts which have not opted into limitauthchg.

An account may opt into the new restrictions by calling limitauthchg with a non-empty allow_perms or a non-empty disallow_perms (both cannot be non-empty). They may opt out again by calling limitauthchg with both an empty allow_perms and an empty disallow_perms.

If allow_perms is non-empty for an account, then the authorized_by permission name of an auth-related action involving that account must be contained in the allow_perms list; otherwise the transaction will abort. If disallow_perms is non-empty for an account, then the authorized_by permission name of an auth-related action involving that account must not be contained in the disallow_perms list; otherwise the transaction will abort. In either case, the core contract verifies that the specific permission of the account named by authorized_by is the one that authorizes the auth-related action.

Among its several uses, the limitauthchg action enables protection against one of the denial of service attack vectors of a particular contract pays solution in which a private key with restricted access to the CPU/NET resources paid for by an application is publicly distributed with the application code.

Configure WASM limits [9]

Assuming CONFIGURABLE_WASM_LIMITS2=ON (which it is by default), the core contract will now include a new wasmcfg action which supports (and depends on) the CONFIGURABLE_WASM_LIMITS2 protocol feature.

This action allows increasing some of the limits enforced on WASM contracts by calling the action with wasmcfg("high"). The WASM limits can be restored back to the original values by calling the action with wasmcfg("low") or wasmcfg("default").

⚠️ Warning: Some of the limits are enforced at the time of deployment, so beware that users may have deployed contracts surpassing the low limits during the window of time that the high limits were enforced. In addition, some of the limits are enforced at run-time, so bringing the configuration back down from high to low may break the contracts that were deployed and tested while the configuration was at high.

Tracked recent block information [19]

The core contract has been updated to keep track within a blockinfo table the block height and timestamp of recent blocks in the blockchain's history. There is a rolling window tracking a maximum number of recent blocks (that max is currently hard-coded to 10), and the core contract will automatically garbage collect table entries for blocks that fall outside of that window.

The blockinfo table schema is a publicly specified interface and is versioned, so contracts are able to look into it to get information about recent blocks. The block_info.hpp header file is provided which can be included into other contracts to allow them to access information in the blockinfo table including via the convenient get_latest_block_batch_info function. The get_latest_block_batch_info can be used as an alternative means to get the current block height (under the assumption that the onblock has not failed) which can be useful in blockchains that have not activated the GET_BLOCK_NUM protocol feature.

Other changes

Core contract

The core contract also includes additional changes and bug fixes.

Memo field added to setcode and setabi [2]

This additional field can help contract authors track deployed contract versions.

Enhanced setparams [9]

Assuming SYSTEM_BLOCKCHAIN_PARAMETERS=ON (which it is by default), the setparams action is modified to take an augmented structure of parameters which now includes max_action_return_value_size (related to the ACTION_RETURN_VALUE protocol feature). The implementation of the action is also modified to use the new and more flexible set_parameters_packed host function, which is only available if the BLOCKCHAIN_PARAMETERS protocol feature has been activated.

REX rounding bug [4]

This release includes a backport of EOSIO/eosio.system#54 (originally authored by @deckb) which works around the REX rounding bug that stopped accounts from selling REX.

Accounts may now use the voteupdate action to restore their account.

In addition, the bug has been fixed so it does not impact more accounts in the future.

Voting and vesting patches for b1 account [6]

The core contract change which was used by BPs on the EOS network to freeze vesting of core tokens to the b1 account has been reproduced in the core contract made available in this release.

Building, compatibility, and upgrading

Building

Instructions for building the system contracts are provided in the README.

This release depends on on CDT 3.0 at a minimum. A release candidate for CDT 3.0.0 is available.

Building the tests also requires EOSIO 3.1 at a minimum. A release candidate for EOSIO 3.1.0 is available. Building the tests is optional; see README for how to build with or without tests.

For now, the EOSIO dependency must be satisfied with a build of EOSIO 3.1 from source. Alternatively, look into DUNE for another way to build the contracts without needing to build CDT or EOSIO from source.

Compatibility

By default, the core contract adds additional requirements (beyond what existed in v1.9.2) that the blockchain has activated the following two protocol features: BLOCKCHAIN_PARAMETERS and CONFIGURABLE_WASM_LIMITS2.

The BLOCKCHAIN_PARAMETERS protocol feature dependency is required for the enhanced setparams action. You can choose to keep the old behavior of the setparams action (and avoid this dependency on the BLOCKCHAIN_PARAMETERS protocol feature) by passing -DSYSTEM_BLOCKCHAIN_PARAMETERS=OFF to cmake.

The CONFIGURABLE_WASM_LIMITS2 protocol feature dependency is required for the new wasmcfg action. You can avoid introducing the wasmcfg action (and avoid this dependency on the CONFIGURABLE_WASM_LIMITS2 protocol feature) by passing -DSYSTEM_CONFIGURABLE_WASM_LIMITS=OFF to cmake.

Upgrading

The core contract can be upgraded on an account with an already deployed v1.9.2 core contract by simply deploying the .wasm and .abi files to the account. No additional actions need to be taken to complete to upgrade.

However, the blockchain must have first activated the necessary protocol features which includes BLOCKCHAIN_PARAMETERS and CONFIGURABLE_WASM_LIMITS2.

Further details on changes since last release

Special thanks to the contributors that submitted patches for this release:

Full list of changes since last release

PRs

  • [5] cicd
  • [7] Cleanup of 2 readme files only different in case (to make OSX happy)
  • [1] Limit auth changes
  • [2] setcode and setabi memo
  • [10] clarify location
  • [9] Add configuration actions for new protocol features
  • [4] Backport rex workaround
  • [6] Reapply b1 patches
  • [13] Fix tests to be compatable with Mandel
  • [12] Bump version to v3.0.0-rc1
  • [17] Remove duplicated check
  • [18] Fix tests to use updated applied_transaction signal
  • [19] Add blockinfo feature to system contract
  • [20] Add Boot Contract
  • [21] Add error messages for get_balance & get_supply
  • [24] Update CDT dependency to CDT 3.0
  • [27] up max_call_depth to 1024
  • [26] [3.1] Update README; bump version to 3.1.0-rc1


Full Changelog: historical-v1.9.2-base...v3.1.0-rc1

Contributors

swatanabe, tbfleming, and 9 other contributors
Assets 2