Leap v3.1 Release Features & Additional Tools

The Leap v3.1 release blockchain software distills months of research and development into a network upgrade that is full of useful features and fixes. 

The Blue Papers outlined some of these features. The API+ Blue Paper recommended several improvements to mitigate lost transactions and improve the predictability of transaction lifecycles.

Previous articles explored how the subjective billing system can cause lost transactions and outlined existing fixes for common transaction lifecycle issues like lost transactions. The Leap v3.1 release introduces new tools to address these issues and other user experience hurdles. 

The Leap v3.1 release introduces the following new transaction lifecycle tools: 

• Transaction Retry
• Transaction Finality Status
• Transaction Resource Cost Estimation 
• Subjective Billing Improvements
• Transaction failure tracing with a new transaction endpoint 

Additional Leap upgrades that are not focused on transaction lifecycle include:

• Improved compatibility with the GELF appender logging protocol
• Upgraded crypto primitives and encryption libraries add EVM-related encryption features and improve the K1 curve key recovery performance by 33%. 
• New build procedures
• A new snapshot format
• Block and SHiP pruning feature
• Option to terminate a node at a particular block
• Mandel 3.0 features, including EOSIO 2.1 backports

Leap v3.1 removes: 

• The history plugin, which was deprecated in 1.2 
• MongoDB plugin
• Older Build scripts
• Reversible block database
• Support for macOS and alternate Linux distributions. The Leap v3.1 release only officially supports Ubuntu 18.04, 20.04, and 22.04. 
• It also deprecates the abi_bin_to_json and abi_json_to_bin conversion APIs.

Like EOSIO 1.8, the Leap v3.1 release requires a coordinated protocol activation. Nodes must update binaries and change configuration settings, and nodes running EOSIO 2.1 must take additional steps before block producers activate new protocol features. Operators need to complete these steps by the planned upgrade date of 21 September 2022. Any nodes that do not activate the Leap v3.1 release are unable to sync with the rest of the network after 21 September. 

You can find more detail about these upgrade steps in our upgrade guide.

New Leap v3.1 Release Features

Transaction Failure Tracing and New Transaction Endpoint

(Details)

The Leap v3.1 release introduces a new transaction endpoint that includes a detailed failure report with embedded transaction exceptions when a transaction fails. This detailed report is the transaction failure trace. Do not mistake this report for a successful transaction trace. You may want to verify the receipt and except fields to ensure transaction success.

Prior to the Leap v3.1 release, failed transactions resulted in a transaction failure trace without details of the failure. A Leap v3.1 transaction failure trace specifies where in a transaction the failure occurred and identifies which action produced the failure. The new Leap v3.1 transaction endpoint has this feature enabled by default.

Transaction Retry

(Details)

The transaction retry feature allows API nodes to resubmit lost transactions additional times until they appear in a block or expire. 

For background, when a user connects to an API node and sends a transaction to the network, there is no guarantee that the transaction will successfully make it into a block. 

Many issues, such as subjective billing or geographic latency, can prevent the propagation of a transaction across the network to the active block producer. One way to solve these issues is to allow API nodes to track transactions for inclusion in the blockchain and retry transactions that block producers did not publish in a block.

The transaction retry feature creates an incoming transaction pool and temporarily keeps transactions in the pool. After inclusion in a block, the transaction remains in the pool for a set number of blocks or until that block reaches irreversibility. 

Node operators individually set the transaction pool parameters and the criteria that define a missing transaction. If the tool detects a missing transaction based on those criteria, it will resubmit the transaction to the network. 

Transaction Finality Status

(Details)

The transaction finality status feature allows nodes to share the finality status of a given transaction. It also returns snapshots of the current chain state.

One of the most common functions developers implement in their smart contracts is to check a transaction’s finality status. With current tooling, each developer must build a custom solution. The need to build and rebuild transaction finality status increases development time and adds a vector for smart contract exploits and bugs. There is great value in allowing nodes to provide this transaction finality information directly.

The transaction finality status feature allows nodes to share snapshots of the current chain state. Nodes with this feature enabled can store transaction status and open a new endpoint to query that status. It returns a status of “UNKNOWN” if the transaction does not appear in the chain.

Transaction Resource Cost Estimation

(Details)

The transaction resource cost estimation feature lets nodes open a read-only endpoint that returns an estimate of resource costs. 

In Antelope chains, the active block producer determines the cost of a transaction at execution time. The block producer determines CPU cost by measuring the CPU time used to execute the non-signature portion of the transaction. The variance in block producer CPU performance makes it difficult to determine actual resource costs before sending a transaction.

The transaction resource cost estimation feature helps users and applications more accurately estimate the resource costs of a transaction. The resource cost estimation feature creates an API endpoint to receive an unsigned transaction. A node with the feature enabled returns an estimate of the transaction’s resource costs based on how long the API node takes to process the transaction. 

Subjective Billing Improvements

(Details)

The Leap v3.1 release’s subjective billing improvements consist of changes to two existing tools. The first change allows nodes to adjust the subjective billing decay time from its default of 24 hours. The second change allows adjustment of the three-strikes parameter in the three-strikes rule used by block producers.

