Skip to main content

Upgrading the Network

The network itself has network wide settings that can be updated.

This is performed by validators voting for and agreeing to new values the same way that consensus is reached for transaction sets, etc.

A node can be configured to vote for upgrades using the upgrades endpoint . See Commands for more information.

The network settings are:

  • the version of the protocol used to process transactions;
  • the maximum number of transactions that can be included in a given ledger close. Separate setting for Soroban and classic transactions;
  • the cost (fee) associated with processing operations;
  • the base reserve used to calculate the lumen balance needed to store non-Soroban data in the ledger; and
  • generalized Soroban network settings stored in ConfigSettingsEntries.

When the network time is later than the upgradetime specified in the upgrades command, the validator will vote to update the network to the value specified in that upgrades command. If the network time is passed the upgradetime by more than 12 hours, the upgrade will be ignored.

When a validator is armed to change network values, the output of info will contain information about the vote.

For a new value to be adopted, the same level of consensus between nodes needs to be reached as for transaction sets.

Important Notes on Network Wide Settings​

Changes to network wide settings have to be orchestrated properly between validators as well as non validating nodes. The general process validators have used to propose and vote on network settings is as follows:

  1. A change is vetted between operators (changes can be bundled).
  2. An effective date in the future is picked for the change to take effect (controlled by the upgradetime parameter of the upgrades command).
  3. If applicable, communication is sent out to all network users.

This careful orchestration plays an important part in the Stellar network's functioning. This planning process is undertaken to avoid nodes misbehaving, socialize new features included in a protocol upgrade so the ecosystem is aware and can take advantage of them, and it also gives the ecosystem time to ready themselves for breaking changes that can have an effect (either directly or indirectly) on their Stellar integrations. An improper plan may cause issues such as:

  • nodes missing consensus (aka "getting stuck"), and having to use history to rejoin
  • network reconfiguration taking effect at a non deterministic time (causing fees to change ahead of schedule for example)

For more information, take a look at how versioning takes into account network upgrades in the versioning.md document in the stellar-core GitHub repository.

Upgrading Soroban Settings​

The mechanism to update Soroban settings is more complex than updating something like the baseReserve. The upgrades endpoint in stellar-core will require validators to vote on a serialized ConfigUpgradeSetKey, which contains a contractID and the SHA-256 hash of the ConfigUpgradeSet that will be applied to the existing settings. The serialized ConfigUpgradeSet must exist in the ledger as Temporary ContractData under the contractID specified earlier and with the SCVal Bytes key that contains the SHA-256 hash of the ConfigUpgradeSet.

This means that someone wishing to propose a setting upgrade will need to create a smart contract that writes the ConfigUpgradeSet bytes into ContractData (remember, a Temporary entry is required), invoke it to write the upgrade xdr, and then share the serialized ConfigUpgradeSetKey to vote on.

We have much more detail on the next page about how to craft an upgrade proposal for these settings. Be sure to read and understand that.

Example Upgrade Command​

By way of example, here is the upgrades command used to upgrade the protocol version to version 9 on January-31-2018.

# arm the node to vote for the upgrade
stellar-core http-command 'upgrades?mode=set&upgradetime=2018-01-31T20:00:00Z&protocolversion=9'
# view the status of the node
stellar-core http-command info

At this point info will tell you that the node is setup to vote for this upgrade:

"status" : [
  "Armed with network upgrades: upgradetime=2018-01-31T20:00:00Z, protocolversion=9"
]