New features

Read-Only Transactions

We have introduced a RPC endpoint for sending read-only transactions. A read-only transaction does not change the state and is not added into the blockchain (chainbase). It is useful for users to retrieve more complex chain information.

The format is the same as regular transaction, except it does not contain authorization section. Mechanisms are in place to ensure actions (including inline actions) in a read-only transaction do not modify the state and deepmind logging is not performed.

The RPC URL is v1/chain/send_readonly_transaction

Cleos is updated to send read-only transactions:

• cleos push transaction --read <transaction>
• cleos push action --read <action>

New producer_plugin logging categories are added for transient transactions (dry-run (by compute_transaction) and read-only transactions). They are transient_trx_success_tracing and transient_trx_failure_tracing . Existing transaction_success_tracing and transaction_failure_tracing do not include the logging for transient transactions.

max_action_return_value_size is not enforced for read-only transactions.

Auto-peering with schedule proximal BP nodes

We've added a config option to automatically manage connections based on the BP schedule. Node order and peering can impact a node's latency to receive last block of the preceding BP, and to send their last block to the next BP. Ideally Block Producers:

• receive the last block of the previous round as soon as possible
• send their last block to the next Block Producer as soon as possible
• avoid getting a late start on their block production

To achieve these goals, the following changes were made in v4.0.0:

Correlate BP account names and connection details

--p2p-auto-bp-peer has been added to nodeos to allow a node to correlate BP account names to p2p connection details. When a block producer node with this setting detects a pending schedule change, it will attempt to auto-peer with BPs that have come into schedule proximity, and disconnect from any auto-peered BPs that are no longer in schedule proximity. These auto-peered connections are not subjected to the limit specified by the --max-clients option.

BP Peer flag in net api

is_bp_peer has been added to every connection object in the v1/net/connections api endpoint response.

Snapshot Scheduling API

The Snapshot Scheduling API added in Leap v4.0.0 allows users to schedule and manage snapshot requests in advance, increasing reliability and reducing the potential for errors in the snapshot creation process. It also allows for greater flexibility in creating and managing snapshots, as users can specify parameters such as start and end blocks and block spacing.

The API provides endpoints for several features:

• /producer/schedule_snapshot: Add a task to perform snapshots
  • Parameters: start_block, end_block, block_spacing, snapshot_description
• /producer/get_snapshot_requests: Return all scheduled snapshot requests
• /producer/unschedule_snapshot: Remove a previously scheduled snapshot task
  • Parameters: snapshot_request_id

For more details, check out the Snapshot Scheduling API Design Specs.

Prometheus Exporter Plugin

Instrumentation of nodeos plugins to expose data with Prometheus. An initial phase of instrumentation will allow for the evaluation of the usability of the instrumentation when viewed from Prometheus. The initial instrumentation will not include any per account or per contract metrics. Additionally, the ability to expire metrics will not be included in the initial phase. To support dynamic metrics, the metric object for each plugin will include an indicator of when the set of metrics has last changed. The following metrics will be collected for the initial phase of instrumentation:

Net Plugin
gauge - number of clients
gauge - number of peers
gauge - number of dropped blocks

Producer Plugin (Producer plugin metrics will be gathered at the start of each block)
gauge - unapplied transaction queue sizes (number of transactions)
counter - blacklisted transactions count (total)
counter - blocks produced
counter - transactions produced
gauge - last irreversible
gauge - current block num
gauge - subjective billing number of accounts
gauge - subjective billing number of blocks
gauge - scheduled transactions

See the Prometheus Plugin Architecture for more details.

Log Splitting

Leap v4.0.0 includes two similar features aimed at giving node operators greater control over how important logs for blocks and state are managed: blocks log splitting and state history log splitting. The key benefit of these features is that it allows users to specify how many split log files to retain, and automates aging out older logs by deleting them or moving them another directory.

Blocks Log Splitting

To make it easy to use block log splitting, we've added some new options for the chain plugin:

• blocks-log-stride allows you to split the block log file when the head block number is the multiple of the stride. When the stride is reached, the current block log and index will be renamed 'blocks--.log/index', and a new current block log and index will be created with the most recent block. All files following this format will be used to construct an extended block log.
• max-retained-block-files alows you to specifiy the maximum number of block files to retain so that the blocks in those files can be queried. When the number is reached, the oldest block file would be moved to an archive directory or deleted if the archive directory is empty. It's important to note that the retained block log files should not be manipulated by users.
• Two new options allow you to configure the locations of blocks log directories, we've added two new options:
  • blocks-archive-dir allows you to specify the location of the blocks archive directory (absolute or relative path). If the value is empty, blocks files beyond the retained limit will be deleted. Files in the archive directory won't be accessed by nodeos anymore.
  • blocks-retained-dir allows you to specify the location of the blocks retained directory (absolute or relative path). If the value is empty, it is set to the value of the blocks dir.

Please note that all of the newly added options cannot be specified together with the --block-log-retain-blocks option. Overall, we believe that the Blocklog splitting feature and its associated options will help you better manage your block logs and improve the efficiency of your nodeos instance.