Because Antelope chains only charge accounts when a block producer publishes a transaction to the blockchain, failed transactions are effectively free, sometimes leading to abuse. The three-strikes rule and the subjective billing tool reduce the failed transaction load on nodes, but introduce user experience hurdles. Leap introduces adjustable subjective billing and three-strikes parameters to mitigate these user experience hurdles. 

Account max failures: 

Before subjective billing, EOSIO 2.0.9 implemented the three-strikes rule for block producer nodes. The three-strikes feature drops the rest of an account’s queued transactions when the account has sent three failed transactions within a single block, reducing the burden of failed transactions.

The previously hard-coded limit of 3 is now configurable to any number of failures.

In addition, accounts that have been whitelisted with the disable-subjective-account-billing option no longer encounter the max transaction failure limit.

Subjective account decay:

Nodes prevent excessive failed transactions by using subjective billing to track an account’s failed transaction CPU budget for each node. The protocol returns this budget to an account over a period known as subjective account decay. This previously hard-coded decay of 24 hours is now configurable.

With the current 24-hour time window, for an account that hasn’t pushed a transaction in 6 hours, the node applies a multiplier of 6/24, or ¼, providing only 25% of the account’s otherwise available resources. 

When the time window is adjusted to 6 hours, the node applies a multiplier of 6/6, or 1, which gives the same account 100% of the available resources. 

When the window is set to one hour, tests find the one-hour window is effective at failed transaction spam mitigation without user experience issues.

Additional Features: 

Additional new features include cryptography-related improvements, new protocol options, pruning features, and logging improvements. Some features optimize EVM-related considerations, while network participants requested other features to improve the efficiencies of their workflows.

• Crypto Primitives
  (Details)
• Fetch Block Number
  (Details)
• Prune SHiP & Block Log
  (Details)
• Custom GELF Fields
  (Details)
• Terminate-at-Block Option
  (Details)

CRYPTO_PRIMITIVES is a feature that introduces seven new host functions. Host functions are faster than smart contracts because they are implemented in native code rather than in an abstracted smart contract layer. These functions enable more efficient computation of the cryptographic functions used in many Solidity and EVM-based contract libraries. The new feature includes:

• An algorithm that more efficiently performs modular exponentiation ( c=mod_m(b^x) ), a useful formula for hashing algorithms.

• Three functions on the alt_bn128 elliptic curve:
  • Point addition
  • Scalar multiplication
  • Bilinear functions 

These functions are used extensively in zero-knowledge proofs (e.g. zkSNARKs) and other privacy-preserving data verification methods.

• Two new hash functions:
  • sha3
  • blake2_f

• Upgrades to the libsecp256k library, improving k1 key recovery by 33%.

The Leap v3.1 release adds nodeos options to prune the block log and state history plugin. When nodeos prunes these files, it removes older data from local node storage to improve performance. 

It also introduces the option to terminate at a particular block, which is useful for chain state snapshots.

Additionally, it includes user-defined fields for transaction logs on a protocol called GELF. This protocol allows transaction logs to be shared using a common syntax that operators can easily integrate with other transaction log solutions.

GET_BLOCK_NUM is a protocol feature that introduces a host function that allows smart contracts to fetch the current block number directly. 

Updates from the Mandel v3.0 release

(Details)

The Mandel v3.0 release included several features from the EOSIO v2.1 release, in addition to new features and various changes to tests, logs, and formats. These features were largely added to bring Mandel features up to date with features from the EOSIO v2.1 release, while omitting those EOSIO v2.1 features that the network didn’t need. Protocol features added in the Mandel v3.0 release which are all still supported in the Leap v3.1 release include:

• GET_CODE_HASH
• ACTION_RETURN_VALUE (This was backported from EOSIO 2.1)
• CONFIGURABLE_WASM_LIMITS2
• BLOCKCHAIN_PARAMETERS (This was backported from EOSIO 2.1)

Installation

The Leap v3.1 release makes changes to the installation procedure of the core software. It also has several compatibility differences as compared to previously released updates.

The new build procedure uses a build process driven by CMake instead of custom shell scripts. Without these build scripts, a build from the source code requires the installation of necessary dependencies. The readme lists these dependencies and the recommended build procedure. 

The Leap v3.1 release is built for Ubuntu 20.04 and 22.04, with support for Ubuntu 18.04, although other distributions, compilers, and platforms may work.

Upgrading from Prior Releases

To upgrade a node using a snapshot: 

1. First, generate a state snapshot from a compatible earlier version of nodeos, such as the nodeos version from the EOSIO v2.0 release. 
2. Remove the node’s state file. 
3. If the node uses the EOSIO v2.1 release, operators also must remove the SHiP and block logs. Nodes running the EOSIO v2.0 release do not need to take this step.
4. Start nodeos with the snapshot. 
5. Start and stop nodeos as usual.

For more details or advice on more complex situations, refer to our Upgrade Guide or contact EOS Support for further recommendations.

Compatibility

(Details)

In general, the Leap v3.1 release is compatible with networks, snapshots, block logs, and state history plugin (SHiP) logs from the EOSIO v2.0 release, but NOT the EOSIO v2.1 release.

The Leap v3.1 release is NOT compatible with state files from earlier software versions.

Leap v3.1 release Deprecations & Removals

(Details)

The Leap v3.1 release deprecates the ABI conversion APIs and removes several deprecated features. 

ABI conversion APIs are deprecated.

