Orinoco Payment Channels

Orinoco payment channels are an implementation of the payment channel concept as laid out in the last article. This article describes how to use them, but first a couple of important notes:

For Test Only

At this point Orinoco payment channels are available for test purposes. Specifically, Orinoco is hard-coded to work only on the Ropsten test network. This means that none of the actions you undertake when testing Orinoco can have any real monetary impact. Orinoco expect to make this payment channel solution available on the live Ethereum network by the end of 2017.

Beta Software

The software produced by Orinoco as listed in this article is in beta. It is fully functional and has been tested internally but there may well be issues with it. If you find any such issues please report them; thank you.


Orinoco payment channels are composed of two components. The first component is a set of commands for most common operating systems and architectures. Details on how to download and install these are available on the Orinoco Payments wiki. The commands allow the use of payment channels without requiring knowledge of Ethereum, smart contracts in general, or the Orinoco smart contract in particular. That said, in the test environment there is a bit of work required to obtain test addresses and some Ropsten Ether with which to play with the channels. Again, information on how to do this is provided in the wiki.

Note that by default the commands connect to Orinoco’s Ropsten node. This means that you do not need to be running a Ropsten node yourself to use the payment channels. If, however, you are running a Ropsten node you can connect to it by providing either the IPC or RPC port to the command (e.g. /home/user/.ethereum/geth.ipc or http://localhost:8545.).

All commands have built-in help; to access it call the relevant command with the ‘-h’ argument.

The second component of Orinoco is a smart contract deployed on the Ethereum network. This contains the logic for opening and closing contracts and distributing funds according to information presented in payment promises. Users do not, in general, need to be aware of its inner workings as it is deployed and maintained by Orinoco.

Orinoco payment channels are Ether payment channels, as opposed to token payment channels. As such, any time that the words “amount” or “funds” are used they refer to Ether.

Unmanaged Payment Channels

The term “unmanaged payment channel” will be used a number of times in this article. The term will be explained more fully in time, but the important thing to understand about unmanaged payment channels is that the entire operation, from the sender opening the payment channel to the withdrawal of the final balances, only consists of three participants: the sender, the recipient and the smart contract.

Opening a Payment Channel

Any user can open a payment channel to any other user by sending the appropriate transaction to the payment channel smart contract. To do so they need to choose the address from which they will deposit funds and the amount of funds to deposit, along with the address of the recipient of any resultant payment. They will also need to choose the maximum amount of time they wish the channel to remain open before it becomes eligible for expiration.

Orinoco allows users to open payment channels with the oriopen command.

Querying the status of a Payment Channel

Any user can query the existence and status of a payment channel. To do so they just need the sender’s and recipients’ addresses. In return they will find out if a channel is active, the amount of funds deposited, and when the channel is due to expire.

Note that due to payment promises being off-chain there is no way that an unmanaged payment channel can provide information on the amount of the deposit that has been promised to date.

Orinoco allows users to query the status of payment channels with the oriquery command.

Creating a Payment Promise

The sender in a payment channel can create a payment promise. To do so they just need the sender’s and recipient’s addresses, along with the amount of funds they wish to promise.

Once the sender has created a payment promise for an unmanaged payment channel it is up to them to send the promise to the recipient. As such, although the sender does not need to send an Ethereum transaction as part of the process they will need network connectivity and some agreed-upon mechanism for transmitting the promise.

Orinoco allows users to create payment promises with the orisend command.

Validating Payment Promises

The recipient of a payment promise cannot trust it. Instead they should carry out a string of checks to ensure that they are happy to accept the promise.

The first thing to do is to verify the signature of the promise. This ensures that the data in the promise has not been tampered with, and gives the recipient the confidence that they can trust the information in the promise. More importantly, it gives the recipient confidence that the payment channel smart contract will accept the information in the promise.

The recipient should then ask the following questions about the promise: is the sender’s address correct? Is the recipient’s address correct? Is there a payment channel active between the sender and recipient, and is there a long enough duration between the current time and the channel’s expiry? Can the amount promised be covered by the deposit in the channel?

Orinoco allows users to validate payment promises with the orivalidate command.

Note that the recipient needs to confirm that they are happy with the amount in the promise. This usually comes down to two questions: is the amount in the promise more than the last promise presented by the sender, and is the difference between the amount in the last promise and the amount in this promise enough for the recipient to carry out whatever function the payment is for? These last two questions are out of scope for unmanaged payment channels and should be decided by the recipient manually.

Closing a Payment Channel

The recipient of a payment channel is able to close an open channel at any time by sending the appropriate transaction containing a valid promise to the payment channel smart contract.

When a payment channel is closed the funds are distributed as follows:

  • Deposit amount less promise amount returns to the sender
  • 99% of the promise amount goes to the recipient
  • 1% of the promise amount goes to the contract

Orinoco allows payment channel recipients to close a channel with the oriclose command.

Expiring a Payment Channel

The sender of a payment channel is able to expire an open channel after the channel’s expiry time has passed by sending the appropriate transaction to the payment channel smart contract. Expiring a channel removes it from the active payment channels list, meaning that any and all payment promises related to the channel can no longer be redeemed.

When a payment channel is expired all funds are returned to the sender.

Orinoco allows payment channel senders to expire an eligible channel with the oriexpire command.

Account Balances

As mentioned in the previous article, funds are not sent directly to the sender and the recipient whenever a payment channel is closed or expired. Instead they are allocated to the relevant account’s balance within the smart contract ready for withdrawal.

Orinoco allows users to see their balance with the oribalance command.

Withdrawal of Balance

Any user can withdraw their balance by sending the appropriate transaction to the payment channel smart contract.

Orinoco allows users to withdraw their balance with the oriwithdraw command.

Command State Diagram

Using the information above the state diagram from the previous article can be annotated with the commands used to transition states:

State diagram for unmanaged payment channels with Orinoco commands

As mentioned earlier, the commands and instructions on how to install and use them are available on the Orinoco wiki. Any and all comments, suggestions or issues with the process or use of payment channels are appreciated and can be made on the Orinoco issues list.

The next article will undertake a critical examination of unmanaged payment channels as laid out over this and the prior two articles. It will discuss some of the uses for unmanaged payment channels, and also some of their limitations.

Like what you read? Give Jim McDonald a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.