Skip to content

Leap v3.1.0

Compare
Choose a tag to compare
@arhag arhag released this 23 Aug 22:42
· 356 commits to release/3.1 since this release
v3.1.0
3c9661e

Release 3.1.0 includes protocol upgrades enabling:

  • contracts to get the current block number and the hash of any contract deployed on an account;
  • return values from actions which are accessible from the action trace;
  • additional ability to configurable consensus parameters including increasing various limit enforced by the WebAssembly VM;
  • and, access to various natively implemented cryptographic functions from contracts.

This release also includes many other new features including:

  • a new transaction submission API endpoint with full trace of a transaction failure and automatic nodeos-mediated retry;
  • nodeos-mediated cache of transaction finality statuses along with a new API endpoint to query the finality status of a transaction;
  • the ability to request a nodeos computation of transaction costs without committing the transaction;
  • the addition of new options for subjective billing;
  • automatic pruning of old entries in block and state_history_plugin (SHiP) logs;
  • and, much more.

Leap v3.1.0 Release Notes

Protocol changes

Action return values

A new protocol feature ACTION_RETURN_VALUE has been introduced which upon activation will make the host function set_action_return_value accessible to contracts. The set_action_return_value allows a contract to set a binary blob as the return value for the action. The last set value, if any, at the time the action completes will be used as the return value of the action which is stored in the action trace but also committed to within the action Merkle tree whose root is stored in the block header. ABI support allows for interpreting this binary blob as a structure similar to how it is done for the action input arguments.

The maximum allowed size for the binary blob for each action is enforced by the new blockchain parameter max_action_return_value_size which defaults to 256 bytes.

Note that while an off-chain client can access the action return value, a contract calling another contract via an inline action has no way to access the return value of the inline action.

Additional configurability of consensus parameters

A new protocol feature BLOCKCHAIN_PARAMETERS provides an alternative extensible mechanism to configure the existing blockchain parameters. Any new blockchain parameters, including the max_action_return_value_size parameter introduced with the ACTION_RETURN_VALUE protocol feature, are retrieved or modified only through this new mechanism to access the values of the parameters. The new mechanism consists of consists of getter and setter host functions, get_parameters_packed and set_parameters_packed respectively, which are made accessible only to privileged contracts upon activation of the BLOCKCHAIN_PARAMETERS protocol feature.

Additionally, another new protocol feature CONFIGURABLE_WASM_LIMITS2 provides a mechanism to adjust limits of the WebAssembly VM that were previous hard-coded. This mechanism consists of consists of getter and setter host functions, get_wasm_parameters_packed and set_wasm_parameters_packed respectively, which are made accessible only to privileged contracts upon activation of the CONFIGURABLE_WASM_LIMITS2 protocol feature.

Get code hash from within contracts

A new protocol feature GET_CODE_HASH has been introduced which upon activation will make the host function get_code_hash accessible to contracts. The get_code_hash host function allows any contract to specify the name of an account and then get back the number of times contract code was deployed to that account and the SHA256 hash of the contract code currently deployed on the account.

Host functions to accelerate crypto primitives

A new protocol feature CRYPTO_PRIMITIVES has been introduced which upon activation will make 7 new host functions accessible to contracts which are all related to cryptographic computations.

While in theory all of these cryptographic computations could be implemented in WebAssembly code if the transaction was given sufficient time to execute before timing out, leveraging these new host functions may allow for significantly reducing the time it takes to execute the computations because the computations are carried out in native implementation of the host executable. This means some cryptographic functions now become practically accessible to contracts even with typical transaction deadlines in production blockchains, and some others continue to remain accessible but at a lower CPU cost.

In particular, all of these new host functions serve to reduce CPU costs of executing the cryptographic functions available in EVM precompiled contracts.

Arbitrary-precision exponentiation under modulo

Activation of the CRYPTO_PRIMITIVES protocol feature introduces the mod_exp host function which enables modular exponentiation with arbitrary-precision numbers.

Support for the alt_bn128 elliptic curve

Activation of the CRYPTO_PRIMITIVES protocol feature introduces the following three host functions that support elliptic curve math involving the alt_bn128 elliptic curve:

  • alt_bn128_add: Point addition on the alt_bn128 elliptic curve.
  • alt_bn128_mul: Scalar multiplication on the alt_bn128 elliptic curve.
  • alt_bn128_pair: Bilinear function on groups on the alt_bn128 elliptic curve.