The abi_bin_to_json and abi_json_to_bin conversion APIs turn serialized data into deserialized data or vice versa. They are both deprecated as of the Leap v3.1 release.

Several features are removed:

• Old Build Scripts

The Leap v3.1 release removes the build scripts that install nodeos, cleos, keosd, and their dependencies. The new CMAKE script installs only nodeos, cleos, and keosd, and operators must install dependencies first.

• History Plugin

The EOSIO v1.0 release included a history plugin, but EOSIO v1.2 deprecated this history plugin on August 14, 2018 in favour of more performant solutions. It will be removed in the Leap v3.1 release, and nodes using --plugin eosio::history_plugin should migrate to --plugin eosio::trace_api_plugin or --plugin eosio::state_history_plugin. 

• MongoDB Plugin

The EOSIO v1.8 release deprecated the MongoDB plugin, which allowed nodes to archive blockchain data into a MongoDB database. The Leap v3.1 release removes this plugin entirely. Node operators can use history tools like the state_history_plugin instead.

• Reversible Block Database

The Leap v3.1 release removes the reversible block database, and stores reversible blocks in the fork database instead. Operators should remove existing configuration settings for the reversible block database from the config.ini file and any scripts.

Dropped support for Ubuntu 16.04, Centos, and MacOS

The Leap v3.1 release drops support for MacOS, Ubuntu v16.04, and the CentOS Linux distribution to optimize developer resources. Supported platforms are now Ubuntu 18.04 (limited support), 20.04, and 22.04. For users on one of these unsupported operating systems, DUNE offers compatibility for any Docker-compatible OS.

Conclusion

The Leap v3.1 release includes powerful tools and options to improve the functionality and user experience on EOS and other EOSIO-based blockchains. As a protocol upgrade, it requires coordination between node operators as the anticipated activation date of 21 September 2022 approaches. After this date, block producers will have updated their software, and wallets and applications can begin incorporating features from the Leap v3.1 release. With the completion of this network upgrade, the EOS Network will make its first strides into self-sovereign network development, making the best technology in the blockchain business even better.

Detailed Release Notes

New Transaction Endpoint

The new chain_api_plugin endpoint feature incorporates transaction_retry as well as other parameters for future features. The endpoint is:

/v1/chain/send_transaction2 (send_transaction_params)

It is similar to the send_transaction endpoint but with additional options. It has the option to return a failure trace and the option to retry a transaction. It has the same format as send_transaction, save for the new configuration arguments (See A-1).

Transaction Retry

The transaction retry feature comes with new configuration arguments for nodeos and new command-line options for the cleos interface.

Configuration arguments are used to adjust the behavior of nodes, and can be used in the config.ini configuration file or directly in nodeos. Config files should have configuration items formatted as “option = value” while command line items can be formatted as “--option=value” or “--option value”. The new transaction retry arguments node operators can use in config.ini files or when starting an instance of nodeos consist of:

transaction-retry-max-storage-size-gb

This option sets the maximum storage space allocation (in GiB) allowed for the transaction retry feature. Setting this number above 0 enables this feature. Nodes with the feature disabled will reject transactions that request it.

transaction-retry-interval-sec (defaults to 20)

This option sets how often, in seconds, a node should re-send an incoming transaction to the P2P network if it doesn’t detect the transaction in a block.

transaction-retry-max-expiration-sec (defaults to 90)

This option sets the maximum allowed transaction expiration time for transactions in the retry pool. The transaction retry tool will not add transactions to the pool if they have an expiration time above this value.

p2p-dedup-cache-expire-time-sec (defaults to 10)

This option sets the deduplication cache. Adjusting this number adjusts the maximum time in seconds to keep track of a transaction while removing its duplicates from the transaction pool.

 The new command-line options for users interacting with the blockchain through cleos consist of:

--use-old-send-rpc (T/F)

This option forces cleos to use the older transaction formatting, using send_transaction instead of send_transaction2 with its new features. It is useful for testing and debugging old APIs.

-t, --return-failure-trace (T/F)

This option returns information on failed transactions to the user. It improves debugging, allowing users to see which specific action failed.

--retry-irreversible (T/F)

This option allows transaction signers to request that nodes retry a transaction until it is in an irreversible block or until the transaction expires. It is a blocking call. It will return an error if the node does not have the feature enabled.

--retry-num-blocks (T/F)

This option allows transaction signers to request that nodes retry a transaction until it has been seen in a block with a defined number of blocks ahead of it or until the transaction expires. It is a blocking call. It will return an error if the node does not have the feature enabled.

Transaction Finality Status

The transaction finality status feature returns a transaction’s status in response to requests. The tool stores transactions propagated by a node in a transaction pool until a transaction is expired or finalized for a specified number of blocks.

It includes the following arguments:

transaction-finality-status-max-storage-size-gb 

This option sets the transaction finality status pool’s storage size (in GiB). Nodes will drop older transactions when the pool size hits this limit. Setting it above zero enables this feature. Nodes with the feature disabled will reject transactions that request it.

transaction-finality-status-success-duration-sec

This option defines the length of time (in seconds) after a successful transaction has achieved finality that it will be kept in the transaction finality status pool.

transaction-finality-status-failure-duration-sec

