Merge pull request #4235 from sisuresh/settings

Soroban Settings Docs

Reviewed-by: dmkozh

Author: latobarita

docs/software/soroban-settings.md

@@ -46,7 +46,22 @@ proposed upgrade.**
     1. `curl -G 'http://localhost:11626/dumpproposedsettings' --data-urlencode 'blob=<LINE_7_OUTPUT>'`
 5. Now schedule the upgrade on all the required validators using the output from line 7 (the `ConfigUpgradeSetKey`) and an agreed upon time in the future
     1. `curl -G 'http://localhost:11626/upgrades?mode=set&upgradetime=YYYY-MM-DDTHH:MM:SSZ' --data-urlencode 'configupgradesetkey=<LINE_7_OUTPUT>'`
+6. Update https://github.com/stellar-expert/staged-soroban-upgrades so https://stellar.expert/explorer/pubnet/protocol-history will show the proposed upgrade.
 
+### Helper script
+A script to help with crafting the transactions above is available [here](../../scripts/settings-helper.sh) with usage details in [README.md](../../scripts/README.md), but it's important to be aware of how the underlying process works in case the script has some issues.
+
+### Debugging
+If any of the transactions above fail during transaction submission, you should get a `TransactionResult` as a response with the reason.
+
+Once the three transactions are run, you should see the proposed upgrade when running the `dumpproposedsettings` command [(step 4)](#propose-a-settings-upgrade). 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 transaction application, the failure will most likely be due to one of the following, and you should confirm this by looking at the `TransactionResult` of the failed transaction using the Stellar Laboratory or an explorer - 
+1. Resources are too low. You'll need to increase the hardcoded resources in [SettingsUpgradeUtils.cpp](../../src/main/SettingsUpgradeUtils.cpp).
+2. Fee or refundable fee is too low. You'll need to increase them in [SettingsUpgradeUtils.cpp](../../src/main/SettingsUpgradeUtils.cpp).
+3. Wasm has expired. You'll need to restore the Wasm.
+
+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](../../src/herder/Upgrades.cpp).
 
 ## Examine a proposed upgrade
 

scripts/README.md