These host functions can support implementations that verify zkSNARKs.

ECDSA uncompressed public key recovery for the secp256k1 elliptic curve

The protocol already supported ECDSA public key recovery for the secp256k1 elliptic curve (and also for the secp256r1 elliptic curve) through the recover_key host function. However, that host function has two limitations. First, it aborts the transaction if an invalid signature is presented rather than returning a failure condition to the caller. Second, it returns the recovered public key in compressed format. And going from a compressed to uncompressed public key requires elliptic curve math which involves compiling in an elliptic curve library into the contract, thus bloating the contract size and increasing CPU time for ECDSA uncompressed public key recovery.

Activation of the CRYPTO_PRIMITIVES protocol features introduces the k1_recover host function which addresses both limitations of recovery_key mentioned above. However, it has its own limitation of only supporting the secp256k1 elliptic curve. There is currently no host function that returns an uncompressed public key from ECDSA recovery using the secp256r1 elliptic curve.

Additional support for hash functions

Activation of CRYPTO_PRIMITIVES protocol feature introduces the following two host functions:

  • sha3: This host function computes the SHA3-256 hash of an arbitrary byte string. Both the NIST and Keccak variants are supported.
  • blake2_f: This host function implements the compression function F used in the BLAKE2 cryptographic hashing algorithm.

Get current block number from within contracts

A new protocol feature GET_BLOCK_NUM has been introduced which upon activation will make the host function get_block_num accessible to contracts. The get_block_num host function returns the block number (aka block height) of the current block.

New features

New transaction submission API