This option defines the length of time (in seconds) after a failed transaction has reached its expiration time that it will be kept in the transaction finality status pool. 

New command-line options for cleos

get transaction-status <id>

This option allows a node, given a transaction ID, to return the current blockchain state and information on the transaction ID, including its finality status if available. It will return “UNKNOWN” if the transaction is not found.

New chain_api_plugin endpoint

/v1/chain/get_transaction_status (get_transaction_status_params )

This endpoint receives a transaction ID and returns the transaction finality state and other information about the transaction, if it is available. See A-2 for the syntax.

Transaction Resource Cost Estimation

The transaction resource cost estimation feature receives test transactions and returns their estimated resource costs without applying the transaction to the chain.

This feature replicates a solution Greymass has been using effectively to estimate resource costs for their ‘Greymass Fuel’ resource provider, which has been a tremendously helpful tool for preventing unintentional resource overrun failures. 

It includes one new configuration option and one new API endpoint.

New command-line option for cleos

--read-only

This option specifies that a transaction is “read-only” and not intended for inclusion in the blockchain. When a user sends a transaction with this option enabled, the connected node will execute the transaction and revert any state changes. 

New chain_api_plugin endpoint

compute_transaction

This node endpoint accepts and executes read-only transactions and then returns the computed resource costs for the transaction. It uses the same transaction parameters as the old send_transaction parameters.

Subjective Billing Improvements

New configuration args for nodeos

subjective-account-max-failures (default 3)

This configuration argument controls parameters used in the three-strikes rule. When activated, nodes will drop all queued transactions from an account after the account has sent three failed transactions in one block. Operators can change the maximum number of failures from three with the subjective-account-max-failures parameter.

subjective-account-decay-time-minutes (default 24 hours)

This option adjusts the subjective billing decay time, the time it takes to return full CPU time to subjectively billed accounts. Existing subjective billing balances use a 24-hour subjective billing decay window. 

The precise mechanism of this decay time involves measuring the exponential moving average of resource consumption from an account to determine its remaining resource budget. The protocol multiplies this remaining resource budget by the proportion of the subjective decay time window since the account last pushed a transaction. 

The formula (see A-3) uses the EMA of an account’s resource usage with linear extrapolation when data is missing, and it multiplies the currently accumulated average by:

Testing has found one hour (7200 blocks) to provide a balance between effective rate-limiting and minimal UX impact.

New terminate-at-block option.

With this nodeos command-line option, operators can configure nodeos to exit once it receives or replays a specified block number. Exiting at a specified block allows unattended progression to a desired state, and enables easy automation of pre-determined snapshots. The terminate-at-block option introduces one new parameter available in the nodeos command line.

New configuration arg for nodeos:

--terminate-at-block <block#>(defaults to 0, meaning disabled)

This option will terminate the nodeos instance after reaching the supplied block number, if the block number is set above zero. This option only works on the command line.

Get the current block number from within a contract.

The Leap v3.1 release introduces a new protocol feature GET_BLOCK_NUM, which makes the host function get_block_num accessible to smart contracts when the chain activates it. The get_block_num host function returns the block number, or block height, of the current block.

Block Log & state_history_plugin (SHiP) Log Pruning

Two new options, block-log-retain-blocks and state-history-log-retain-blocks, are available. These options configure nodeos to periodically prune these logs to the most recent configured blocks. Pruning allows node operators to reduce the amount of disk space nodeos uses over time without stopping the node.

The block-log-retain-blocks option also adds the --vacuum option to eosio-blocklog, which converts a pruned log into an unpruned format. The unpruned format expands sparse areas of the file that were collapsed during pruning, but doesn’t restore pruned data. The vacuum operation is automatically performed when a node operator removes the block-log-retain-blocks or state-history-log-retain-blocks options.

Crypto Primitives

The Leap v3.1 release introduces a new protocol feature called CRYPTO_PRIMITIVES, which makes seven new host functions accessible to contracts upon activation. These functions are all related to cryptographic computations and reduce the CPU costs of executing EVM precompiled contracts.

Leveraging these new host functions may significantly reduce execution time for their computations, because the host functions are implemented in native code without the overhead of a smart contract. This feature enables cryptographic functions that previously overran transaction deadlines, and ensures accessibility of other functions at a lower CPU cost.

• Modular exponentiation takes the form c=b^x mod(m). It raises an integer b by a power x, divides the result by an integer, and returns the remainder. Computation can quickly become difficult using arithmetic methods, as b^x gets enormous when using large numbers for strong cryptography. 

For example, the 1024-bit number 5¹⁰⁷⁶ raised to the 17th power produces a 1,304-digit number that arithmetic methods must divide to find its remainder. This process is slow for large numbers. CRYPTO_PRIMITIVES introduces an algorithm that does this kind of modular exponentiation efficiently for any size number.

• alt_bn128 is an elliptic curve, a polynomial formula of the general form y²=x³+ax+b. CRYPTO_PRIMITIVES introduces three host functions on this curve: 
  • point addition (alt_bn128_add)
  • scalar multiplication (alt_bn128_mul)
  • bilinear functions (alt_bn128_pair)

These functions are used extensively in zero-knowledge proofs (e.g. zkSNARKs) and other privacy-preserving data verification methods.

