# Mediation Fees¶

## Overview¶

Mediation fees are used to incentivize people to mediate payments. There are (currently) three components:

**Flat fees**: absolute fees paid per mediation.**Proportional fees**: fees that grows proportionally to the mediated amount.**Imbalance fees**: fees that can be both positive or negative, which are used incentivize mediations which put the channels into a state desired by the mediator.

Each of these fees is calculated by the mediator for both the incoming and outgoing channel. The sum of all fee components for both channels is the total mediation fee for a single mediator.

For an explanation why this fee system has been chosen, please consult the architectural decision record.

## Imbalance Fees¶

The imbalance fee is calculated from an Imbalance Penalty (IP) function. \(\mathit{IP}(\mathit{cap})\) describes how much a node is willing to pay to bring a channel from the capacity \(\mathit{cap}\) into its preferred capacity.

Mediators can choose arbitrary IP functions to describe which channel capacities are preferable for them and how important that is to them. If a node prefers to have a channel capacity of 5 while the total capacity of that channel is 10 (so that it could mediate up to 5 tokens in both directions) the IP function might look like

```
IP
^
|X X
|X X
| X X
| X X
| X X
| X X|
| X X |
| X X |dIP = IP(cap_after) - IP(cap_before)
| XX XX |
| XX XX----->
| XXX amount
+-----------+--+-----+--> Capacity
0 5 6 9
```

If the node currently has a capacity of 6 and is asked to mediate a payment of 3 tokens coming from this channel, it will get into the less desired position of 9 capacity. To compensate for this, it will demand an imbalance fee of \(i = \mathit{IP}(9) - \mathit{IP}(6)\). If the situation was reversed and the capacity would go from 9 to 6, the absolute value would be the same, but this time it would be negative and thus incentivize moving towards the preferred state. By viewing the channel balances in this way, the imbalance fee is a zero sum game in the long term. All tokens which are earned by going into a bad state will be spent for moving into a good state again, later.

The flexible shape of the IP function allows to encode many different mediator intentions. If I use a channel solely to pay (apart from mediation), having more free capacity is always desired and any capacity gained by mediating in the reverse direction is welcome. In that case, the IP function could look like

```
IP
^
|X
|X
| X
| X
| XX
| XX
| XX
| XX
| XX
| XXX
| XXX
+------------------------> Capacity
```

## Nomenclature¶

In this description a simple mediation node is assumed. The incoming channel (for the mediated payment) is also called **payer channel** and the outgoing channel is also called **payee channel**. This scenario is shown in the following graphic:

```
c
--> a --> (M) --> b -->
```

- \(a\) is the locked amount of the payer channel. This locked amount includes fees.
- \(b\) is the locked amount of the payee channel. This locked amount includes fees for further hops.
- \(c\) is a helper value for making the calculation of mediation fees simpler. It is not exposed to the user.

In the calculation the different fees are used.

- \(f\) is the flat fee
- \(i\) is the imbalance fee

## Converting per-hop proportional fees in per-channel proportional fees¶

User usually think about deducting mediation fees as an atomic action, so it’s
easier to let them define a *per-hop* proportional mediation fee (called
\(p\)). However, this setting then needs to be converted into a
*per-channel* proportional fee (called \(q\)).

## Fee calculation¶

The mediation fees for a payment amount \(x\) for a single channel are calculated as

where the imbalance fee for that channel is defined as

and \(t\) is the balance of the that channel. The amount \(x\) is positive for incoming channels and negative for outgoing channels to reflect the change in balance. The values \(\mathit{flat}\), \(\mathit{q}\) and the function \(\mathit{IP}\) comprise the fee schedule for the channel.

To get the mediation fee for a single mediator, we have to sum up the fees across both involved channels:

When the mediator has enabled fee capping (which is the default), the result will not go below zero.

### Forward calculation (used in the mediator)¶

A mediator already knows \(x_{in}\), but knows neither \(x_{out}\) nor \(\mathit{fee}_m\) both of which can’t be calculated directly without knowing the other. So instead of a directly calculating them, we solve the equation we get by equating (1) and (2).

The only unknown in this equation is \(x_{out}\) which makes this equivalent to finding the zero of

Due to the constraints [1] on the fee schedule, this function is monotonically decreasing. Thus there is only a single solution and it can be found easily by following the slope into the right direction. Additionally, the current implementation uses the fact that the mediation fees are a piecewise linear function by only searching for the section that includes the solution and then interpolating to get the exact solution.

[1] | `PROPORTIONAL_MED_FEE_MAX` + 2 * `MAXIMUM_SLOPE` must be strictly below 1, where `MAXIMUM_SLOPE` is the highest absolute slope allowed at any point of the IP function. |

### Backward calculation (in the PFS)¶

This works analogous to the forward calculation with the only difference that \(x_{in}\) is the unknown variable and \(x_{out}\) is given as input.

### Example¶

Let’s assume no fees for the incoming channel and:

- \(\mathit{flat}_{out} = 100\)
- \(q_{out} = 0.1\)
- \(x_{in} = 1200\)
- \(x_{out} = 1000\)

Now forward and backward calculation should let us confirm that \(x_{in}\) and \(x_{out}\) are correct.

**Mediator**

\(x_{in}\) is known:

**PFS**

\(x_{out}\) is known:

Due to the simple example this is true for any \(x_{in}\). If there was a scheduling involving proportional or imbalance fees, we would need to find the intersection with the x-axis as above for the mediator.

## Default Imbalance Penalty Curve¶

### Requirements¶

In order to make it easier to enable imbalance fees, the Raiden client
includes a default imbalance penalty (IP) function that can be configured by a single
parameter (`--proportional-imbalance-fee`

on the Raiden CLI).

The function is chosen to have the following properties:

- It is convex, symmetric and defined for all values in the range \([0, \mathit{capacity}]\)
- The penalty is zero when both channel participants have the same balance.
- The highest point should have a given value \(f(0) := c\).
- The slope should not exceed \(s := 0.1\) to avoid awarding extreme incentives for transferring tokens.

To get reasonable values for channels with greatly varying capacity, the maximum \(c\) is chosen in proportion to the channel capacity.

### Used Function¶

One function that fulfills these requirements is

where

when the offset \(o\) is chosen to be half the total channel capacity (own balance + partner balance).

### Derivation of \(a\) and \(b\)¶

Starting with the function formula and its derivative

as well as the slope constraint

from the requirements, we can deduce the values for \(a\)

and \(b\)