PRs

  • (mandel#79) Transaction retry feature
  • (mandel#88) Many Transaction Long Running Test
  • (mandel#89) Add new transaction retry integration test
  • (mandel#116) Add docs for transaction retry
  • (mandel#173) Implement return failure traces
  • (mandel#809) [3.1] Increase default transaction-retry-max-expiration-sec from 90 to 120


New chain_api_plugin endpoint:

  • /v1/chain/send_transaction2(send_transaction_params)

    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
    };

This new transaction submission API supports returning the full trace of a failed transaction and automatic nodeos-mediated retry if enabled on the node.

When transaction retry is enabled on an API node, it will monitor incoming API transactions and ensure they are resubmitted additional times into the P2P network until they expire or are included in a block.

⚠️ Warning: Full failure traces are now returned by default instead of exceptions. Be careful to not confuse a returned trace as an indication of speculative execution success. Verify receipt and except fields of the returned trace.

New configuration args for nodeos:

  • transaction-retry-max-storage-size-gb
    • "Maximum size (in GiB) allowed to be allocated for the Transaction Retry feature. Setting above 0 enables this feature."
  • transaction-retry-interval-sec (defaults to 20)
    • "How often, in seconds, to resend an incoming transaction to the P2P network if not seen in a block."
  • transaction-retry-max-expiration-sec (defaults to 120)
    • "Maximum allowed transaction expiration for retry transactions, will retry transactions up to this value."
  • p2p-dedup-cache-expire-time-sec (defaults to 10)
    • "Maximum time in seconds to track transaction for duplicate optimization"

New command line options for cleos:

  • --use-old-send-rpc
    • "Use old RPC /v1/chain/send_transaction, rather than new RPC /v1/chain/send_transaction2"
  • -t,--return-failure-trace defaults to true use -t false for previous behavior
    • "Return partial traces on failed transactions"
    • Note: Automation which depends on cleos to return a non-zero value on transaction failure will instead need to parse the traces or use option -t false.
  • --retry-irreversible
    • "Request node to retry transaction until it is irreversible or expires, blocking call"
  • --retry-num-blocks
    • "Request node to retry transaction until in a block of given height, blocking call"

Transaction finality status

PRs


New chain_api_plugin endpoint:

  • /v1/chain/get_transaction_status(get_transaction_status_params)

    struct get_transaction_status_params {
        transaction_id_type                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;
    };

When transaction finality status is enabled, the status of a transaction in the node, as well as a snapshot of the current chain state, can be queried. If a transaction is not found for the given transaction id, only the chain status fields and a status of "UNKNOWN" will be provided.

New configuration args for nodeos:

  • transaction-finality-status-max-storage-size-gb
    • "Maximum size (in GiB) allowed to be allocated for the Transaction Finality Status feature. Setting above 0 enables this feature."
  • transaction-finality-status-success-duration-sec (defaults to 180)
    • "Duration (in seconds) a successful transaction's finality status will remain available from being first identified."
  • transaction-finality-status-failure-duration-sec (defaults to 180)
    • "Duration (in seconds) a failed transaction's finality status will remain available from being first identified."

New command line options for cleos:

  • get transaction-status <id>
    • "Gets current blockchain state and, if available, transaction information given the transaction id"

Transaction Resource Cost Estimation

PRs

  • (mandel#86) Added capability for read-only txns / added compute_transaction to chain api
  • (mandel#108) Ignore signature verification for compute_transaction / integration tests
  • (mandel#109) Added compute_transaction functionality
  • (mandel#114) Don't apply subjective billing to read-only transactions


New chain_api_plugin endpoint:

  • /v1/chain/compute_transaction
    • accepts existing send_transaction_params

Transactions sent to this endpoint will be executed and create a transaction trace, including resource usage, and then will revert all state changes and will not contribute to the subjective billing for the account. If the transaction has signatures, they will be processed, but any failures will be ignored. Transactions which fail will always include the transaction failure trace.

⚠️ Warning: Users with exposed nodes who have enabled the compute_transaction endpoint should implement some sort of throttling to protect from Denial of Service attacks.

New command line options for cleos:

  • --read-only
    • "Specify a transaction is read-only"

Block log & state_history_plugin (SHiP) log pruning

PRs

  • (mandel#342) block log pruning: optionally reduce disk usage of block log file during operation by periodically trimming blocks
  • (mandel#327) ship log pruning: optionally reduce disk usage of ship log files during operation by periodically trimming logs
  • (mandel#483) [3.1] bump fc submod with fix for macos hole punching


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

Other changes

Upgraded cryptography library libsecp256k1

PRs

  • (mandel#128) replace old libsecp256k1 fork with upstream


The branch of the libsecp256k1 library in use was many years old. The newly adopted version enables significant performance improvements, as well as including bug fixes.

K1 signature key recovery performance improvements:

CPU Previous New
Intel 9600k 50 µs 33 µs
AMD 5950X 51 µs 35 µs

(exact performance numbers will vary depending on hardware, OS, and system load)

The library's own unit tests are now incorporated into the suite of tests executed by Leap.

Subjective billing improvements

PRs

  • (mandel#84) Add Configured Whitelist to Ignore Number of Failures
  • (mandel#82) Configurable max_failures_per_account
  • (mandel#90) Configurable subjective account decay time


Account max failures: During block production, accounts are permitted a set number of failures before their additional transactions are dropped for a given block. This previously hard-coded limit of 3 is now configurable. Also, disable-subjective-account-billing accounts are no longer subjected to this limit.

Decay time: Users are prevented from abuse of transactions by tracking an account's subjective CPU budget. The budget is returned to an account over a period of time known as subjective account decay. This previously hard-coded decay of 24 hours is now configurable.

New configuration args for nodeos:

  • subjective-account-max-failures (defaults to 3)
    • "Sets the maximum amount of failures that are allowed for an account per block"
  • subjective-account-decay-time-minutes (defaults to 1440 (24 hours))
    • "Sets the time to return full subjective CPU for accounts"

New user-defined fields in GELF appender for Graylog

PRs

  • (mandel#305) Extend GELF appender to support user-defined fields
  • (mandel#330) Update fc to use default compression instead of best compression


The GELF appender now supports arbitrary fields and accompanying values in the logging.json configuration file, with some restrictions. Per the GELF specification, user-defined field names must begin with an underscore and contain only letters, numbers, underscores, dashes, and dots. The regular expression against which field names are checked is: ^_[\w\.\-]*$. Beyond the format check, there is also a list of reserved field names which are reserved by the specification or used by nodeos. The list of reserved field names is:

  • _id
  • _timestamp_ns
  • _log_id
  • _line
  • _file
  • _method_name
  • _thread_name
  • _task_name

There is no enforced limit on the length of the field name nor the accompanying value. However, by default, Graylog servers are configured to drop UDP GELF log messages which exceed 128 fragments. The GELF appender limits its payload size to 512 bytes, so field names and values with a combined length of somewhat less than 65536 bytes may result in lost log messages. The GELF protocol allows a maximum of 256 fragments, so a combined length exceeding 131072 bytes will always result in lost log messages. There is also no enforced limit regarding the number of user-defined fields beyond those limits described above.

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

New --terminate-at-block option in nodeos

PRs

  • (mandel#144) Add terminate-at-block option to nodeos


Nodeos can be configured to exit once it receives or replays the specified block number, allowing unattended progression to a desired state and enabling easy automation of pre-determined snapshots.

New configuration arg for nodeos:

  • --terminate-at-block (defaults to 0, meaning disabled)
    • "terminate after reaching this block number (if set to a non-zero number)"

This option is only accepted on the command line.

state_history_plugin (SHiP) fixes

PRs

  • (mandel#472) [3.1] Fix issue with current block not sent to SHiP clients
  • (mandel#505) [3.1] fix linking of c++ SHIP tests on boost versions prior to 1.69


A bug in SHiP that prevented sending the most recent block to clients has been fixed.

Deep-mind writing packed transactions instead of signed transactions for PUSH_CREATE

PRs

  • (mandel#654) [3.1] Use signed transaction for PUSH_CREATE action deep-mind logging


The deep-mind plug-in was writing the packed transactions into the dmlog on PUSH_CREATE, which is only appropriate for the MODIFY_CREATE action. An update was made to match the behavior of the version integrated with EOSIO v2.1, which writes signed transactions instead.

Reduce excessive logging of P2P handshake messages

PRs

  • (mandel#791) [3.1] Reduce net_plugin handshake messages in case of unavailable blocks


In testing, it was discovered that when a node's full block log was not available that net plugin would unnecessarily send a handshake message for each unavailable block requested. Instead, the node will now disconnect from the peer with benign_other and move on to a different peer to sync from. This mirrors the existing pattern for blk_send_branch when a block is not available.

Add missing file package to list of installable packages for pinned builds

PRs

  • (mandel#807) [3.1] Added file package to the list of installable packages


There was a minor omission in the installation scripts resulting in an error when file package was not listed as an installable package.

Building, compatibility, and upgrading

New build procedure

The shell scripts previously recommended for building the software have been removed in favor of a build process entirely driven by CMake. Those wishing to build from source are now responsible for installing the necessary dependencies. The list of dependencies and the recommended build procedure are in the README.md file. Instructions are also included for efficiently running the tests.

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

Activating protocol features

The instructions below walk through how to activate the protocol features introduced in the 3.0 and 3.1 releases on a new Antelope blockchain, e.g. a new local test blockchain. Step 3 does not include the other protocol features introduced in prior releases that you can also activate; simply add additional cleos calls to activate them by the appropriate digest in a suitable order.

If activating the new protocol features on an existing blockchain, you will likely be able to jump ahead to step 3.

  1. Activate special protocol feature: PREACTIVATE_FEATURE

All protocol features require a special protocol feature called PREACTIVATE_FEATURE. If this has not already been activated, then first activate it by running:

curl --request POST \
    --url http://<RPC_ENDPOINT_IP_PORT>/v1/producer/schedule_protocol_feature_activations \
    -d '{"protocol_features_to_activate": ["0ec7e080177b2c02b278d5088611686b49d739925a92d9bfcacd7fc6b74053bd"]}'
  1. Install eosio.boot system contract

Activating other protocol features requires a privileged contract to call the appropriate host function to pre-activate the protocol feature. If the contract deployed on the eosio account already has an activate action, you will likely be able to skip this step and just use that action in the next step.

If you do not have any contract deployed on the eosio account, as would be the case for a new blockchain, then you are recommended to deploy the system smart contract eosio.boot to the eosio account. To do this, run:

./cleos set contract eosio <EOS_SYSTEM_CONTRACTS_DIRECTORY>/contracts/eosio.boot/ eosio.boot.wasm eosio.boot.abi
  1. Activate remaining protocol features

Call the activate action on the contract deployed on the eosio account with a protocol feature's digest as an input to activate that protocol feature. Repeat this in the appropriate order for as many protocol features you wish to activate.

To get the a list of the digests of protocol features, run

curl -X POST http://<RPC_ENDPOINT_IP_PORT>/v1/producer/get_supported_protocol_features | jq .

and then look for feature_digest field for each protocol feature.

New protocol features introduced in versions 3.0 and 3.1 do not have dependencies on other protocol features or each other. You can use any order to activate them. For example:

# ACTION_RETURN_VALUE
./cleos push action eosio activate '["c3a6138c5061cf291310887c0b5c71fcaffeab90d5deb50d3b9e687cead45071"]' -p eosio

# CONFIGURABLE_WASM_LIMITS2
./cleos push action eosio activate '["d528b9f6e9693f45ed277af93474fd473ce7d831dae2180cca35d907bd10cb40"]' -p eosio

# BLOCKCHAIN_PARAMETERS
./cleos push action eosio activate '["5443fcf88330c586bc0e5f3dee10e7f63c76c00249c87fe4fbf7f38c082006b4"]' -p eosio

# GET_CODE_HASH
./cleos push action eosio activate '["bcd2a26394b36614fd4894241d3c451ab0f6fd110958c3423073621a70826e99"]' -p eosio

# CRYPTO_PRIMITIVES
./cleos push action eosio activate '["6bcb40a24e49c26d0a60513b6aeb8551d264e4717f306b81a37a5afb3b47cedc"]' -p eosio

# GET_BLOCK_NUM
./cleos push action eosio activate '["35c2186cc36f7bb4aeaf4487b36e57039ccf45a9136aa856a5d569ecca55ef2b"]' -p eosio

Snapshot compatibility

This release introduces a new snapshot format. It can still load older snapshot versions. Snapshot versions and compatibility is as follows:

  • v6 is the snapshot format introduced in this release (3.1). It is only compatible with nodeos version 3.1.
  • v5 is a snapshot format from the unsupported EOSIO 2.1 release. Because v5 snapshots can be generated by unsupported software that may have incompatible protocol features activated, it may not generally be possible to load a v5 snapshot into a version 3.1 release of nodeos. However, if the v5 snapshot is of the state of a blockchain that has not activated any protocol features introduced in EOSIO 2.1, then the snapshot can be loaded in nodeos version 3.1.
  • v4 is a snapshot format generated by nodeos version 2.0. It is compatible with nodeos version 3.1.

Network compatibility

Network compatibility means it can accept blocks and transactions over the p2p connection between nodes and will respond to requests for blocks.

This release is network compatible with nodeos version 2.0.

This release may also be network compatible with EOSIO 2.1 assuming the blockchain has not activated any protocol features specific to EOSIO 2.1.

state_history_plugin (SHiP) compatibility

This release is compatible with SHiP logs generated by nodeos version 2.0, but is NOT compatibile with SHiP logs that were written to by EOSIO 2.1.

To accommodate 3.1's new features, changes to the state history ABI were required. Consumers of state history from a 3.1 nodeos 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. Remember that your client must be prepared to receive either the v0 or v1 variation since entries in your state history log prior to upgrading to 3.1 will continue to be sent to your client as v0 versions.

These new versions are listed here for convenience but the authoritative definition is the ABI sent over state history's WebSocket upon connection.

action_trace_v1 & chain_config_v1
    {
      "name": "action_trace_v1",
      "fields": [
        {
          "name": "action_ordinal",
          "type": "varuint32"
        },
        {
          "name": "creator_action_ordinal",
          "type": "varuint32"
        },
        {
          "name": "receipt",
          "type": "action_receipt?"
        },
        {
          "name": "receiver",
          "type": "name"
        },
        {
          "name": "act",
          "type": "action"
        },
        {
          "name": "context_free",
          "type": "bool"
        },
        {
          "name": "elapsed",
          "type": "int64"
        },
        {
          "name": "console",
          "type": "string"
        },
        {
          "name": "account_ram_deltas",
          "type": "account_delta[]"
        },
        {
          "name": "except",
          "type": "string?"
        },
        {
          "name": "error_code",
          "type": "uint64?"
        },
        {
          "name": "return_value",
          "type": "bytes"
        }
      ]
    },

  {
    "name": "chain_config_v1",
    "fields": [
      {
        "type": "uint64",
        "name": "max_block_net_usage"
      },
      {
        "type": "uint32",
        "name": "target_block_net_usage_pct"
      },
      {
        "type": "uint32",
        "name": "max_transaction_net_usage"
      },
      {
        "type": "uint32",
        "name": "base_per_transaction_net_usage"
      },
      {
        "type": "uint32",
        "name": "net_usage_leeway"
      },
      {
        "type": "uint32",
        "name": "context_free_discount_net_usage_num"
      },
      {
        "type": "uint32",
        "name": "context_free_discount_net_usage_den"
      },
      {
        "type": "uint32",
        "name": "max_block_cpu_usage"
      },
      {
        "type": "uint32",
        "name": "target_block_cpu_usage_pct"
      },
      {
        "type": "uint32",
        "name": "max_transaction_cpu_usage"
      },
      {
        "type": "uint32",
        "name": "min_transaction_cpu_usage"
      },
      {
        "type": "uint32",
        "name": "max_transaction_lifetime"
      },
      {
        "type": "uint32",
        "name": "deferred_trx_expiration_window"
      },
      {
        "type": "uint32",
        "name": "max_transaction_delay"
      },
      {
        "type": "uint32",
        "name": "max_inline_action_size"
      },
      {
        "type": "uint16",
        "name": "max_inline_action_depth"
      },
      {
        "type": "uint16",
        "name": "max_authority_depth"
      },
      {
        "type": "uint32",
        "name": "max_action_return_value_size"
      }
    ]
  }


Additionally, global_property_v1 has a new binary extension with the wasm_config type, implemented with wasm_config_v0

global_property_v1 & wasm_config_v0
  "name": "global_property_v1",
  "fields": [
    {
      "type": "uint32?",
      "name": "proposed_schedule_block_num"
    },
    {
      "type": "producer_authority_schedule",
      "name": "proposed_schedule"
    },
    {
      "type": "chain_config",
      "name": "configuration"
    },
    {
      "type": "checksum256",
      "name": "chain_id"
    },
    {
      "type": "wasm_config$",
      "name": "wasm_configuration"
    }
  ]
},

"name": "wasm_config_v0",
"fields": [
  {
    "type": "uint32",
    "name": "max_mutable_global_bytes"
  },
  {
    "type": "uint32",
    "name": "max_table_elements"
  },
  {
    "type": "uint32",
    "name": "max_section_elements"
  },
  {
    "type": "uint32",
    "name": "max_linear_memory_init"
  },
  {
    "type": "uint32",
    "name": "max_func_local_bytes"
  },
  {
    "type": "uint32",
    "name": "max_nested_structures"
  },
  {
    "type": "uint32",
    "name": "max_symbol_bytes"
  },
  {
    "type": "uint32",
    "name": "max_module_bytes"
  },
  {
    "type": "uint32",
    "name": "max_code_bytes"
  },
  {
    "type": "uint32",
    "name": "max_pages"
  },
  {
    "type": "uint32",
    "name": "max_call_depth"
  }
]


State file compatibility

This release is not compatible with the state files generated by earlier release. Please use a compatible snapshot file generated from an earlier version of nodeos.

Block log compatibility

This release is compatible with block logs generated by nodeos version 2.0.

This release is NOT compatible with block logs generated by EOSIO 2.1.

Upgrading from prior releases

Generate a snapshot of the state from an earlier version of nodeos (e.g. 2.0). See snapshot compatibility section for other snapshot formats that can be used.

Remove the state file used by the node you are upgrading. If using EOSIO 2.1, you will also need to remove the SHiP and blocks logs. But SHiP and block logs can remain if upgrading from nodeos version 2.0.

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

Deprecations, removals, and dropped support

Deprecations

ABI conversion APIs 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.

Removals

Build scripts removed

As mentioned earlier, the build scripts were removed. See README.md for instructions to build.

history_plugin removed

The history_plugin was deprecated as part of the v1.2.0 release and is fully removed as of this release.

Nodes which were being started with --plugin eosio::history_plugin will need to be migrated to --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 v1.8.0 release and is fully removed as of this release.

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 continue to still be stored in the fork databasae on shutdown.

Note: Any existing configuration for the reversible block Chainbase database should be removed from the config.ini file and any scripts.

reversible-blocks-db-size-mb, reversible-blocks-db-guard-size-mb, fix-reversible-blocks, import-reversible-blocks, and export-reversible-blocks

Dropped support

Ubuntu 16.04, Centos, and macOS

As mentioned earlier, the only officially supported platforms are Ubuntu 18.04, 20.04 and 22.04. All others have been removed from binary package support and/or code level changes.

Developers using cleos, nodeos, etc. should look at DUNE which supports Windows 10 and 11, macOS, and any Linux that supports Docker.

Further details on changes since last release

Contributors

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

Full list of changes since last release

PRs

Refer to full list of changes from the following prior releases:

In addition, this release also includes the following PRs:

  • (28) [3.1] [CI] adjustments to CICD now that repo is public
  • (41) [3.1] [CI] tweak name of dev package artifiact for consistency
  • (36) [3.1] explictly reference llvm11 in README's build documentation cmake command
  • (43) [3.1] bump version to 3.1.0


Full Changelog: 9bcfe22...v3.1.0