• The feature also introduces two new hash functions, sha3 and blake2_f. 
  • sha3 is an extension of the SHA2 hashing algorithm that is more secure against particular types of attacks known as length-extension attacks, where an attacker uses a message m₁ and its length to decode another message m₂ from the hashing function of m₁ x m₂. SHA3 is much more resistant to these attacks, and SHA3 algorithms can directly replace SHA2 algorithms. 
  • blake2_f is a hashing function that offers faster hashing speeds than sha3, combining the speed of the relatively insecure MD5 algorithm with the higher security level of the SHA3 algorithm.

• The libsecp256k library is a collection of elliptical curves used in computing EOSIO public-private key pairs. The Leap 3.1 release includes an update to a more recent version of this library that improves the performance of public-key recovery by 33%. 

The Antelope protocol has historically supported ECDSA public key recovery for the secp256k1 and secp256r1 elliptic curves through a host function called recover_key. 

The new k1_recover host function improves on recover_key. It returns the specific failure condition when given an invalid signature, rather than just a generic transaction abort failure.

In addition, it returns the recorded public key in uncompressed format, eliminating an elliptical curve mathematics step and reducing contract size and CPU execution time for the function.

Notably, it only supports the K1 elliptical curve and not the R1 elliptical curve.

Support for user-defined fields with the GELF logging protocol.

The GELF appender now supports arbitrary user-defined fields and values in the GELF logging.json configuration file, with the following restrictions: user-defined field names must begin with an underscore, and names can contain only letters, numbers, underscores, dashes, and dots. 

Beyond the format check, there is also a list of reserved field names reserved by the specification or used by nodeos (see A-4). 

There is no enforced limit on the field name length, the accompanying value, or the number of user-defined fields. However, by default, servers limit streams to 128 fragments of 512 bytes each, so messages over 65536 bytes might be dropped by the server based on its settings.

The GELF protocol enforces a similar practical maximum of 256 fragments of 512 bytes, totalling 131072 bytes.

The Graylog server automatically omits the leading underscore in user-defined fields when displaying them in selectors and the interface.

Mandel v3.0 Release Features

The Mandel v3.0 release included several features from the EOSIO v2.1 release that were ported to the Mandel v3.0 release. Among these are the ability to return a value in the action trace, configurable limits for a WASM runtime, and other configurable blockchain parameters. The features from the Mandel v3.0 release include:

• GET_CODE_HASH

Allows contracts to check if an account has a contract, the contract’s hash, and how many times the code has changed.

• ACTION_RETURN_VALUE

Allows actions to return values in the action trace.

• CONFIGURABLE_WASM_LIMITS2

Allows operators to increase limits on WASM files. 

• BLOCKCHAIN_PARAMETERS

Allows the configuration of blockchain parameters like the maximum return value supported by ACTION_RETURN_VALUE.

• onblock logging

Helps diagnose system contract failures.

More info on these features can be found in the release page for the Mandel v3.0.0 release.

3.0 also implemented a limited version of a feature called “contract pays” that allows a smart contract to pay for resources. This limited version uses a workaround that allows for the “publicly embedded private key” approach to be used without an immediate denial of service attack vector.

This version of the “contract pays” feature was not implemented as part of the protocol itself, but by adding a new feature to the EOS system contracts. It is part of the latest system contracts release, and allows developers to optionally restrict permission changes.

This approach is still vulnerable to other abuse through subjective billing. More work is required for a proper contract pays solution.

Other Release Notes

New Build Procedure

A new build process driven by CMake replaces the shell scripts previously recommended for building the software. Those who wish to build from the source code are now responsible for installing the necessary dependencies. The list of dependencies and the recommended build procedure are in the README.md file. The readme also includes instructions for efficiently running tests.

Ubuntu 18.04, 20.04, and 22.04 are the only supported build platforms. Other distributions, compilers, and platforms are known to work. Your experience may differ.

Compatibility

Snapshot compatibility

Node operators can use snapshots to sync nodeos more rapidly with the rest of the blockchain.

The newest snapshot version introduced with the Leap v3.1 release, v6, is only compatible with nodeos v3.1. The older v4 snapshot is compatible with the Leap v3.1 release, the EOSIO v2.0 release and the EOSIO v2.1 release. 

V5 snapshots are from the unsupported EOSIO v2.1 release and will NOT work with the Leap v3.1 release unless the EOSIO v2.1 release features are disabled. 

Network Compatibility

Network compatibility refers to the ability of a node to accept blocks and transactions over the p2p connection between nodes and to respond to block requests.

This release is compatible with networks running the EOSIO v2.0.x release and networks running the EOSIO v2.1 release as long as the network has NOT enabled the EOSIO v2.1 release-specific features.

State_history_plugin Compatibility.

The Leap v3.1 release is compatible with the block logs and state history plugin (SHiP) logs produced by the EOSIO v2.0 release, but NOT the EOSIO v2.1 release. 

The Leap v3.1 release’s new features required changes to the state history ABI. Consumers of state history from a Leap v3.1 nodeos instance must be prepared to handle the following changes.

A new action_trace_v1 and chain_config_v1 will be sent instead of the previous _v0 versions. Clients must be prepared to receive either the v0 or v1 variation, as they will continue to receive v0 versions from entries in the state history log before the upgrade to the Leap v3.1 release.

State File Compatibility.

