docs: add auth/gasprice query and gas price mechanism

docs/resources/gas-fees.md

@@ -41,6 +41,67 @@ Maximum Fee = Gas Wanted × Gas Fee
 
 You will be charged the gas fee you specified.
 
+## Gas Price
+
+The network dynamically adjusts the minimum required gas price after each block
+based on demand. This ensures the network responds to congestion by increasing
+prices when usage is high and decreasing them when usage is low.
+
+### How Gas Price Works
+
+The gas price is returned as a `GasPrice` object with two fields:
+- `gas` - the gas units (e.g., 1000)
+- `price` - the price for those gas units (e.g., "100ugnot")
+
+Together, these represent a **rate**. For example, `{gas: 1000, price: "100ugnot"}`
+means the minimum rate is 100 ugnot per 1000 gas units, which simplifies to
+0.1 ugnot per gas unit.
+
+### Calculating Your Gas Fee
+
+Your `--gas-fee` must meet or exceed this network gas price for your transaction
+to be accepted. To calculate the minimum fee:
+
+1. Query the current gas price
+2. Calculate the rate: `price / gas`
+3. Multiply by your `--gas-wanted`
+
+**Example:**
+```bash
+# Query returns: {gas: 1000, price: "100ugnot"}
+# Rate = 100 ÷ 1000 = 0.1 ugnot/gas
+
+# If you want --gas-wanted 2000000:
+# Minimum fee = 2,000,000 × 0.1 = 200,000 ugnot
+# So set: --gas-fee 200000ugnot (or higher)
+```
+
+### Querying Gas Price
+
+You can query the current network gas price using:
+```bash
+gnokey query auth/gasprice -remote https://rpc.gno.land:443
+```
+
+This returns the gas price calculated from the most recently completed block,
+which is the minimum rate currently required for new transactions.
+
+For more details, see [`auth/gasprice`](../users/interact-with-gnokey.md#authgasprice).
+
+### How the Network Adjusts Gas Price
+
+The network automatically adjusts the gas price after each block based on demand:
+
+- **Low demand**: Price decreases (but never below 1 ugnot/1000 gas)
+- **High demand**: Price increases
+
+The network targets 70% utilization of the maximum block gas limit (3B gas) by default.
+When blocks exceed this target, prices rise. When blocks fall below it, prices drop.
+Changes are gradual to avoid sudden price spikes.
+
+**Note**: Individual validators can also set their own minimum gas price through the
+`min_gas_prices` configuration parameter in their `config.toml` file. Different validators may have different minimums.
+
 ## Typical Gas Values
 
 Here are some recommended gas values for common operations:
@@ -99,6 +160,15 @@ gnokey maketx call \
   YOUR_KEY_NAME
 ```
 
+## Common Errors
+
+**Insufficient fees:** `insufficient fees; got: 50000ugnot required: 200000ugnot`
+- Your `--gas-fee` is too low. Increase it to meet the minimum required.
+
+**Out of gas:** `out of gas in location: ... wanted: 100000, used: 150000`
+- Your `--gas-wanted` is too low. Use `--simulate only` to estimate needed gas, then increase.
+- ⚠️ **You're still charged for failed transactions!** Fees are deducted before execution, so even if your transaction runs out of gas, you pay for the gas consumed up to the limit.
+
 ## Gas Optimization Tips
 
 To minimize gas costs, consider these optimization strategies:

docs/users/interact-with-gnokey.md

@@ -1022,12 +1022,14 @@ types of queries to a Gno.land network.
 Below is a list of queries a user can make with `gnokey`:
 
 - `auth/accounts/{ADDRESS}` - returns information about an account
+- `auth/gasprice` - returns the current minimum gas price required for transactions
 - `bank/balances/{ADDRESS}` - returns balances of an account
 - `vm/qfuncs` - returns the exported functions for a given pkgpath
 - `vm/qfile` - returns package contents for a given pkgpath
 - `vm/qdoc` - Returns the JSON of the doc for a given pkgpath, suitable for printing
 - `vm/qeval` - evaluates an expression in read-only mode on and returns the results
 - `vm/qrender` - shorthand for evaluating `vm/qeval Render("")` for a given pkgpath
+- `vm/qpaths` - lists all existing package paths
 - `vm/qstorage` - returns storage usage and deposit locked in a realm
 
 Let's see how we can use them.
@@ -1093,6 +1095,40 @@ data: "227984898927ugnot"
 
 The data field will contain the coins the address owns.
 
+### `auth/gasprice`
+
+The `auth/gasprice` query allows you to fetch the minimum gas price currently
+required for transactions. This is useful for ensuring your `--gas-fee` meets
+the network's requirements when submitting transactions. To call it, we can run the following command:
+
+```bash
+gnokey query auth/gasprice -remote https://rpc.gno.land:443
+```
+
+If everything went correctly, we should get an output similar to the following:
+
+```bash
+height: 0
+data: {
+  "gas": 1000,
+  "price": "100ugnot"
+}
+```
+
+The return data will contain the following fields:
+- `height` - the height at which the query was executed. This is currently not
+  supported and is `0` by default.
+- `data` - contains the result of the query.
+
+The `data` field returns a `GasPrice` object, which contains:
+- `gas` - the gas units
+- `price` - the price for those gas units in the form of a [coin](../resources/gno-stdlibs.md#coin)
+
+The network adjusts the gas price after each block based on demand. This query returns
+the gas price calculated from the most recently completed block, which is the minimum
+gas price required for new transactions.
+For a deeper explanation, see [Gas Price](../resources/gas-fees.md#gas-price).
+
 ### `vm/qfuncs`
 
 Using the `vm/qfuncs` query, we can fetch exported functions from a specific package