From 3cdc051dbebd9f0fbbbef427992f2d794475f577 Mon Sep 17 00:00:00 2001
From: Jonathan LEI <me@xjonathan.dev>
Date: Sun, 16 Jul 2023 19:40:59 +0000
Subject: [PATCH] docs: transaction fees page

---
 book/src/SUMMARY.md          |  1 +
 book/src/transaction-fees.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100644 book/src/transaction-fees.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index a0372c4..15b85ca 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -12,6 +12,7 @@
 - [Providers](./providers.md)
 - [Signers](./signers.md)
 - [Accounts](./accounts.md)
+- [Transaction fees](./transaction-fees.md)
 - [Argument resolution](./argument-resolution.md)
 
 # Cookbooks
diff --git a/book/src/transaction-fees.md b/book/src/transaction-fees.md
new file mode 100644
index 0000000..28e4c39
--- /dev/null
+++ b/book/src/transaction-fees.md
@@ -0,0 +1,31 @@
+# Transaction fees
+
+Starknet transactions are priced using a single `max_fee` value, which indicates the maximum amount of fees (in `Wei`) that an account is willing to pay.
+
+For commands that send out transactions, Starkli needs to come up with this value. By default, a fee estimate is requested from the [provider](./providers.md), and a 50% buffer is added on top of the estimate to avoid failures due to price fluctuations.
+
+## Setting `max_fee` manually
+
+It's possible to skip the entire fee estimation process by manually providing a `max_fee` value.
+
+The recommended way to do it is through the `--max-fee` option, which accepts a decimal value in Ether (18 decimals). For example, to perform an `ETH` transfer with a `max_fee` of `0.01 ETH`:
+
+```console
+starkli invoke eth transfer 0x1234 u256:100 --max-fee 0.01
+```
+
+If you already have the `max_fee` value in `Wei`, it's also possible to use the raw value directly via the `--max-fee-raw` option. An equivalent command to the example above would be:
+
+```console
+starkli invoke eth transfer 0x1234 u256:100 --max-fee-raw 10000000000000000
+```
+
+## Estimating fee only (dry run)
+
+Commands that send out transactions accept a `--estimate-only` flag, which stops command execution as soon as an estimate is generated.
+
+An example command to estimate the fee for an `ETH` transfer:
+
+```console
+starkli invoke eth transfer 0x1234 u256:100 --estimate-only
+```