This release is NOT compatible with the state files generated by earlier releases. Please use a compatible snapshot file generated from an earlier version of nodeos to rebuild the current state file.

Upgrading from Prior Releases

Generate a snapshot of the state from nodeos. You cannot use snapshots from the EOSIO v2.1 release, but snapshots from the Mandel v3.0 or Leap v3.1 releases as well as earlier snapshot versions will work.   

Remove the state file used by the upgrading node. If the node has been using EOSIO 2.1, operators must also remove the SHiP and block logs. SHiP and block logs can remain if the node is upgrading from the EOSIO v2.0 release.

Start nodeos with the snapshot. Afterwards, nodeos will start and stop as usual.

Deprecations & Removals

The Leap v3.1 release removes some deprecated features. Among these are the history_plugin and the mongoDB_plugin, both of which can use the state_history_plugin or the trace_history_plugin as an alternative. The Leap v3.1 release also removes WABT in favour of the more performant EOS VM. It also drops Mac support, although Mac and Windows users can still use DUNE to virtualize a Leap blockchain environment. 

The new update deprecates cleos WAST output, and a later update will remove it.

ABI conversion APIs are deprecated.

The APIs /v1/chain/abi_bin_to_json and /v1/chain/abi_json_to_bin have been deprecated as of this release and will be fully disabled or removed in a future release. This is due to the security risk of blindly trusting these APIs, which a malicious actor could exploit to switch parameters during the conversion. 

Build Scripts Removed.

As mentioned earlier, the Leap v3.1 release removes the build scripts. See the readme for instructions to build.

history_plugin removed.

The history_plugin was deprecated in 2018 as part of the EOSIO v1.2.0 release, and the Leap v3.1 release fully removes it. More RAM-efficient solutions like the state_history_plugin and Hyperion have since replaced the history_plugin. 

This means that nodes that initialize with the option --plugin eosio::history_plugin should instead migrate to the option --plugin eosio::trace_api_plugin or --plugin eosio::state_history_plugin. 

mongo_db_plugin removed

The mongo_db_plugin was deprecated as part of the EOSIO v1.8.0 release, and this release fully removes it.

Reversible block database removed

A chainbase database is no longer used to store the active set of reversible blocks during nodeos operation. The reversible blocks are still stored in the fork database upon shutdown.

Note: Node operators should remove any existing configuration for the reversible block Chainbase database from the config.ini file and any scripts, including: 

• reversible-blocks-db-size-mb
• reversible-blocks-db-guard-size-mb
• fix-reversible-blocks
• import-reversible-blocks 
• export-reversible-blocks

Dropped support for Ubuntu 16.04, Centos, and MacOS

(Supports Ubuntu 18.04, 20.04, 22.04) (Devs should use DUNE for Windows, Mac, and any Linux distribution that supports Docker)

Ubuntu 16.04, Centos, and macOS

As mentioned earlier, the only officially supported platforms are Ubuntu 18.04, 20.04 and 22.04. Leap has removed all others, including Ubuntu 16.04, Centos, and macOS, from binary package support and code-level changes.

Developers running the Leap v3.1 release on a non-Ubuntu machine should consider using DUNE, which supports Windows 10 and 11, macOS, and any Linux distribution that supports Docker.

Proposed Deprecations

Deprecate the r1 curve and multi-key control for Block Producers

A future release may deprecate block producers using R1 curves for signing blocks due to lack of use.

EOSIO originally allowed block producers to register multiple keys with multiple weights as a block producer, much as multiple weighted keys can control accounts. It also allowed block producers to register keys with the k1 or r1 curve. These are different curves used in elliptical-curve cryptography. 

Official documentation specified the r1 curve used a “verifiably random” curve. Bitcoin fans widely speculate that Satoshi Nakamoto, the creator of Bitcoin, didn’t trust this “verifiably random” curve not to have a potential backdoor. Because of this mistrust and the efficiency of the secp256k1 curve, Bitcoin uses the k1 curve. 

Block producers on EOS don’t use keys on the r1 curve or multi-key block production. This open Github issue seeking feedback proposes to drop support for keys on the r1 elliptic curve and drop multi-key producer authority. 

Replace YubiHSM Support with Generic HSM Support

The EOSIO v1.7 release shipped with a tool that allows users to easily create a key on the EOSIO tool keosd, using the YubiKey hardware authentication device. This proposal points out the unnecessary dependencies and software integration hurdles that this tool comes with and proposes an alternative tool compatible with any generic hardware authentication device, including the YubiKey. 

This alternative would require a new tool to facilitate smooth integration of the two-user generic tool into the single-user keosd environment.

Appendix

A-1 New send_transaction2 Endpoint structure:

The endpoint has the following structure:

struct send_transaction2_params {

    bool return_failure_trace = true; ///< Embed transaction exceptions into the returned transaction trace

    bool retry_trx = false; ///< request transaction retry on validated transaction

    std::optional<uint16_t> retry_trx_num_blocks{}; ///< if retry_trx, report trace at specified blocks from executed or lib if not specified

    fc::variant transaction; ///< same format as send_transaction
};

A-2 Syntax for the Transaction Finality Status Endpoint

The endpoint has the following syntax:

