Merge branch 'main' into mnemonic_tx

docs/docs/building-modules/04-query-services.md

@@ -54,3 +54,31 @@ Here's an example implementation for the bank module:
 ```go reference
 https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/bank/keeper/grpc_query.go
 ```
+
+### Calling queries from the State Machine
+
+The Cosmos SDK v0.47 introduces a new `cosmos.query.v1.module_query_safe` Protobuf annotation which is used to state that a query that is safe to be called from within the state machine, for example:
+- a Keeper's query function can be called from another module's Keeper,
+- ADR-033 intermodule query calls,
+- CosmWasm contracts can also directly interact with these queries.
+
+If the `module_query_safe` annotation set to `true`, it means:
+ - The query is deterministic: given a block height it will return the same response upon multiple calls, and doesn't introduce any state-machine breaking changes across SDK patch versions.
+ - Gas consumption never fluctuates across calls and across patch versions.
+
+If you are a module developer and want to use `module_query_safe` annotation for your own query, you have to ensure the following things:
+ - the query is deterministic and won't introduce state-machine-breaking changes without coordinated upgrades
+ - it has its gas tracked, to avoid the attack vector where no gas is accounted for
+ on potentially high-computation queries.
+
+#### Deterministic and Regression tests	
+
+Tests are written for queries in the Cosmos SDK which have `module_query_safe`. Each query is tested using 2 methods:
+- we use property-based testing using the [`rapid`](https://pkg.go.dev/pgregory.net/rapid@v0.5.3) library. The property that is tested is that the query response and gas consumption are the same upon 1000 query calls.
+- we write regression tests with hardcoded responses and gas, and make sure they don't change upon 1000 calls and between SDK patch versions.
+
+Here's an example of regression tests:
+
+```go reference
+https://github.com/cosmos/cosmos-sdk/blob/9f3575a10f1a6f1315b94a9be783df5156ce2292/tests/integration/bank/keeper/deterministic_test.go#L102-L115
+```