add message fee docs

docs/CLI/commands.md

@@ -216,6 +216,41 @@ Returns the [receipt](../Blocks/transaction-life-cycle.md#transaction-receipt) a
 
 - `transaction_hash`\* - hash of the requested transaction
 
+### starknet estimate_fee
+
+```bash title="estimate_fee"
+    starknet estimate_fee
+        --address <contract_address>
+        --abi <contract_abi>
+        --function <function_name>
+        --inputs <arguments>
+```
+
+Returns the fee estimation for a given contract call, can take the following arguments:
+
+- `address`\* - the address of the called contract
+- `contract_abi`\* - a path to a JSON file containing the called [contract’s abi](https://www.cairo-lang.org/docs/hello_starknet/intro.html#the-contract-s-abi)
+- `function_name`\*- the name of the called function
+- `arguments`\* - inputs to the called function, represented by a list of space-delimited values`
+
+### starknet estimate_message_fee
+
+```bash title="estimate_message_fee"
+    starknet estimate_message_fee
+        --from_address <sender_address>
+        --to_address <contract_address>
+        --function <function_name>
+        --inputs <arguments>
+```
+
+Returns the fee estimation for a given l1 handler application, can take the following arguments:
+
+- `from_address`\* - the L1 address of the sender
+- `to_address`\* - the L2 address of the receipient
+- `contract_abi`\* - a path to a JSON file containing the [abi](https://www.cairo-lang.org/docs/hello_starknet/intro.html#the-contract-s-abi) of the receiving contract on L2
+- `function_name`\*- the name of the desired l1 handler
+- `arguments`\* - inputs to the called handler, represented by a list of space-delimited values
+
 :::tip Custom endpoints
 When working with the CLI, it's possible to manually choose the read/write endpoints for the
 interaction with StarkNet, by adding the ``--feeder_gateway_url` and `gateway_url` parameters.

docs/L1<>L2 Communication/messaging-mechanism.md

@@ -2,7 +2,18 @@
 
 ## L1 → L2 Messages
 
-Contracts on L1 can interact asynchronously with contracts on L2 via the L1→L2 messaging protocol. In the first step, an L1 contract initiates a message to an L2 contract on StarkNet. It does so by calling the [`sendMessageToL2`](https://github.com/starkware-libs/cairo-lang/blob/4e233516f52477ad158bc81a86ec2760471c1b65/src/starkware/starknet/eth/StarknetMessaging.sol#L100) function on the StarkNet Core Contract with the message parameters. The StarkNet Core Contract hashes the message parameters (the L1 sender address, the recipient contract address on StarkNet, function selector, and the relevant calldata) and increases the hash counter by 1.
+Contracts on L1 can interact asynchronously with contracts on L2 via the L1→L2 messaging protocol. In the first step, an L1 contract initiates a message to an L2 contract on StarkNet. It does so by calling the [`sendMessageToL2`](https://github.com/starkware-libs/cairo-lang/blob/4e233516f52477ad158bc81a86ec2760471c1b65/src/starkware/starknet/eth/StarknetMessaging.sol#L100) function on the StarkNet Core Contract with the message parameters. The StarkNet Core Contract hashes the message parameters and updates the l1→l2 messages mapping to indicate that a message with this hash was indeed sent. An L1→L2 message consists of:
+
+- The L1 sender address
+- The recipient contract address on StarkNet
+- Function selector
+- Calldata array
+- Message nonce
+
+:::info message nonce
+The message nonce is maintained on the StarkNet Core contract on L1, and is bumped whenever a message is
+sent to L2. It is used to avoid hash collisions between different L2 transactions who are induced by the same message being sent on L1 multiple times.
+:::
 
 A message is then decoded into a StarkNet transaction which invokes a function annotated with the `l1_handler` decorator on the target contract.
 The StarkNet sequencer, upon seeing enough L1 confirmations for the transaction that sent the message, initiates the corresponding L2 transaction which invokes the relevant `l1_handler`. The handled message is then attached to the proof of the relevant state update – and the message is cleared (or the count is deduced) when the state is updated. At this point the message is considered handled.
@@ -42,3 +53,14 @@ The above flow is illustrated in the following diagram:
 Imagine a scenario where a user transfers an asset from L1 to L2. The flow starts with the user sending the asset to a StarkNet bridge and the corresponding L1→L2 message generation. Now, imagine that the L2 message consumption doesn’t function (this might happen due to a bug in the dApps’s Cairo contract). This could result in the user losing custody over their asset forever.
 
 To mitigate this risk, we allow the contract that initiated the L1→L2 message to cancel it – after declaring the intent and waiting a suitable amount of time. The user starts by calling [`startL1ToL2MessageCancellation`](https://github.com/starkware-libs/cairo-lang/blob/4e233516f52477ad158bc81a86ec2760471c1b65/src/starkware/starknet/eth/StarknetMessaging.sol#L134) with the relevant message parameters in the StarkNet Core Contract. Then, after a five days delay, the user can finalize the cancellation by calling [`cancelL1ToL2Message`](https://github.com/starkware-libs/cairo-lang/blob/4e233516f52477ad158bc81a86ec2760471c1b65/src/starkware/starknet/eth/StarknetMessaging.sol#L147). The reason for the delay is to protect the sequencer from a DOS attack in the form of repeatedly sending and canceling a message – before it is included in L1, rendering the L2 block which contains the activation of the corresponding L1 handler invalid. Note that this flow should only be used in edge cases such as bugs on the Layer 2 contract preventing message consumption.
+
+## L1 → L2 Message Fees
+
+An L1 → L2 message induces a transaction on L2 which is not associated with an account (unlike regular transactions). This calls for a different mechanism for paying the transaction's fee, for otherwise the sequencer has no incentive of including l1 handler calls inside a block.
+
+To avoid having to interact with both L1, L2 when sending a message, L1 → L2 messages are paypable on L1, by sending ETH with the call to the payable function `sendMessageToL2` on the StarkNet Core contract. This payment will be taken as a fee for handling the message, and will be charged by the sequencer in full upon updating the L1 state with the consumption of this message.
+
+Note that throughtout the lifecycle of the message, the assoicated fee is locked in the Core contract. If the message was not processed for any reason, then [cancelling](./messaging-mechanism#l1--l2-message-cancellation) the message will
+also return the fee to the sender.
+
+You can use the [CLI](../CLI/commands#starknet-estimate_message_fee) to get an estimation for a L1 → L2 message fee.

docs/L1<>L2 Communication/token-bridge.md

@@ -8,14 +8,16 @@ The bridges facilitate a user’s ability to conduct their transactions with the
 
 ### L1→L2 Transfer (Deposit)
 
-#### Step 1: Call The Deposit Function on L1
+#### Step 1: Call The Deposit Function on L1 and pay the deposit fee
 
-The user calls the function `deposit` (see [ERC-20 deposit](https://github.com/starkware-libs/starkgate-contracts/blob/28f4032b101003b2c6682d753ea61c86b732012c/src/starkware/starknet/apps/starkgate/solidity/StarknetERC20Bridge.sol#L10) and [ETH deposit](https://github.com/starkware-libs/starkgate-contracts/blob/28f4032b101003b2c6682d753ea61c86b732012c/src/starkware/starknet/apps/starkgate/solidity/StarknetEthBridge.sol#L10)), supplying as parameters the recipient address on StarkNet and the amount to transfer in the case of ERC-20 token. The deposit function then:
+The user calls the function `deposit` (see [ERC-20 deposit](https://github.com/starkware-libs/starkgate-contracts/blob/28f4032b101003b2c6682d753ea61c86b732012c/src/starkware/starknet/apps/starkgate/solidity/StarknetERC20Bridge.sol#L10) and [ETH deposit](https://github.com/starkware-libs/starkgate-contracts/blob/28f4032b101003b2c6682d753ea61c86b732012c/src/starkware/starknet/apps/starkgate/solidity/StarknetEthBridge.sol#L10)), supplying as parameters the recipient address on StarkNet and the amount to transfer in the case of ERC-20 token.
+
+The deposit function then:
 
 - Checks that the funds transferred are within the Alpha [limitations](./token-bridge.md#starkgate-alpha-limitations)
 - Transfers the funds from the user account to the StarkNet bridge
 - Emits a deposit [event](https://github.com/starkware-libs/starkgate-contracts/blob/28f4032b101003b2c6682d753ea61c86b732012c/src/starkware/starknet/apps/starkgate/solidity/StarknetTokenBridge.sol#L101) with the sender address on L1, the recipient address on L2, and the amount
-- Sends a message to the relevant L2 bridge with the amount to be transferred, and the recipient address as parameters. Note that, since every single bridge is dedicated to one token type, the token type doesn't have to be explicit here.
+- Sends a message to the relevant L2 bridge with the amount to be transferred, and the recipient address as parameters. Note that, since every single bridge is dedicated to one token type, the token type doesn't have to be explicit here. The deposit fee is passed along to the StarkNet Core contract, which is responsible for messaging.
 
 At the end of this step (i.e., after the execution on L1) the deposit transaction is known to StarkNet’s sequencer, yet sequencers may wait for enough L1 confirmations before corresponding deposit transaction is initated on L2. During this step, the status of the L2 deposit transaction is [`NOT_RECEIVED`](../Blocks/transaction-life-cycle.md#not_received).
 
@@ -30,6 +32,8 @@ At the end of this step (i.e., after the sequencer processed this transaction, b
 
 Once the sequencer completes the block construction, StarkNet’s provers will prove its validity and submit a state update to L1. When this happens, the message confirming the funds transfer will be cleared from the StarkNet Core Contract, and the fact that the user has transferred their funds will be part of the now finalized state of StarkNet. Note that if the message wasn’t on L1 to begin with (meaning StarkNet “invented” a deposit request), the state update would fail.
 
+After completing this step, the sequencer collects the desposit fee (to the sequencer, see is just a message fee).
+
 ### L2→L1 Transfer (Withdraw)
 
 #### Step 1: Call The Withdraw Function on L2