struct get_transaction_status_params {
      string id; //transaction id to status
 };
 struct get_transaction_status_results {
    string state;
    std::optional<uint32_t> block_number;
    std::optional<chain::block_id_type> block_id;
    std::optional<fc::time_point> block_timestamp;
    std::optional<fc::time_point> expiration;
    uint32_t head_number;
    chain::block_id_type head_id;
    fc::time_point head_timestamp;
    uint32_t irreversible_number;
    chain::block_id_type irreversible_id;
    fc::time_point irreversible_timestamp;
    chain::block_id_type last_tracked_block_id;
};

A-3 Resource cost calculation

The calculation uses an exponential moving average of an account’s chain utilization, using linear extrapolation when given limited data. It multiplies the currently accumulated average by (number of blocks in the window – number of blocks since the last update) / (number of blocks in the window). 

EMA is calculated for each period in a window, such that:

EMA = Exponential moving average, 

k = Weighting multiplier, k = 2N + 1 where N = the number of periods in the time window.

p_c= This period’s closing price, 

EMA_p= Previous period’s EMA, with the first period’s EMA = the SMA of the time window.

The formula is:

EMA is calculated one period at a time, starting with the first period. The EMA of the first period is the same as the SMA (Simple Moving Average), which uses a typical averaging formula of:

Where n is the number of periods in a window and A is the value of each period.

A-4 GELF Reserved Fields:

The list of reserved field names is:

_id
_timestamp_ns
_log_id
_line
_file
_method_name
_thread_name
_task_name

A-5 Additional Tools

Alongside Leap 3.1, two additional related tools have also been released under the AntelopeIO GitHub organization:

• An updated Contract Development Toolkit (CDT)
• A new tool called Docker Utility for Node Execution (DUNE), for multi-OS support.

Additionally, the EOS Network Foundation has also released EOS System Contracts v3.1.

Contract Development Toolkit (CDT)

The Contract Development Toolkit (CDT) is a suite of tools that smart contract developers can use to compile their contracts to WebAssembly. CDT version 3.0.0 implements several changes to this tool. 

Developers need to be aware that this release changes the toolkit’s name from “eosio.cdt” to just “cdt”. Developers need to change their CMake files and replace each instance of “eosio.cdt” with “cdt” to accommodate this change.

Renaming changes include:

• Name changes to the binaries, so that they have a prefix of “cdt” rather than “eosio” i.e. eosio-cpp becomes cdt-cpp etc.
• CMake projects use find_package(cdt) instead of find_package(eosio.cdt).
• All library paths and namespaces remain the same, but may be assigned to deprecated features in a future release.

Crypto Extensions

The Leap v3.1 release adds support for the GET_BLOCK_NUM protocol feature which adds a host function to get the current block number as well as the CRYPTO_PRIMITIVES protocol feature which adds a new set of crypto primitive host functions. To allow smart contract developers the ability to leverage these, the CDT v3.0 release has added these to the C API and some of them to the C++ API.

C API now has the functions:

void sha3( const char*, uint32_t, char*, uint32_t , int32_t)
int32_t blake2_f(uint32_t, const char*, uint32_t, const char*, uint32_t, const char*, uint32_t, const char*, uint32_t, int32_t, char* , uint32_t)
int32_t k1_recover( const char*, uint32_t, const char*, uint32_t, char*, uint32_t)
int32_t alt_bn128_add( const char*, uint32_t, const char*, uint32_t, char*, uint32_t)
int32_t alt_bn128_mul( const char*, uint32_t, const char*, uint32_t, char*, uint32_t)
int32_t alt_bn128_pair( const char*, uint32_t)
int32_t mod_exp( const char*, uint32_t, const char*, uint32_t, const char*, uint32_t, char*, uint32_t)
uint32_t get_block_num( void )

The C++ API now has the functions:

block_num_t current_block_number() - (in system.hpp)
eosio::checksum256 sha3(const char*, uint32_t) - (in crypto.hpp)
eosio::checksum256 keccak(const char*, uint32_t) - (in crypto.hpp)
void assert_sha3(const char*, uint32_t, eosio::checksum256&) - (in crypto.hpp)
void assert_keccak(const char*, uint32_t, eosio::checksum256&) - (in crypto.hpp)

The CDT v3.0 release only adds C++ wrappers for the SHA3 hash functions and the function to get the current block number. C++ wrappers for the other host functions and their associated data types will be added in a later release of CDT.

Stack Canary

The CDT also includes the new Stack Canary feature that prevents stack overflows when the stack is placed at the end of the contract’s reserved portion of memory. The “stack” is the portion of the memory that grows as further nested functions are called. 

When using the flag -fno-stack-first to allow for large stack sizes, smart contract developers open themselves up to unexpected results or severe bugs. Normally, CDT places the stack at the beginning of a set of addressable memory. This has the benefit of preventing memory overruns, as stack overflows will spill into the contract data and trigger a memory access violation, causing the program to terminate rather than causing unexpected behavior or severe bugs. However, WASM is limited to processing static data from only the first 64kb page of WASM memory. This limits the size of the stack to 64KiB minus the size of the contract data, as the contract must be within the first 64KiB of memory. 

CDT gives contracts the option to place the stack at the end of addressable memory. This opens the entire 64KiB first page to static data, allowing for a larger stack. However, this introduces the possibility of a stack overflow overwriting out-of-scope memory. 

