> ## Documentation Index > Fetch the complete documentation index at: https://developers.stellar.org/llms.txt > Use this file to discover all available pages before exploring further. # Soroban Settings > Soroban has a large collection of settings stored on-ledger that can be modified through a validator vote. 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](https://developers.stellar.org/docs/validators/admin-guide/commands.md) 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](https://developers.stellar.org/docs/validators/admin-guide/network-upgrades.md#upgrading-soroban-settings) for more information on how the settings upgrade mechanism works internally. > [!NOTE] > > If you are being asked to vote for an upgrade, please move on to the [Examine a Proposed Upgrade](#examine-a-proposed-upgrade) section for details on how to accomplish that. ### Frozen ledger keys [CAP-77](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0077.md) has been introduced in protocol 26 to allow validators to make certain ledger keys "frozen", meaning that they will not be accessible for reading or writing. This is a mechanism that can be used to quarantine corrupted data in case of data corruption bugs, or remove access to stolen funds in case of security incidents. Freezing/unfreezing the keys follows the standard upgrade procedure described below. The only caveat is that the upgrade JSON must contain hex-encoded `LedgerKey` XDR in the sets of keys to freeze and/or unfreeze, for example: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "updated_entry": [ { "frozen_ledger_keys_delta": { "keys_to_freeze": [ "000000000000000000000000000000000000000000000000000000000000000000000000" ], "keys_to_unfreeze": [ "000000000000000000000000000000000000000000000000000000000000000000000001" ] } } ] } ``` Since most tools encode XDR as base64, you can use a helper script in the [stellar-core repository](https://github.com/stellar/stellar-core/blob/master/scripts/frozen_keys_base64_to_hex.py). ## Helper Script A script to help you create the transactions below is available [in the stellar-core GitHub repo](https://github.com/stellar/stellar-core/blob/master/scripts/settings-helper.sh), with usage details [also available](https://github.com/stellar/stellar-core/blob/master/scripts/README.md). We've saved the information below for now, because it's important to be aware of how the underlying process to generate the transactions works in case the script has some issues. ### 1. Create an Upgrade Set The `stellar` CLI 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 `ConfigUpgradeSet`. You can use the [`pubnet_phase1.json`] and [`pubnet_phase2.json`] files as a starting point to formulate your upgrade proposal. You can also pull directly from a running core node using `http-command 'sorobaninfo?format=upgrade_xdr' | stellar-xdr decode --type ConfigUpgradeSet --output json-formatted`. This will allow you to get the exact settings running on that core node in JSON format, making it easier to change only the value you want to. Once you have your JSON file with updated values, use the following command to create the required upgrade set XDR: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} stellar xdr encode --type ConfigUpgradeSet path/to/upgrade.json ``` The output of the phase 2 JSON file, for example, would look like: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} AAAAAgAAAAEAAAAAHc1lAAAAAAAF9eEAAAAAAAAAABkCgAAAAAAAAgAAAMgAB6EgAAAAfQABEXAAAAAoAAIIAAAAABkAAQQAAAAAAAAAGGoAAAAAAAAnEAAAAAAAAAb6AAAAAukO3QD///////0NfwAAAAAAAOFfAAAD6A== ``` > [!NOTE] > > `stellar` CLI can be installed using brew or cargo: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > brew install stellar-cli > # OR > cargo install --locked stellar-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. Restore the Wasm entry from the next step (if it exists). 2. Upload a simple smart contract's Wasm bytecode to the network that allows for `Temporary` ledger entries to be created, keyed using `Bytes` `SCVal`s. 3. Create's a contract instance from the previously uploaded Wasm bytecode. 4. 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](#1-create-an-upgrade-set). * `--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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg get-settings-upgrade-txs \ GAUQW73V52I2WLIPKCKYXZBHIYFTECS7UPSG4OSVUHNDXEZJJWFXZG56 \ 73014444032 \ "Public Global Stellar Network ; September 2015" \ --xdr AAAAAgAAAAE... \ --signtxs ``` This command's output will include three sets of `TransactionEnvelope`s and corresponding transaction `Hash`es, followed by a base64-encoded `ConfigUpgradeSetKey` XDR string: ```bash showLineNumbers theme={"theme":{"light":"github-light","dark":"github-dark"}} # restore Wasm `TransactionEnvelope` (truncated here) AAAAAgAAAABSvbro8P/XAQP+eTvW1TnB4+r4vZx5fKj+DsWuWN3gjQX14QAAA...LgymJ36XIBrUVMU2wg= # restore Wasm transaction `Hash` 3a2457d3fc081ab3a72dfe7ee2236f3a282c62f21d7e3dbdb5b13ac0d09c8647 # upload Wasm `TransactionEnvelope` (truncated here) AAAAAgAAAABi/B0L0JGythwN1lY0aypo19NHxvLCyO5tBEc...wF9wL68IAAAAdkJxSgpyRStTvbSA9jgs= # upload Wasm 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 four transactions can then be submitted to the network through your node. Replace the blob placeholders below with the `TransactionEnvelope`s in lines 1, 3, 5, and 7. > [!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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} http-command 'tx?blob=' http-command 'tx?blob=' http-command 'tx?blob=' http-command 'tx?blob=' ``` ### 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 9 above: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} http-command 'dumpproposedsettings?blob=' ``` ### 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 9 above and an agreed upon time in the future: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} http-command 'upgrades?mode=set&upgradetime=YYYY-MM-DDTHH:MM:SSZ&configupgradesetkey=' ``` ### 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]. ### Debugging Once the four transactions are run, you should see the proposed upgrade when running the `dumpproposedsettings` command ([see step 4 above](#4-verify-proposed-upgrades)). 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 Lab](https://lab.stellar.org) 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](https://github.com/stellar/stellar-core/blob/3007c595c2fe9b53502aa0daf8089d119a9c37cb/src/herder/Upgrades.cpp#L1451). ## 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} http-command 'dumpproposedsettings?blob=A6MvjFLujnqaZa5hacafWyYwhpk4cgRpyu0z6ilZ0pm1S7fmjSNnsyjGwGodLGiD8ss8S1AHiOBBb6GQbOeMbw==' ``` ## Examine Current Settings You can also get the current Soroban settings to compare against by using stellar-core's `sorobaninfo`. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} http-command 'sorobaninfo?format=detailed' ``` [`pubnet_phase1.json`]: https://github.com/stellar/stellar-core/blob/master/soroban-settings/pubnet_phase1.json [`pubnet_phase2.json`]: https://github.com/stellar/stellar-core/blob/master/soroban-settings/pubnet_phase2.json [precompiled binary]: https://github.com/stellar/stellar-cli/releases/latest [protocol history page]: https://stellar.expert/explorer/pubnet/protocol-history [stellar.expert]: https://stellar.expert [this repository]: https://github.com/stellar-expert/staged-soroban-upgrades [`settingsupgradeutils.cpp`]: https://github.com/stellar/stellar-core/blob/master/src/main/SettingsUpgradeUtils.cpp