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:
- Allocation: Reserve token capacity for a given payment, using a locked transfer message.
- Finalization: Use the reserved token amount to complete payments, using the unlock message
A mediated transfer may be cancelled and can expire until the initiator reveals the secret.
A mediated transfer is a hash-locked transfer. Currently Raiden supports only one type of lock, a hash time lock. This 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 a number of
N mediators, a mediated transfer will require
10N + 14 messages to complete successfully in the best case. These are:
N + 1locked transfer or refund transfer messages
N + 1unlock
2N + 2processed (one for every message with a balance proof)
N + 2reveal secret
5N + 7delivered
For a simple example with one mediator:
- Alice wants to transfer
ntokens to Charlie, using Bob as a mediator.
- Alice creates a new transfer with:
Lock(n, hash(secret), expiration)
locksroot= updated value containing the new
- 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
SecretRequestmessage to Alice.
- Alice sends the
RevealSecretto 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
ntokens to his side.
- Charlie sends a
RevealSecretmessage to Bob to inform him that the secret is known and acts as a request for off-chain synchronization.
- Bob sends an
Unlockmessage 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
locksrootvalues are updated.
- Bob sends a
RevealSecretmessage to Alice.
- Finally Alice sends an
Unlockto Bob, completing the transfer.
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 - 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.
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.