Skip to main content

Soroban Settings

Soroban has a large collection of settings stored on-ledger that can be modified through a validator vote. Here you can find out how to propose a new settings upgrade as well as how to examine a proposed upgrade. You can also look at the Commands page for more details on the stellar-core commands used below.

Propose a Settings Upgrade​

This section will describe how to propose a settings upgrade, but take a look at the Upgrading the Network page for more information on how the settings upgrade mechanism works internally.

info

If you are being asked to vote for an upgrade, please move on to the Examine a Proposed Upgrade section for details on how to accomplish that.

1. Create an Upgrade Set​

The stellar-xdr rust tool allows for the use of a JSON input file to encode a collection of Soroban settings into an base64-encoded string representing the XDR type ConfiguUpgradeSet. You can use the pubnet_phase1.json and pubnet_phase2.json files as a starting point to formulate your upgrade proposal. Use the following command to create the required upgrade set XDR:

stellar-xdr encode --type ConfigUpgradeSet path/to/upgrade.json

The output of the phase 2 JSON file, for example, would look like:

AAAAAgAAAAEAAAAAHc1lAAAAAAAF9eEAAAAAAAAAABkCgAAAAAAAAgAAAMgAB6EgAAAAfQABEXAAAAAoAAIIAAAAABkAAQQAAAAAAAAAGGoAAAAAAAAnEAAAAAAAAAb6AAAAAukO3QD///////0NfwAAAAAAAOFfAAAD6A==
info

stellar-xdr can be installed using brew or cargo:

brew install stellar/tap/stellar-xdr
# OR
cargo install --locked stellar-xdr --features cli

You can also download a precompiled binary of the latest release for your system from GitHub.

2. Generate Settings Upgrade Transactions​

You can use stellar-core's get-settings-upgrade-txs command to create a series of transactions that will:

  1. Upload a simple smart contract's Wasm bytecode to the network that allows for Temporary ledger entries to be created, keyed using Bytes SCVals.
  2. Create's a contract instance from the previously uploaded Wasm bytecode.
  3. Invoke the newly created contract instance's write function with your (validated) base64-encoded upgrade set.

You're required to provide four arguments for this command:

  • PUBLIC_KEY: (positional) the public key that will be the source for these transactions. Note that you will be submitting transactions, so the account for the public key specified must exist and have the funds to pay the transaction fees.
  • SEQUENCE_NUMBER: (positional) the current sequence number for the specified public key.
  • NETWORK_PASSPHRASE: (positional) the network passphrase for the network these transactions will be submitted to.
  • --xdr AAAA...: the base64-encoded upgrade set generated in step 1.
  • --signtxs: (optional) if provided, this command will prompt you for a secret key and will return signed transactions that can be submitted to the network right away.

For example, the command for the phase 2 upgrade might have looked like this:

stellar-core get-settings-upgrade-txs \
    GAUQW73V52I2WLIPKCKYXZBHIYFTECS7UPSG4OSVUHNDXEZJJWFXZG56 \
    73014444032 \
    "Public Global Stellar Network ; September 2015" \
    --xdr AAAAAgAAAAE... \
    --signtxs

This command's output will include three sets of TransactionEnvelopes and corresponding transaction Hashes, followed by a base64-encoded ConfigUpgradeSetKey XDR string:

# upload bytecode `TransactionEnvelope` (truncated here)
AAAAAgAAAABi/B0L0JGythwN1lY0aypo19NHxvLCyO5tBEc...wF9wL68IAAAAdkJxSgpyRStTvbSA9jgs=
# upload bytecode transaction `Hash`
19c49f18e5442db9d626f7485c34ecb0cd938034255515099b37acebdb6677a7
# create contract instance `TransactionEnvelope` (truncated here)
AAAAAgAAAABi/B0L0JGythwN1lY0aypo19NHxvLCyO5tBEc...AAd0OB3n3Yadews=
# create contract instance transaction `hash`
9e70cbff631247638fae96b9d996d8d22b6fa75208380d5f5d714a57c0a90947
# invoke contract `TransactionEnvelope` (truncated here)
AAAAAgAAAABi/B0L0JGythwN1lY0aypo19NHxvLCyO5tBEc...F9wX14QAAAAARAAAAAwAAAAAAAAAAAAAAAQAAAAAAAAAYAAAAAAAAAAGd/IhWQcE2UdzIof7ygqCuAmYD8ycsJbB
# invoke contract transaction `Hash`
4f6457d3fc081ab3a72dfe7ee2236f3a282c62f21d7e3dbdb5b13ac0d09c8647
# base64-encoded `ConfigUpgradeSetKey`
nfyIVkHBNlHcyKH+8oKgrgJmA/MnLCW3E4Fhg4XYTkqZa2MyqzRdB2+mN3DOKUFKtZIAXp6o3DHrkgR0mo7rUw==

