WAX sw/eden

WAX Testnet Antelope upgrade

The following text describes what node operators needs to do to upgrade their nodes before antelope is activated on the WAX testnet.

All node operators should have updated their testnet nodes before December 21st, 2022 11:00 UTC as after this time, The WAX Testnet will start the upgrade to Antelope. You should also begin to upgrade your Mainnet nodes as that will soon follow, more on that later. 

Note that the upgrade is delayed to ensure we sync everything.

Outline

1) Planning for upgrade
2) Prepare Nodes for the upgrade
3) Features and Tools in the Antelope Upgrade
4) Onchain changes for Antelope features

TLDR: If you run wax 2.0, upgrade to antelope and start from a snapshot.

1. Planning for upgrade

1.1 Plugins

These changes to plugins have been made:
  • eosio::history_plugin is completely removed.
  • mongo_db_plugin is completely removed.

Nodes that use these plugins must adapt their solutions prior to activation, ideally immediately.
Operators can migrate their solutions to services like Hyperion, Chronicle or dfuse.
eosio::trace_api_plugin and eosio::state_history_plugin can be used to index data to those solutions.

1.2 Upgrade from WAX 2.0

wax-leap 3.1 is based on WAX 2.0, so upgrading nodes from WAX 2.0 is straightforward.
You should use a snapshot when upgrading in that case.

1.3 Incase you run WAX 2.1 - Upgrade path

  1. wax 2.1 used state history plugin (SHiP) files and blocks.log files that are incompatible with 3.1. SHiP files from 2.1 are always incompatible with 3.1. However, blocks.log files may be compatible if the node upgraded from an earlier version of wax.
  2. 2.1 Nodes that don’t keep a blocks.log file or state history are the easiest to upgrade.
  3. For 2.1 nodes that keep a blocks.log file but do not keep state history, the version of the blocks.log file is important. If your blocks.log was created before wax 2.1, the blocks.log file is compatible with 3.1 and you can start from a snapshot without removing existing logs.

    If your block log was created on 2.1. It may or may not be compatible. An incompatible blocks.log file needs to be removed. To determine if your blocks.log file is compatible, use the following command with your node:

    apt-get install bsdmainutils
    hexdump <nodeos data directory>/blocks/blocks.log | head

    (The <nodeosdatadirectory> will be the data directory where nodeos stores blockchain data, for example, “.local/share/eosio/nodeos/data”)

    The second number in the output (top row, second column from the left) corresponds with the blocks.log version. 0001, 0002, or 0003 is ok. 0004 is from WAX 2.1, and is not compatible.

    0000000 0003 8000 6a7f 017e e473 5a38 0827 d7e6
    0000010 8804 fb34 07c1 2f9f b1ab 3c7b 5b12 6a14

    The output continues. Other than the bolded section, the content will be different.
  4. If you need to keep state history, you need to either replay your block log or resync from the network. Replay is faster, as it saves network overhead.
    • You can replay your blocks log if you have a compatible version of blocks.log. See (2) above.
      NOTE: A replay can take weeks.
    • If your blocks log is not compatible, you need to resync from another node on the network. You can synchronize from either 2.0 or 2.1, and a resync creates a compatible blocks.log file.
      NOTE: Resync can take weeks. When resyncing, blocks.log and state history are created together.

Figure 1, Table of steps the nodes running 2.1 must take depending on their configuration (cells highlighted in yellow and red represent steps that can take weeks to complete)


2. Preparing your node for upgrade


2.1 Getting the binary

Debian packages can be downloaded from Sw/eden APT
user who wish to build from source can follow this guide

2.2 Getting a snapshot (if you need one)

2.2.1 Generating one yourself

If you are running wax 2.0 (but not wax 2.1), you can generate a snapshot from within a local node by using the command:

curl -X POST http://127.0.0.1:8888/v1/producer/create_snapshot

To perform a snapshot, nodes must be started with the configuration option: plugin = eosio::producer_api_plugin
Make sure your node is not exposed to the public when enabling the producer_api_plugin as it is only for administrators.

2.2.2 Download

You can also download snapshots from a trusted guild.
Be aware that there is no way for a node to verify the integrity of these snapshots.

2.3 Config changes

Several configuration options have changed. Nodeos will fail to start if invalid configuration options are present.

2.3.1 Reversible block database settings

These config settings needs to be removed:

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

2.3.2 wax 2.1 Block log splitting

The Block log splitting feature from 2.1 has been removed and changed to log block rotation.
Remove the following parameters:

  • blocks-log-stride
  • max-retained-block-files
  • blocks-archive-dir

2.4 Remove old blocklogs/state history

Any nodes currently running wax 2.1 should remove the state history.
From the data directory, delete files from the /state-history directory using:

