Using Raiden on Mainnet

Warning

Before you start, make sure Raiden is correctly installed and configured by following the installation instructions.

Also make sure you have read and understood the safe usage guidelines before starting to use Raiden.

Get Whitelisted Tokens

The Raiden Coruscant release puts a certain limit on the amount of tokens that can be deposited into a channel. This is to minimize potential loss of funds in case of bugs.

The global limit per token network is approximately $5000000.
The limit per channel side is approximately $5000.

Note

These dollar values of these limits are calculated at contract deployment time and vary with the exchange rates of the underlying tokens.

W-ETH

W-ETH stands for Wrapped Ether and is essentially Ether that has been packaged to become ERC-20 compatible.

There are several ways in which you can get W-ETH from your Ether.

Using the contract directly
Trade the token on an exchange, e.g. Uniswap

DAI

DAI is a popular stablecoin. Visit Maker DAO for further information on how to purchase it.

Deposit Tokens to the UDC

To do mediated transfers we need to have RDN (Raiden Network Tokens) in the UDC (User Deposit Contract) for paying the monitoring and pathfinding services. This section will describe how to add Raiden Network Tokens to the UDC by making a call to the User Deposit endpoint of the Raiden API. The following POST request will deposit 100 RDN tokens to the UDC:

curl -i -X POST \
http://localhost:5001/api/v1/user_deposit \
-H 'Content-Type: application/json' \
--data-raw '{"total_deposit": "100000000000000000000"}'

Note

Raiden utilizes a RESTful API where all URL paths starts with /api/ followed by a version number. The current API version is 1 and therefore all requests begins with /api/v1/.

The request will take a couple of minutes, because two on-chain transactions are performed: Approving the UDC to use RDN and Depositing RDN to the UDC. When successfully completed the API will respond with a transaction hash.

Open a Channel

Opening a channel and depositing tokens in it allows you to transfer these tokens to your channel partner - and indirectly to other nodes connected to you partner. To open a channel, a PUT request is made to the channels endpoint that includes a JSON object containing:

The address of the node you’d like to open the channel with. If you don’t know to which partner you should connect, have a look at Find suitable partner nodes.
The token address. We use W-ETH token in this example.
The amount of tokens you want to deposit in the channel (Remember that it is always possible to deposit more tokens later). 1 W-ETH is equivalent to 10^18 WEI.
The settle timeout period which corresponds to the number of blocks that have to be mined before a closed channel can be settled.

curl -i -X PUT \
http://localhost:5001/api/v1/channels \
-H 'Content-Type: application/json' \
--data-raw '{"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "total_deposit": "1337", "settle_timeout": "500"}'

This will create a new channel and a successful request will return you the following response object:

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "token_network_address": "0x3C158a20b47d9613DDb9409099Be186fC272421a",
    "channel_identifier": "99",
    "network_state": "unknown",
    "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
    "token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700",
    "balance": "1337",
    "total_deposit": "1337",
    "total_withdraw": "0",
    "state": "opened",
    "settle_timeout": "500",
    "reveal_timeout": "50"
}

As you can tell by the response object a channel identifier has been generated. This means that there now is a channel with that identifier inside the token network.

We’re now ready to start sending W-ETH tokens!

Make a Payment

Payments are made from the payments endpoint via a POST request that has to include:

The address of the W-ETH token as a path parameter.
The address of the node receiving your payment as a path parameter.
The amount you would like to pay as a body parameter.

curl -i -X POST \
http://localhost:5001/api/v1/payments/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/<target_address> \
-H 'Content-Type: application/json' \
--data-raw '{"amount":"42"}'

You will receive a success response once the payment goes through.

Payments in Raiden can be done either as:

Direct payments
Mediated payments

Note

It is possible to receive tokens through the Raiden Network without having any initial Ether or tokens. The receiving peer just needs to have a Raiden full node running and the sender must be willing to pay the fees for the on-chain transactions.

Direct payments

You can open a channel directly with any node you know the address of. You might want to open a direct channel if you know you’ll be making frequent payments to a specific peer. Each payment will then go straight to that peer via the open channel. This is called a direct payment.

Mediated payments

If you don’t have a direct channel to a node for whom you want to send a payment, Raiden will try to find a path from you to the recipient node through the network of channels. This is called mediated payments.

Mediated payments are a powerful feature in Raiden since it lets you pay anyone in the network by leverging the path of connected payment channels.

By making no more than two API calls - one call to join the token network and one call to make the payment - we can send payments to anyone who is part of the W-ETH token network.

Deposit Tokens

You deposit in a channel by making a PATCH request to the channels endpoint that includes:

The address of the W-ETH token as a path parameter.
The address of the partner node as a path parameter.
The amount of tokens you want to deposit in the channel as a body parameter.

curl -i -X PATCH \
http://localhost:5001/api/v1/channels/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/<partner_address> \
-H 'Content-Type: application/json' \
 --data-raw '{"total_deposit":"4000"}'

Note

Notice how we are specifying the total_deposit in the request and not only the amount we want to “top-up” with. This means that if we initially deposited 2000 WEI and want to increase the amount with 2000 we would need to make a total deposit of 4000 WEI.

This is done to prevent requests that are sent repeatedly (by accident or as part of an attack) from having any further consequences.

View Channel Status

To view the status of a channel you have to make a GET request to the channels endpoint and provide:

The address of the W-ETH token as a path parameter.
The address of the partner node as a path parameter.

curl -i \
http://localhost:5001/api/v1/channels/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C

