feat: fee payer

Author: ratik

docs/neutron/feerefunder/client.md

@@ -53,5 +53,6 @@ Output:
           timeout_fee:
             - denom: "untrn"
               amount: "500"
+        payer: neutron10h9stc5v6ntgeygf5xf945njqq5h32r54rf7kf
   ```
 </details>

docs/neutron/feerefunder/overview.md

@@ -21,10 +21,29 @@ The module requires smart-contracts, which use [Transfer](../transfer/messages#m
 * `ack_fee` - amount of coins to refund relayer for submittting ack message for a particular IBC packet (i.e. `500untrn`);
 * `timeout_fee` - amount of coins to refund relayer for submitting timeout message for a particular IBC packet (i.e. `500untrn`);
 * `recv_fee` - currently is used for compatibility with ICS-29 interface only and **must be set to zero** (i.e. `0untrn`), because Neutron's fee module can't refund relayers for submission of `Recv` IBC packets due to compatibility with target chains.
+* `payer` - optional address of the contract which will pay for the fees. Please note that payer must give allowance to the contract to spend fees.
 
 > **Note:** the fees can be specified only in native Cosmos-SDK coins. CW-20 coins are not supported!
 
-When a smart-contract issues `Transfer` or `SubmitTx` message, the fee Module deduct the whole specified fee amount (`ack_fee + timeout_fee + recv_fee`) and locks that amount in the module's escrow address. When a relayer submits `Ack` message for a particular packet, the module sends the specified amount of `ack_fee` to the relayer from the escrow address and return the specified `timeout_fee` to the contract which issued the original `Transfer` or `SubmitTx` message. In case when relayer submits `Timeout` message, things go the other way around: the relayer is refunded with `timeout_fee` and the contract gets `ack_fee` back.
+When a smart-contract issues `Transfer` or `SubmitTx` message, the fee Module deduct the whole specified fee amount (`ack_fee + timeout_fee + recv_fee`) from contract address or from payer address (if it is defined and there is allowance from payer to contract address) and locks that amount in the module's escrow address. When a relayer submits `Ack` message for a particular packet, the module sends the specified amount of `ack_fee` to the relayer from the escrow address and return the specified `timeout_fee` to the contract (or fee payer) which issued the original `Transfer` or `SubmitTx` message. In case when relayer submits `Timeout` message, things go the other way around: the relayer is refunded with `timeout_fee` and the contract gets `ack_fee` back.
+
+<details>
+    <summary>Details on Fee Payer</summary>
+    
+    1. A fee payer is an address that holds tokens that can be used to pay for the interchain transaction fees.
+
+    2. The fee payer can grant an allowance to a contract address, which allows the contract to use tokens from this address for the fees. Optionally, a limit, expire date, and period can be set, please refer to the [feegrant module's documentation in the Cosmos SDK](https://docs.cosmos.network/v0.46/modules/feegrant/) for more information.
+
+    3. When an interchain transaction is requested by a contract, the feerefunder module checks the allowance in general by using the feegrant module's GetAllowance function.
+    
+    4. The feerefunder module then calls the Accept method on the returned interface with the total fees as an argument to check if the contract has permission to use the required amount of tokens and to deduct them from the allowance.
+    
+    5. If the allowance is enough for the interchain transaction, the contract can execute the transaction.
+    
+    6. The feegrant module is responsible for ensuring that the contract has enough tokens to pay for the fees, if it doesn't have enough tokens, the transaction should return an error message.
+    
+    7. The payer field from the Fee struct is used to specify which address should be used to pay the fees.
+</details>
 
 > **Note:** the minimal amount of fee to be specified for the messages above is defined via parameter [`min_fee`](https://github.com/neutron-org/neutron/blob/9cdd583bd754d0e4d5f2e16d7414cf80151b205d/proto/feerefunder/params.proto#L13) controlled by governance proposal.
 If provided fees are less than `min_fee` parameter, `Transfer` or `SubmitTx` or message will be rejected.

docs/neutron/feerefunder/state.md

@@ -2,7 +2,7 @@
 
 The FeeRefunder module stores one [FeeInfo](https://github.com/neutron-org/neutron/blob/a9e8ba5ebb9230bec97a4f2826d75a4e0e6130d9/proto/feerefunder/genesis.proto#L18) per [`channel_id`, `port_id` and `sequence`](https://github.com/neutron-org/neutron/blob/a9e8ba5ebb9230bec97a4f2826d75a4e0e6130d9/x/feerefunder/types/keys.go#L28).
 `FeeInfo` contains all the necessary info to store data about fees to properly refund relayers and return fees to the original caller of IBC messages:
-* `payer` - stores an address of the smart-contract which issues `Transfer` or `SubmitTx` message;
+* `payer` - stores an address of the smart-contract (or fee payer) which issues `Transfer` or `SubmitTx` message;
 * `packet_id` - stores an info about an IBC packet for which `ack` or `timeout` submission relayers should be refunded;
 * `fee` - stores amount of fee to refund relayers for the submission of IBC packets.