3. Submit Settings Upgrade Transactions​

These three transactions can then be submitted to the network through your node. Replace the blob placeholders below with the TransactionEnvelopes in lines 2, 6, and 10.

note

If you didn't provide the --signtxs parameter to the get-settings-upgrade-txs command, don't forget to sign them before submitting to the network.

curl -G 'http://localhost:11626/tx' --data-urlencode 'blob=<LINE_2_OUTPUT>'
curl -G 'http://localhost:11626/tx' --data-urlencode 'blob=<LINE_6_OUTPUT>'
curl -G 'http://localhost:11626/tx' --data-urlencode 'blob=<LINE_10_OUTPUT>'

4. Verify Proposed Upgrades​

You can verify that the proposed upgrades have been set up using stellar-core's dumpproposedsettings command, providing the ConfigUpgradeSetKey XDR string from line 14 above:

curl -G 'http://localhost:11626/dumpproposedsettings' --data-urlencode 'blob=<LINE_14_OUTPUT>'

5. Schedule the Upgrades​

Now you can schedule the upgrade on all the required validators using stellar-core's upgrades command, providing the ConfigUpgradeSetKey output from line 14 above and an agreed upon time in the future:

curl -G 'http://localhost:11626/upgrades?mode=set&upgradetime=YYYY-MM-DDTHH:MM:SSZ' --data-urlencode 'configupgradesetkey=<LINE_14_OUTPUT>'

6. Update Stellar Expert​

One of the most-used methods of "watching" an upgrade take place for the network's Soroban settings is the Protocol History page on stellar.expert.

In order to make sure that page gets updated with the proposed upgrades, please fill out a PR against this repository.

Helper Script​

A script to help you create the transactions above is available in the stellar-core GitHub repo, with usage details also available. We've saved this information for now, because it's important to be aware of how the underlying process works in case the script has some issues.

Debugging​

Once the three transactions are run, you should see the proposed upgrade when running the dumpproposedsettings command (see step 4 above). If you don't, then either one or more of the transactions above failed during application, or the upgrade is invalid.

If any of the transactions above fail during submission, you should get a TransactionResult as a response along with the reason for the failure. The failure will most likely be due to one of the following reasons:

  • Resources are too low. You'll need to increase the hardcoded resources in SettingsUpgradeUtils.cpp.
  • Fee or refundable fee is too low. You'll need to increase them in SettingsUpgradeUtils.cpp.
  • Wasm has expired. You'll need to restore the Wasm.

You should confirm what caused the failure by looking at the TransactionResult of the failed transaction using the Stellar Laboratory or a block explorer.

If the transactions succeeded but the dumpproposedsettings command still returns an error, then the upgrade is invalid. The error reporting here needs to be improved, but the validity checks happen here.

Examine a Proposed Upgrade​

You can use stellar-core's dumpproposedsettings command along with a base64-encoded ConfigUpgradeSetKey XDR string to query a proposed upgrade:

curl -G 'http://localhost:11626/dumpproposedsettings' --data-urlencode 'blob=A6MvjFLujnqaZa5hacafWyYwhpk4cgRpyu0z6ilZ0pm1S7fmjSNnsyjGwGodLGiD8ss8S1AHiOBBb6GQbOeMbw=='

Examine Current Settings​

You can also get the current Soroban settings to compare against by using stellar-core's sorobaninfo.

curl -G 'http://localhost:11626/sorobaninfo' --data-urlencode 'format=detailed'