@@ -4,6 +4,7 @@ This folder is for storing any scripts that may be helpful for using stellar-cor
 ## List of scripts
 - [Overlay survey](#overlay-survey)
 - [Diff Tracy CSV](#diff-tracy-csv)
+- [Parse Backtrace Dump](#parse-backtrace-dump)
 
 ### Overlay survey 
 - Name - `OverlaySurvey.py`
@@ -54,5 +55,14 @@ This folder is for storing any scripts that may be helpful for using stellar-cor
 ./src/stellar-core(+0x34f0c1) [0x55c7cd1000c1]"
 ```
 
+### Soroban Settings Helper
+- Name - `settings-helper.sh`
+- Prequisites - `stellar-xdr` and `stellar-core`
+- Description - This is a script to help with the [Soroban Settings Upgrade](../docs/software/soroban-settings.md). It's important to be aware of how the underlying process works
+in case the script has some issues, so please read through that doc before attempting to use this script. This script should be run from the directory that contains your stellar-core binary. This script also queries the SDF Horizon for the sequence number of the account, so if the SDF Horizon instance is unavailable, then you'll need to provide the account's sequence number manually.
+- Usage - Ex. `sh ../scripts/settings-helper.sh SCSQHJIUGUGTH2P4K6AOFTEW4HUMI2BRTUBBDDXMQ4FLHXCX25W3PGBJ 'Test SDF Network ; September 2015' ../soroban-settings/testnet_settings_phase2.json`. The first argument is the secret key of the source account that will be used for the transactions to set up the upgrade, the second argument is the the network passphrase, and the third is 
+the path to the JSON file with the proposed settings.
+
+
 ## Style guide
 We follow [PEP-0008](https://www.python.org/dev/peps/pep-0008/).

scripts/settings-helper.sh

@@ -0,0 +1,50 @@
+#!/bin/sh
+set -e
+
+SECRET_KEY="$1"
+PUBLIC_KEY=$(./stellar-core convert-id "$SECRET_KEY" | sed -n '4p' | awk '{print $NF}')
+echo "PUBLIC_KEY is $PUBLIC_KEY"
+
+PUBNET_HORIZON="https://horizon.stellar.org/accounts"
+PUBNET_PASSPHRASE="Public Global Stellar Network ; September 2015"
+
+TESTNET_HORIZON="https://horizon-testnet.stellar.org/accounts"
+TESTNET_PASSPHRASE="Test SDF Network ; September 2015"
+
+HORIZON=""
+
+#choose which horizon to hit for the SEQ_NUM. If Horizon is down, remove this code and manually set SEQ_NUM below
+if [ "$2" == "$PUBNET_PASSPHRASE" ]
+then
+HORIZON=$PUBNET_HORIZON
+elif [ "$2" == "$TESTNET_PASSPHRASE" ]
+then
+HORIZON=$TESTNET_HORIZON
+else
+echo "invalid passphrase"
+fi
+
+# get seq num
+SEQ_NUM="$(curl -s "$HORIZON/$PUBLIC_KEY" | grep "\"sequence\":" | sed 's/[^0-9]//g')"
+re='^[0-9]+$'
+if ! [[ $SEQ_NUM =~ $re ]] ; then
+   echo "Error: SEQ_NUM not retrieved. Your account might not be funded, or Horizon might be down. Hardcode the SEQ_NUM below and remove the horizon code." >&2; exit 1
+fi
+
+OUTPUT="$(echo $SECRET_KEY | ./stellar-core get-settings-upgrade-txs "$PUBLIC_KEY" "$SEQ_NUM" "$2" --xdr $(stellar-xdr encode --type ConfigUpgradeSet $3) --signtxs)"
+
+echo "----- TX #1 -----"
+echo "curl -G 'http://localhost:11626/tx' --data-urlencode 'blob=$(echo "$OUTPUT" | sed -n '1p')'"
+
+echo "----- TX #2 -----"
+echo "curl -G 'http://localhost:11626/tx' --data-urlencode 'blob=$(echo "$OUTPUT" | sed -n '3p')'"
+
+echo "----- TX #3 -----"
+echo "curl -G 'http://localhost:11626/tx' --data-urlencode 'blob=$(echo "$OUTPUT" | sed -n '5p')'"
+echo "-----"
+
+echo "curl -G 'http://localhost:11626/dumpproposedsettings' --data-urlencode 'blob=$(echo "$OUTPUT" | sed -n '7p')'"
+echo "-----"
+
+echo "distribute the following command with the upgradetime set to an agreed upon point in the future"
+echo "curl -G 'http://localhost:11626/upgrades?mode=set&upgradetime=YYYY-MM-DDT01:25:00Z' --data-urlencode 'configupgradesetkey=$(echo "$OUTPUT" | sed -n '7p')'"

src/main/SettingsUpgradeUtils.cpp

@@ -63,7 +63,7 @@ getCreateTx(PublicKey const& publicKey, LedgerKey const& contractCodeLedgerKey,
 
     auto& tx = txEnv.v1().tx;
     tx.sourceAccount = toMuxedAccount(publicKey);
-    tx.fee = 15'000'000;
+    tx.fee = 25'000'000;
     tx.seqNum = seqNum;
 
     Preconditions cond;
@@ -133,7 +133,7 @@ getCreateTx(PublicKey const& publicKey, LedgerKey const& contractCodeLedgerKey,
 
     tx.ext.v(1);
     tx.ext.sorobanData().resources = uploadResources;
-    tx.ext.sorobanData().resourceFee = 7'000'000;
+    tx.ext.sorobanData().resourceFee = 15'000'000;
 
     return {txEnv, contractSourceRefLedgerKey, contractID};
 }