From 9e36e4628ed2d8d81f45a7c130f03a916a368be7 Mon Sep 17 00:00:00 2001 From: Jonathan LEI Date: Wed, 1 May 2024 15:44:54 +0800 Subject: [PATCH] docs: document STRK tx fee payment --- book/src/transaction-fees.md | 60 +++++++++++++++++++++++++++++++----- 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/book/src/transaction-fees.md b/book/src/transaction-fees.md index 28e4c39..b2331e2 100644 --- a/book/src/transaction-fees.md +++ b/book/src/transaction-fees.md @@ -1,30 +1,74 @@ # 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. +Historically, Starknet transaction fees could only be paid with _ETH_. With the introduction of [v3 transactions](https://github.com/starknet-io/SNIPs/blob/main/SNIPS/snip-8.md), however, users now have the option to pay fees in _STRK_ if they so choose. -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. +By default, Starkli sends transactions with _ETH_ fees. The fee token can be set by using the `--fee-token` option (e.g., `--fee-token STRK`). Alternatively, you can also use the `--eth` or `--strk` shorthands. -## Setting `max_fee` manually +> ℹ️ **Note** +> +> While it might seem to be the case, it's not true that v3 transactions provide the option to choose between fee tokens. Instead, v3 transactions are _always_ paid with _STRK_. Starkli abstracts this away by automatically falling back to using older transaction versions when users choose to pay fees in _ETH_. -It's possible to skip the entire fee estimation process by manually providing a `max_fee` value. +## Setting transaction fees manually -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`: +By default, Starkli requests a fee estimate from the [provider](./providers.md), and a 50% buffer is added on top of the estimate to avoid failures due to price fluctuations. However, sometimes it might be desirable to manually specify the fees instead. Some common reasons to do this include: + +- The fee estimation returned by the provider is inaccurate; +- You want to speed up command execution by skipping fee estimation; or +- The transaction in question is flaky, so the estimation might fail. + +Since transactions paying in _ETH_ and _STRK_ are priced differently, the options for manually setting fees are different depending on which token you're paying fees with. + +### Setting _ETH_ fees manually + +Transactions that pay fees in _ETH_ are priced using a single `max_fee` value, which indicates the maximum amount of fees (in `Wei`) that an account is willing to pay. + +Users can set the `max_fee` value by using 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: +If you already have the `max_fee` value in `Wei`, you can also 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) +### Setting _STRK_ fees manually + +Transactions that pay fees in _STRK_ are priced differently from those that pay with _ETH_. Specifically, the fee is made up of two components: `gas` and `gas_price`, which indicate the maximum amount of **L1 gas** and the maximum **L1 gas price** a user is willing to pay, respectively. + +To set the `gas` value, simply use the `--gas` option. For example, to manually set a `gas` value of `50000`: + +```console +starkli invoke --strk eth transfer 0x1234 u256:100 --gas 50000 +``` + +> 💡 **Tips** +> +> When `gas` is manually set but `gas_price` is not, Starkli does _not_ perform a fee estimation and instead sources the `gas_price` value directly from the pending block header. Therefore, transaction failure will _not_ be detected until it's reverted on-chain. + +To set the `gas_price` value, use the `--gas-price` option, which accepts a decimal value in _STRK_ (18 decimals). For example, to set the L1 gas price at `0.0001` _STRK_: + +```console +starkli invoke --strk eth transfer 0x1234 u256:100 --gas-price 0.0001 +``` + +Similar to setting `max_fee` for _ETH_-priced transactions, the `gas_price` value can also be set with raw values by using `--gas-price-raw`. This command is equivalent to the one shown above: + +```console +starkli invoke --strk eth transfer 0x1234 u256:100 --gas-price-raw 100000000000000 +``` + +> 💡 **Tips** +> +> When `gas_price` is manually set but `gas` is not, Starkli will still perform a fee estimation to determine how much L1 gas is needed. + +## Estimating the 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: +An example command to estimate the fee for an _ETH_ transfer: ```console starkli invoke eth transfer 0x1234 u256:100 --estimate-only