SHiP Log Splitting

To make it easy to use SHiP Log Splitting, we've added some new options for the state history plugin:

• state-history-stride allows you to split the state history log file when the block number is the multiple of the stride. When the stride is reached, the current history log and index will be renamed '*-history--.log/index', and a new current history log and index will be created with the most recent blocks. All files following this format will be used to construct an extended history log.
• max-retained-history-files allows you to specify the maximum number of state history log file groups to retain so that the blocks in those files can be queried. When the number is reached, the oldest log files would be moved to an archive directory or deleted if the archive directory is empty. The retained log files should not be manipulated by users.
• state-history-retained-dir allows you to specify the location of the state history retained directory (absolute path or relative to state-history dir). If the value is empty, it is set to the value of the state history dir.
• state-history-archive-dir allows you to specify the location of the state history archive directory (absolute path or relative to state-history dir). If the value is empty string, log files beyond the retained limit will be deleted. All files in the archive directory are completely under user's control, i.e. they won't be accessed by nodeos anymore.

Please note that all of the newly added options cannot be specified together with the --state-history-retain-num option. Overall, we believe that the SHiP Log Splitting feature will help you better manage your state history log files and improve the efficiency of your nodeos instance. We look forward to seeing how this feature will benefit the Leap community.

Performance improvements

Parallelize Read-Only Transaction Execution

Regular read-only transactions are executed sequentially on the main thread. To take advantage of multi-core architecture, offloading them from the main thread and executing them multi-threaded will make more time for the main thread and improve throughput of read-only transactions.

We have implemented a feature to parallelize read-only transaction execution. The design is documented in https://github.com/eosnetworkfoundation/product/blob/main/transactions/read-only/parallel.md.

When this feature is enabled, the node toggles between write and read windows. In the write window, the node operates normally, except read-only transactions are queued for later parallel execution in the read window. In the read window, the queued read-only transactions are executed in a dedicated thread pool, while operations safe to read-only transaction execution are executed on the main thread.

New configuration options are

  --read-only-threads arg (=0)          Number of worker threads in read-only
                                        transaction execution thread pool
  --read-only-write-window-time-us arg (=200000)
                                        time in microseconds the write window
                                        lasts
  --read-only-read-window-time-us arg (=60000)
                                        time in microseconds the read window
                                        lasts

If --read-only-threads is not configured or configured to 0, this feature is not enabled; read-only transactions are executed on the main thread.

--read-only-threads is not allowed on a producer node.

--read-only-read-window-time-us must be greater than --max-transaction-time.

Lighter Validation for Relays

This feature aims to reduce the latency of block propagation by enabling nodes to relay blocks before fully validating or computing state, as long as certain conditions are met. With this new feature, nodes can immediately process received blocks after validating their headers, even when there is a backlog of pending transactions. Additionally, the new implementation includes optimizations for broadcast blocks behavior and peer_block_state_index, further improving block propagation times. The goal of lighter validation on relays is to reduce the latency of block propagation.

Other Multithread Support

We have moved more tasks out from the main thread and process them in separate threads:

• block_log has been made thread safe.
• net_plugin updated to use thread safe block_log from net threads instead of having to post onto the main thread for processing.
• SHiP writes to the state history logs on the main thread, but reads from them on the SHiP thread. The state history logs have been made thread safe.
• /v1/chain/get_block performance has been significantly improved by moving abi serialization off the main thread.

Other changes

Faster bilinear group cryptography library for EVM support

The Ethereum Virtual Machine on EOS requires bilinear group cryptography. The libff and bn256 libraries were benchmarked against each other. Each test run used the same 10 pairs of points as input and run through the same initialization and pairing. The bn256 library was selected as most performant, and ported into Antelope Leap v4.0.0.

Building, compatibility, and upgrading

Upgrading from prior releases

To upgrade from Leap 3.X.X to Leap 4.0.0:

• Install Leap v4.0.0
• Edit config.ini and remove any set configuration items that no longer exist in v4.0.0 :
  • nodeos read-mode=speculative, read-mode=read-only, disable-api-persisted-trx, private-key, https-client-root-cert, https-client-validate-peers, https-server-address, https-certificate-chain-file, https-private-key-file, https-ecdh-curve, plugin=eosio::trx_test_gen_plugin, txn-reference-block-lag, txn-test-gen-threads, txn-test-gen-account-prefix, txn-test-gen-expiration-seconds, txn-test-gen-stop-on-push-failed, plugin=eosio::login_plugin, max-login-requests, max-login-timeout.
  • keosd yubism-url, yubism-authkey, https-server-address, https-certificate-chain-file, https-private-key-file, https-ecdh-curve.
• Restart the binaries while pointing to the same data directories and the updated config
  • Persisted data files used by Leap v3.1.X and v3.2.X are compatible with Leap v4.0.0.

Feature Lifecycle Updates

Removed features in v4.0.0

Speculative mode

