Set state via TX

tests/systemtests/bank_test.go

@@ -15,10 +15,45 @@ import (
 )
 
 func TestQueryTotalSupply(t *testing.T) {
+	// scenario:
+	// given a chain with a custom token on genesis
+	// when an amount is burned
+	// then this is reflected in the total supply
+
 	sut.ResetChain(t)
 	cli := NewCLIWrapper(t, sut, verbose)
+	sut.ModifyGenesisJSON(t, setupGenesis(t, cli))
+	sut.StartChain(t)
+
+	raw := cli.CustomQuery("q", "bank", "total-supply")
+
+	exp := map[string]int64{
+		"stake":     int64(500000000 * sut.nodesCount),
+		"testtoken": int64(1000000000 * sut.nodesCount),
+		"mytoken":   1_000_000,
+	}
+	require.Len(t, gjson.Get(raw, "supply").Array(), len(exp), raw)
 
-	sut.ModifyGenesisJSON(t, func(genesis []byte) []byte {
+	for k, v := range exp {
+		got := gjson.Get(raw, fmt.Sprintf("supply.#(denom==%q).amount", k)).Int()
+		assert.Equal(t, v, got, raw)
+	}
+
+	// and when
+	txHash := cli.Run("tx", "bank", "burn", "node0", "400000mytoken")
+	RequireTxSuccess(t, txHash)
+	// then
+	exp["mytoken"] = 600_000 // update expected state
+	raw = cli.CustomQuery("q", "bank", "total-supply")
+	for k, v := range exp {
+		got := gjson.Get(raw, fmt.Sprintf("supply.#(denom==%q).amount", k)).Int()
+		assert.Equal(t, v, got, raw)
+	}
+	assert.Equal(t, int64(600_000), cli.QueryBalance(cli.GetKeyAddr("node0"), "mytoken"))
+}
+
+func setupGenesis(t *testing.T, cli *CLIWrapper) func(genesis []byte) []byte {
+	return func(genesis []byte) []byte {
 		// disable inflation
 		genesis, err := sjson.SetRawBytes(genesis, "app_state.mint.minter.inflation", []byte(`"0.000000000000000000"`))
 		require.NoError(t, err)
@@ -41,21 +76,5 @@ func TestQueryTotalSupply(t *testing.T) {
 		newState, err := sjson.SetRawBytes(genesis, fmt.Sprintf("app_state.bank.balances.#[address==%q]#.coins", anyAddr), newBalancesBz)
 		require.NoError(t, err)
 		return newState
-	})
-
-	sut.StartChain(t)
-
-	raw := cli.CustomQuery("q", "bank", "total-supply")
-
-	exp := map[string]int64{
-		"stake":     int64(500000000 * sut.nodesCount),
-		"testtoken": int64(1000000000 * sut.nodesCount),
-		"mytoken":   1000000,
-	}
-	require.Len(t, gjson.Get(raw, "supply").Array(), len(exp), raw)
-
-	for k, v := range exp {
-		got := gjson.Get(raw, fmt.Sprintf("supply.#(denom==%q).amount", k)).Int()
-		assert.Equal(t, v, got, raw)
 	}
 }

tests/systemtests/getting_started.md

@@ -171,3 +171,35 @@ Next step is to add the new token to the assert map. But we can also make it mor
 ```shell
 go test -mod=readonly -tags='system_test' -v ./...  --run TestQueryTotalSupply --verbose --nodes-count=1 
 ```
+
+## Part 4: Set state via TX
+
+Complexer workflows and tests require modifying state on a running chain. This works only with builtin logic and operations.
+If we want to burn some our new tokens, we need to submit a bank burn message to do this.
+The CLI wrapper works similar to the query. Just pass the parameters. It uses the `node0` key as *default*:
+
+```go
+	// and when
+	txHash := cli.Run("tx", "bank", "burn", "node0", "400000mytoken")
+	RequireTxSuccess(t, txHash)
+```
+`RequireTxSuccess` or `RequireTxFailure` can be used to ensure the expected result of the operation.
+Next, check that the changes are applied.
+```go
+	exp["mytoken"] = 600_000 // update expected state
+	raw = cli.CustomQuery("q", "bank", "total-supply")
+	for k, v := range exp {
+		got := gjson.Get(raw, fmt.Sprintf("supply.#(denom==%q).amount", k)).Int()
+		assert.Equal(t, v, got, raw)
+	}
+	assert.Equal(t, int64(600_000), cli.QueryBalance(cli.GetKeyAddr("node0"), "mytoken"))
+```
+
+While tests are still more or less readable, it can gets harder the longer they are. I found it helpful to add
+some comments at the beginning to describe what the intention is. For example:
+```go
+	// scenario:
+	// given a chain with a custom token on genesis
+	// when an amount is burned
+	// then this is reflected in the total supply
+```