cd <nodeos data directory>
rm state-history/*

Any nodes that have block log version 0004 from 2.1 should remove Block logs from the data directory, delete files from the /blocks directory using:

cd <nodeos data directory>
rm blocks/*
rm blocks/reversible/*

2.5 Start your node.

pass --snapshot <path/to/snapshot> flag if you are starting from snapshot. otherwise start your node as usual.

3. Features and tools to be aware of

3.1 wax-leap v3.1 introduces the following new transaction lifecycle tools:


Transaction Retry

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.

This 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

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.

This 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

On the blockchain, the active guild determines the cost of a transaction at execution time. The guild determines CPU cost by measuring the CPU time used to execute the non-signature portion of the transaction. The variance in the guild’s CPU performance makes it difficult to determine actual resource costs before sending a transaction.

This 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

The WAX-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 the WAX chain only charge accounts when a guild 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:

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.

Transaction failure tracing with a new transaction endpoint:

The 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.

3.2 Additional wax-leap upgrades that are not focused on transaction lifecycle include:

  • Improved compatibility with the GELF appender logging protocol
  • New build procedures
  • A new snapshot format
  • Block and SHiP pruning feature
  • Option to terminate a node at a particular block

See the Changelog for more in-depth information.

3.3 WAX CDT

The Contract Development Toolkit (CDT) has been upgraded, and anyone using this tool should be aware of some minor naming changes

  • CDT 3.0 changes the names of its binaries to replace “eosio” prefixes with “cdt” instead, as in `cdt-cpp` instead of `eosio-cpp`.
  • For CMake projects, use find_package(cdt) instead of find_package(eosio.cdt).

4. Onchain Contract Upgrades

The below parameters are for upgrading any eosio chain to antelope.

4.1 Update System Contract

Compile version v3.1.1 contract: https://github.com/eosnetworkfoundation/eos-system-contracts/releases/tag/v3.1.1
before deploying the contract. we need to enable CONFIGURABLE_WASM_LIMITS2,BLOCKCHAIN_PARAMETERS and WTMSIG_BLOCK_SIGNATURES:

# BLOCKCHAIN_PARAMETERS
./cleos push action eosio activate '["5443fcf88330c586bc0e5f3dee10e7f63c76c00249c87fe4fbf7f38c082006b4"]' -p eosio 
# CONFIGURABLE_WASM_LIMITS2
./cleos push action eosio activate '["d528b9f6e9693f45ed277af93474fd473ce7d831dae2180cca35d907bd10cb40"]' -p eosio
# WTMSIG_BLOCK_SIGNATURES
./cleos push action eosio activate '["299dcb6af692324b899b39f16d5a530a33062804e41f09dc97e9f156b4476707"]' -p eosio

After those have been enabled you can deploy the contract.

4.2 Activate the rest of the 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.

Features that needs to be activated

CONFIGURABLE_WASM_LIMITS2

Allows operators to increase limits on WASM files.

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

CRYPTO_PRIMITIVES

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

GET_BLOCK_NUM

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

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

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.

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

ACTION_RETURN_VALUE

Enables new set_action_return_value intrinsic which sets a value that is included in action_receipt.
Allows actions to return values in the action trace.

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

WEBAUTHN_KEY

Enables usage of WebAuthn keys and signatures.

./cleos push action eosio activate '["4fca8bd82bbd181e714e283f83e1b45d95ca5af40fb89ad3977b653c448f78c2"]' -p eosio

4.3. Additional notes usefull for starting new networks (NOT needed for wax testnet)

System Contracts v3.1 needs a special boot contract too bootstrap the chain before the real system contract can be deployed.

This is needed because v3.1 system contract needs CONFIGURABLE_WASM_LIMITS2 and BLOCKCHAIN_PARAMETERS to function. And those are not enabled on a new chain. The boot contract can be used in that case to just enable those features before deploying the real contract.
Steps to bootstrap a new blockchain:

  1. Activeate PREACTIVATE_FEATURE (can be done without a system contract)
  2. Deploy the boot contract
  3. Activate CONFIGURABLE_WASM_LIMITS2 and BLOCKCHAIN_PARAMETERS using the boot contract.
  4. Deploy the actual system contract.

5. References

Information has been taken and modified from the following sources.

6. Acknowledgement

Thanks to EOSNetwork for developing leap and providing the initial documentation for upgrading to leap 3.1

Leave a Comment:

1 comment
Dan says October 18, 2022

Instead of installing the bsdmainutils package for hexdump – most systems probably already have the venerable ‘od’ utility installed. You might want to just try the command ‘od -x /blocks/blocks.log | head -1’ before installing that.

Reply
Add Your Reply