Katana Fee Token Configurations

[kariy]

Background

Following the v0.13.0 protocol update, currently Starknet have two fee tokens that can be used to pay for transactions fee - $ETH and $STRK token - used to pay for < V3 and >= V3 txs respectively.

This is a global network configuration and thus enforced on the protocol level. On the technical side, this means when creating an instance of blockifier or starknet_in_rust (ie Starknet logic implementations) you have to specify the contract addresses of both ETH and STRK token as part of their configurations. The ETH and STRK tokens are explicitly required to be defined.

The long term goal of Katana is to be a sequencer where people can easily use to spin up their own Starknet-based blockchain network. Katana is designed with customizability in mind, granting users to easily configure their blockchain network to suits their needs. It's not meant to be a devnet or even a Starknet full node. As such, Katana doesn't strictly aim to achieve 100% feature parity with Starknet.

Problem

The main issue is that the two fee tokens exist due to circumstances specific to Starknet only. Imo doesn't seem to make much sense for us to follow this path of having two separate fee tokens.

It's worth noting that, < V3 transactions are now deprecated. So they may soon not be supported at all and thus making ETH fee token obsolete.

Katana doesn't currently allow to configure the STRK-equivalent fee token (only ETH-equivalent). I wrote '-equivalent' because the genesis configuration allow to customize the fee token metadata ie name, symbols etc, so you're not stuck with ETH as the fee token name. But the internal/rpc types would still refer to it as ETH token as to conform to blockifier and sir implementations, and also the client libraries.

For context, this is a type returned by the estimateFee API. The only possible variants of PriceUnit are; Wei and Fri - for ETH and STRK token respectively. If we were to extend Katana fee token configuration allowing for a custom PriceUnit, the client libraries (eg starknet-rs, starknet.js, etc) would not be fully compatible as they would expect the price unit to only be either Wei or Fri.

Ideally, the price unit should be based on the fee token configuration, bcs it would be awkward if the fee token is LORDS but then the price unit reflected in the estimateFee is Wei)

dojo/crates/katana/primitives/src/fee.rs

Lines 5 to 14 in f0637f9

	pub struct TxFeeInfo {
	/// The total amount of L1 gas consumed by the transaction.
	pub gas_consumed: u128,
	/// The L1 gas price at the time of the transaction execution.
	pub gas_price: u128,
	/// The fee used by the transaction.
	pub overall_fee: u128,
	/// The type of fee used to pay for the transaction, depending on the transaction type.
	pub unit: PriceUnit,
	}

Though, Katana is a Starknet-based sequencer, it doesn't mean that we want it to fully mirror everything about the mainnet. Unless we really want to maintain Katana as a proper Starknet devnet (which is the assumption of most people still).

dojo/crates/katana/primitives/src/genesis/mod.rs

Line 36 in f0637f9

pub struct FeeTokenConfig {

Which approach to this problem should we take, thinking of short and long term tradeoff:

1. Allow to specify both token types - also allowing to customize their individual configs - basically adding another STRK-equivalent fee token config in genesis for paying >= V3 txs.

2. Define only a single fee token and use it for both < V3 and >= V3 transactions. (when setting up blockifier and sir, we will use that fee token as both the ETH and STRK token)

(1) may soon be obsolete after Starknet remove support for < V3 transactions but be more Starknet equivalent in the short term(?). (2) would be the simplest but to ensure we don't break client libraries, the RPC (and perhaps even internally) would still need to refer to the custom single token config as the two fee token - ETH and STRK based setup, so would introduce some awkwardness in the codebase.

---

The fee token is define in the FeeTokenAddresses struct:

dojo/bin/katana/src/main.rs

Lines 54 to 57 in f0637f9

	fee_token_addresses: FeeTokenAddressses {
	eth: starknet_config.genesis.fee_token.address,
	strk: Default::default(),
	},

It is then passed to the executor factory constructor function, as part of the executor configurations.

dojo/bin/katana/src/main.rs

Lines 54 to 57 in f0637f9

	fee_token_addresses: FeeTokenAddressses {
	eth: starknet_config.genesis.fee_token.address,
	strk: Default::default(),
	},

While this is where we pass the fee tokens that was configured earlier to blockifier when instantiating it:

dojo/crates/katana/executor/src/implementation/blockifier/mod.rs

Line 82 in f0637f9

let block_context = utils::block_context_from_envs(&block_env, &cfg_env);

dojo/crates/katana/executor/src/implementation/blockifier/utils.rs

Lines 327 to 330 in f0637f9

	pub(crate) fn block_context_from_envs(block_env: &BlockEnv, cfg_env: &CfgEnv) -> BlockContext {
	let fee_token_addresses = FeeTokenAddresses {
	eth_fee_token_address: to_blk_address(cfg_env.fee_token_addresses.eth),
	strk_fee_token_address: to_blk_address(cfg_env.fee_token_addresses.strk),

---

NOTE: this was written at 3am while im half asleep, so i might not be able to express my message properly.

[glihm]

Thanks for the great explanation here @kariy.

Having only one fee token makes sense, as you mention we may not mirror exactly Starknet, even if two tokens is not too complex to manage I guess.

At RPC level we must remain compatible even if it may be less good for the devex of having only one fee token. Currently we already struggle with people using dojo with lower version of the RPC, if we have too much divergence here it may be even more friction for people. And we may instruct the user if we choose to only have one fee token of how Katana is handling this (might be simpler a the end though for the user).

So in 1), we would always have $ETH being defined (without being configurable by the user)? As you mentioned that they could use the genesis for an other $STRK equivalent.

And in 2), we could document that setting either $STRK/$ETH will set the same token. So if both are set, we throw an error.