WARNING Previously with read-mode=speculative a transaction submitted to an API node would maintain any state changes for subsequent transactions submitted to the same API node. For example, create a new account in one transaction and then transfer to that account in a subsequent transaction. This typically worked with read-mode=speculative but no longer will work under read-mode=head. Now the transfer transaction will need to wait for the block with account creation to be created by a block producer and then applied locally before the transfer would be allowed.

The use of read-mode=speculative caused confusion for users by showing a false state of executed transactions, which is different from any other node. In v4.0.0 of Leap, the speculative read mode was removed and only head or irreversible modes are now available. The disable-api-persisted-trx option was also removed as persisted transactions are no longer supported. The deprecated read-mode=read-only was replaced with a combination of options for better control:

• read-mode=head
• p2p-accept-transactions=false
• api-accept-transactions=false

These changes better reflect the actual state of execution, reduce user confusion, and improve control over transaction behavior by introducing more clearly defined options.

HTTPS in nodeos and keosd

• removed HTTPS support (and code) from http_plugin
• removed HTTPS support (and code) from http_client_plugin (mostly in libfc)
• removed OpenSSL::SSL from libraries/libfc/CMakeLists.txt

Direct YubiHSM support

The original implementation of YubiHSM support required additional dependencies, complicated the build process, lacked sufficient automated testing, and prevented natively building Leap for ARM on macOS. Leap v4.0.0 removes support for YubiHSM.

Transaction Generator

The old txn_test_gen_plugin was deprecated in favor of the new trx_generator. Tests previously using txn_test_gen_plugin were updated to use trx_generator. Additionally, performance tests and configuration options were added to trx_generator.

Login Plugin

The Login Plugin (login_plugin) appears to be an abandoned demo/prototype/PoC from early EOSIO implementations. It was removed in Leap v4.0.0.

Blocklog Utility

The deprecated eosio-blocklog program blocklog-util has been removed in v4.0.0, please use leap-util block-log instead. Output file names have changed when using leap-util block-log extract-blocklog. The file names now include the start and end block numbers as a suffix. For example, blocks-100-200.log and blocks-100-200.index.

Example 1

eosio-blocklog --as-json-array --blocks-dir .

...is now...

leap-util block-log print-log --as-json-array --blocks-dir .

Example 2

eosio-blocklog --trim-blocklog -f 1 -l 100 --blocks-dir .

...is now...

leap-util block-log trim-blocklog -f 1 -l 100 --blocks-dir .

Example 3

eosio-blocklog --extract-blocks -f 1 -l 100 --blocks-dir . --output-dir newdir

...is now...

leap-util block-log extract-blocklog -f 1 -l 100 --blocks-dir . --output-dir newdir

Private-key nodeos config

The private-key nodeos config was deprecated since EOSIO v1.0.0 and is now removed in favor of signature-provider nodeos config.

For example:

--private-key [\"EOS6hMjoWRF2L8x9YpeqtUEcsDKAyxSuM1APicxgRU1E3oyV5sDEg\",\"5JgbL2ZnoEAhTudReWH1RnMuQS6DBeLZt4ucV6t8aymVEuYg7sr\"]

Becomes:

--signature-provider EOS6hMjoWRF2L8x9YpeqtUEcsDKAyxSuM1APicxgRU1E3oyV5sDEg=KEY:5JgbL2ZnoEAhTudReWH1RnMuQS6DBeLZt4ucV6t8aymVEuYg7sr

Cleos send transaction --read-only

--read-only option is removed in cleos send transaction command. Use --dry-run instead for compute_transaction

eosio-launcher

eosio-launcher is removed and replaced by launcher.py.

Remove deprecated abi serialization/deserialization endpoints

Remove the deprecated endpoints:

• /v1/chain/abi_bin_to_json
• /v1/chain/abi_json_to_bin

All deprecated features, not yet removed

fc and wasm-spec-tests repos

Due to limited cases for fc and wasm-spec-tests have been integrated directly into leap repository. Further development on related code will occur directly in the leap repository and the only development that will occur within the fc and wasm-spec-tests repositories are critical bug fixes that are necessary to support Leap 3.1 patches. The fc and wasm-spec-tests repositories will be archived in an upcoming version of Leap.

Ubuntu 18.04 Support

Support for Ubuntu 18.04 will be removed in an upcoming version of Leap. Please use Ubuntu 20.04 or 22.04.

More Information

The latest state of deprecations for Leap can be found by visiting our deprecations and proposed deprecations page.

Further details on changes since last release

Contributors

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

• @heifner
• @linh2931
• @kj4ezj
• @lparisc
• @ClaytonCalabrese
• @oschwaldp-oci
• @spoonincode
• @ScottBailey
• @mikelik
• @MaximSmolskiy
• @ndcgundlach
• @766C6164
• @huangminghuang
• @pnx
• @jgiszczak
• @systemzax
• @greg7mdp
• @ericpassmore
• @jolly-fellow

Full list of changes since last release

Full Changelog:
v4.0.0-rc1: v3.2.1...v4.0.0-rc1
v4.0.0-rc2: v4.0.0-rc1...v4.0.0-rc2