To mitigate this, the CDT v3.0 release adds the -stack-canary option. This adds some protection to smart contracts, so if a contract overbounds the stack, it will fail the contract instead of possibly allowing it to finish with unexpected results.

To fix this, CDT 3.0.0 introduces the “Stack Canary”, which detects when a stack overflow occurs and terminates the process. This prevents the stack from overwriting memory outside of its scope, providing the same benefits as keeping the stack at the beginning of memory, while still allowing for more initial memory (global variables and strings) and larger stack sizes.

If this fails it will produce an assertion code of 8000000000000000002.

Bug Fixes

Because of build issues, the CDT v3.0 release has removed the ability to compile CDT with ccache and sccache.

Docker Utilities for Node Execution (DUNE)

DUNE is an environment designed to run on macOS, Windows 10 & 11, and other operating systems that the Leap v3.1 release does not directly support. DUNE requires Docker and Python3, but is otherwise straightforward to implement, with instructions for each operating system in the readme. It offers the same commands as CDT and nodeos, cleos, and other Leap v3.1 components. It also offers other abstracted commands that involve all of these components. Importantly, it allows anyone with a Docker-capable machine to develop and test on the EOS network.

EOS System Contract Upgrade

The EOS System Contracts v3.1 release updates the core contract and introduces a new system contract, the boot contract. 

The boot contract aids in bootstrapping a new blockchain.

All host functions introduced in protocol features other than PREACTIVATE_FEATURE are unavailable until their features are activated using a privileged contract such as the core contract. Deployment of the core contract requires specific host functions introduced via protocol features to be available. This creates an activation paradox, preventing deployment of the core contract. 

The boot contract circumvents this issue. The boot contract does not have dependencies on any protocol features other than PREACTIVATE_FEATURE, which can be activated by a block producer without using a smart contract. The preactivate_feature host function, which is made available to privileged contracts through activation of PREACTIVATE_FEATURE, allows the privileged boot contract to activate each of the protocol features needed to deploy the core contract.  When aiming to deploy the core contract on a new chain, the initial steps involve activating the PREACTIVATE_FEATURE protocol feature via a block producer, deploying the boot contract, and then using the boot contract to activate all other protocol features required by the core contract.

The core contract upgrade requires that the CONFIGURABLE_WASM_LIMITS2 and BLOCKCHAIN_PARAMETERS features have been activated. Once these features are activated, the new core contract can be deployed on-chain. The new core contract now allow for:

• The ability to restrict permission changes
• Configurable WASM limits 
• A blockinfo table that tracks the 10 most recent blocks 
• Memo fields in setabi and setcode 
• Updates to adjustable blockchain parameters
• Various bug fixes and patches.

Restricting Permissions Changes

One new action in the core contract, limitauthchg, allows accounts to optionally restrict permission changes. Using this, accounts can put additional constraints on the updateauth, deleteauth, linkauth, and unlinkauth actions.

The limitauthchg action can define which permissions to either allow or disallow using either allow_perms or disallow_perms. Nodes can call limitauthchg for allow_perms or disallow_perms to opt into the feature, but a given call cannot contain both allow_perms and disallow_perms. If allow_perms are defined, then the defined permissions are permitted to perform update, delete, link, and unlink authorization actions. If disallow_perms are defined, then the defined permissions are not permitted to perform these actions.

Accounts can opt into this feature by calling the limitauthchg action with non-empty allow_perms or disallow_perms. They can opt out again by calling the limitauthchg action with empty allow_perms and disallow_perms. 

This feature is helpful for mitigating denial-of-service attacks. Specifically, it can prevent attacks involving an existing resource management solution that uses a publicly available private key to manage resources for an application’s users.

Configurable WASM Limit

The core contract includes the CONFIGURABLE_WASM_LIMITS2 protocol feature, and an action wasmcfg that adjusts the WASM limit. Valid values of wasmcfg are high, low, and default, although low and default are equivalent. Set wasmcfg as high to increase the maximum bytes used for mutable globals by 8x, the maximum number of table elements by 8x, and the maximum initializable memory range by 16x. Developers need to be aware that if this feature is set to high when a contract is initialized, if they reset the feature to low or default it may cause the contract to overrun the new WASM limit and cease to function.

Tracking Recent Block Info

A new table has been introduced, blockinfo, which includes the table version number with the block height and timestamp of the 10 most recent blocks. The get_latest_block_batch_info function returns the block height and timestamp of the starting and ending block of a given batch of 10 blocks. It returns “insufficient data” if one of the blocks within this batch is missing. Blocks may be missing due to either early deletion of the first block or gaps caused by failure of the onblock action. This error will also occur if the batch start height is greater than the latest block height.

Additional changes

Memo fields are now available in the setcode and setabi actions. This allows contract developers to specify contract versions and release notes directly on the blockchain.

The setparams action has more parameters available, including max_action_return_value_size, which is used in the ACTION_RETURN_VALUE protocol feature.

The new system contracts include a fix to a rounding error bug in REX that prevented accounts from selling REX. It also features a patch that incorporates the system contract change that resulted in freezing B1’s token vesting schedule.

More information on these features is in the system contracts release notes, at https://github.com/eosnetworkfoundation/eos-system-contracts/releases/tag/v3.1.0-rc1