This will return the following response object:

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2",
    "channel_identifier": "0xa24f51685de3effe829f7c2e94b9db8e9e1b17b137da5",
    "network_state": "unknown",
    "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
    "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "balance": "3958",
    "state": "open",
    "settle_timeout": "500",
    "reveal_timeout": "50"
}

As you can tell by the response, the current balance in the channel is 3958 which matches the two deposits and one payment you’ve just made (2000 + 2000 - 42 = 3958 ).

Mediation Fees

What are Mediation Fees?

Raiden lets users pay anyone in the network by using a path of connected payment channels to mediate the payment. Mediating nodes, which are the nodes between the initiator and target on the selected payment path, can earn mediation fees.

Mediation fees are paid by the initiator by slightly increasing the amount of tokens above the amount intended for the target. This also means that mediation fees are always paid in tokens of the kind that is being transferred.

Benefits of Mediation Fees

Mediation fees increase the health of the payment network by:

incentivizing users to run mediating nodes
choosing lower fees for routes that balance the involved payment channels

A healthy payment network allows cheap and reliable payments for users. So even though users have to pay mediation fees when initiating payments, these fees are ultimately to their own benefit.

Calculation of Mediation Fees

Each mediator can choose a fee schedule for mediating payments. This fee schedule consists of three parts:

a flat fee per mediation
a fee proportional to the mediated amount of tokens
an imbalance fee that increases when the payment exhausts channel capacity, which might prevent the channel from being used in future payments

The sum of these fee components represents the fee for a single mediator. Summing the fees for all mediators in the payment route yields the total amount of mediation fees for a payment.

Since the fees can change between the time of fee calculation by the initiator (or the pathfinding service on his behalf) and the time of mediation, a safety margin is added on top of the mediation fee. Without this, a mediator might drop the payment because its imbalance fee has increased due to another payment taking place within this time span.

For more details on the calculation of fees, see the blog post and the architecture decision record.

Default Fee Schedule

You don’t need to configure the fee schedule yourself if you don’t want to, since Raiden comes with a default fee schedule. The default values are

flat fee
- DAI: 10^-6 DAI
- W-ETH: 10^-8 W-ETH
proportional: 0.4% of the mediated tokens
imbalance: up to 0.3% of the mediated tokens (usually much less)

and apply to all transferred tokens, unless specified differently by the user.

Changing Your Fee Schedule

As with all Raiden settings, you can get a short summary of the available options by running raiden --help:

$ raiden --help

...

Mediation Fee Options:
  --flat-fee <ADDRESS INTEGER RANGE>...
        Sets the flat fee required for every mediation in wei of the mediated token
        for a certain token address. Must be bigger or equal to 0.
  --proportional-fee <ADDRESS INTEGER RANGE>...
        Mediation fee as ratio of mediated amount in parts-per-million (10^-6) for a
        certain token address. Must be in [0, 1000000].
  --proportional-imbalance-fee <ADDRESS INTEGER RANGE>...
        Set the worst-case imbalance fee relative to the channels capacity in
        parts-per-million (10^-6) for a certain token address. Must be in [0, 50000].
  --cap-mediation-fees / --no-cap-mediation-fees
        Cap the mediation fees to never get negative.  [default: True]

The first three parameters each set one of the three fee components. Each parameter takes two values: a token address and a fee value. When mediating a payment for the given token, the corresponding fee value will be used. Here are some examples of fee parameters that could be used for the DAI token:

--flat-fee 0x6B175474E89094C44Da98b954EedeAC495271d0F 1000000000000000

Ask for 1000000000000000/10^18 = 0.001 DAI per mediation

--proportional-fee 0x6B175474E89094C44Da98b954EedeAC495271d0F 1000

Ask for 1000/10^6 = 0.1% of the mediated tokens

--proportional-imbalance-fee 0x6B175474E89094C44Da98b954EedeAC495271d0F 10000

Apply up to 10000/10^6 = 1% of the mediated tokens as imbalance fee. This fee will be positive when increasing imbalance and negative when decreasing imbalance. It will usually stay far below this maximum value, because the maximum applies only when the channel goes from perfectly balanced to completely imbalanced due to a single payment.

Since imbalance fees can be negative to incentivize payments that balance your channels, the sum of all three mediation fee components could go negative, too. This can make sense, but it is counter-intuitive for the mediating user and it might open up certain classes of attacks against mediators. For these reasons, the total mediation fee per mediator is capped to not go below zero by default. If you want to allow the fee total to be negative, use the --no-cap-mediation-fees flag.

Frequently Asked Questions

Why Does the Target Receive More Tokens Than Expected?

As noted in the “Calculation of Mediation Fees” section above, a small safety margin is added on top of the mediation fees when initiating a payment. This safety margin is only used by the mediators when the channel balances change to the initiator’s disadvantage immediately before initiating the payment. So usually this margin is not or only partially used up before reaching the payment target. The remainder reaches the target along with the intended payment amount itself, thereby slightly increasing the amount received by the target.

What does “Payment exceeded the maximum fee limit” mean?

Currently the Raiden client cancels payments that would require more than 20% of the transferred amount in fee costs. This is the maximum fee limit. As noted in “Default Fee Schedule”, there are fees for both the DAI and W-ETH token networks by default.

This means that the transferred amount has to be big enough, so that the fees do not surpass 20% of the transferred amount. This results in the following minimum amounts for the token networks when mediation is used:

DAI: Min. 0.00001 DAI (10^-5)
W-ETH: Min 0.0000001 W-ETH (10^-7)

As direct payments do not need mediation fees, this does not apply for direct transfers.