feat: fee payer

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,30 @@ 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 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>
+
+    * A fee payer is an address that holds tokens that can be used to pay for the interchain transaction fees.
+
+    * 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, expiration 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.
+
+    * When an interchain transaction or transfer message is requested by a contract, the feerefunder module checks the allowance in general by using the feegrant module's GetAllowance function.
+
+    * 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.
+
+    * If the allowance is enough for spending fee, the feerefunder module transfers fee from fee payer address to the module's escrow address and saves the fee payer address in state by PacketID.
+
+    * Then interchain transaction or transfer message is sent to the IBC module.
+
+    * When the IBC module receives the Ack or Timeout message, the module sends the specified amount of fee to the relayer from the escrow address and return the rest of fees to the fee payer's address.    
+
+</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 the fee payer address (smart contract or other fee payer) which will be refunded after the IBC packet is processed;
 * `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.