Mediated transfers

Overview

Nodes can use a mediated transfer to send payments to another node without opening a direct channel to it.

A mediated transfer is done in two stages, usually through multiple channels:

A mediated transfer may be cancelled and can expire until the initiator reveals the secret.

Mediated Transfers

A mediated transfer is a hash-time-locked transfer. Currently raiden supports only one type of lock. The lock has an amount that is being transferred, a secrethash used to verify the secret that unlocks it, and a lock expiration to determine its validity.

Mediated transfers have an initiator and a target and a number of mediators in between. Assuming N number of mediators, a mediated transfer will require 10N + 16 messages to complete. These are:

For a simple example with one mediator:

  • Alice wants to transfer n tokens to Charlie, using Bob as a mediator.
  • Alice creates a new transfer with:
    • transferred_amount = previous transferred_amount, unchanged
    • lock = Lock(n, hash(secret), expiration)
    • locked_amount = previous locked_amount plus n
    • locksroot = updated value containing the new lock
    • nonce = previous nonce plus 1.
  • Alice signs the transfer and sends it to Bob.
  • Bob forwards the transfer to Charlie.
  • Charlie requests the secret that can be used for withdrawing the transfer by sending a SecretRequest message to Alice.
  • Alice sends the RevealSecret to Charlie and at this point she must assume the transfer is complete.
  • Charlie receives the secret and at this point has effectively secured the transfer of n tokens to his side.
  • Charlie sends a RevealSecret message to Bob to inform him that the secret is known and acts as a request for off-chain synchronization.
  • Bob sends an Unlock message to Charlie. This acts also as a synchronization message informing Charlie that the lock will be removed from the list of pending locks and that the transferred_amount and locksroot values are updated.
  • Bob sends a RevealSecret message to Alice.
  • Finally Alice sends an Unlock to Bob, completing the transfer.

Note

The number of mediators can also be zero. There are currently no dedicated message types for direct transfers in Raiden, so a direct transfer is just realized as a mediated transfer with no mediators.

Mediated Transfer - Happy Path Scenario

In the happy path scenario, all Raiden nodes are online and send the final balance proofs off-chain.

Mediated Transfer Good Behaviour

Mediated Transfer - Unhappy Path Scenario

In case a Raiden node goes offline or does not send the final balance proof to its payee, then the payee can register the secret on-chain, in the SecretRegistry smart contract before the secret expires. This can be used to unlock the lock on-chain after the channel is settled.

Mediated Transfer Bad Behaviour

Restrictions to mediated transfers

Limit to number of simultaneously pending transfers

The number of simultaneously pending transfers per channel is limited. The client will not initiate, mediate or accept a further pending transfer if the limit is reached. This is to avoid the risk of not being able to unlock the transfers, as the gas cost for this operation grows with the number of the pending locks and thus the number of pending transfers.

The limit is currently set to 160. It is a rounded value that ensures the gas cost of unlocking will be less than 40% of Ethereum’s traditional pi-million (3141592) block gas limit.