STREAMing Money and Data Over ILP
STREAM is the new TCP for Interledger. It makes building Interledger applications easier by splitting payments into packets, sending them over ILP, and automatically reassembling them for you. STREAM, or the Streaming Transport for the Realtime Exchange of Assets and Messages, is designed to be used whenever you want to send streaming micropayments or larger discrete payments. This tutorial will show you how to:
- Establish a connection between a STREAM client and server
- Send streaming micropayments or a larger payment over the connection
- Send data over the connection (instead of over the internet 🤔)
If you want to learn more about the STREAM protocol, check out the RFC.
Install STREAM
You’ll need a local moneyd running and Node.js ≥ v8.10.
You can install the STREAM module in your Node.js project by running:
npm install --save ilp-protocol-streamOr git clone the repo to run the example from there.
Listening for Connections
STREAM servers listen for incoming connections established over ILP. When you call await createServer({ plugin }) it connects to the given plugin and waits for ILP packets (ilp-plugin is used below to connect to moneyd).
The server uses generateAddressAndSecret() to generate a unique ILP address and shared secret for each client, which will be used to encrypt data and generate fulfillments for ILP packets. STREAM does not handle communicating the address and secret to the client, so this must be done using an external encrypted communication channel (like an HTTPS request/response in the case of SPSP).
If you notice the connection.on('stream'... line, that’s included because each connection can include many separate streams of money and data. Streams are used as a flexible encapsulation for payments and messages (you can read more about this here).
Connecting to a Server
Clients connect using createConnection once they have the ILP address and shared secret from the server.
The streams returned by connection.createStream expose the Node.js Stream API for sending data. When you want to send money, you call sendTotal with the total amount you want to send on that stream (so in this example, 200 units will be sent, not 300).
Running the two examples together (see the full script here), you’ll see:
Multiplexed Bidirectional Streams
As you can see above, STREAM connections consist of any number of streams. This is inspired by QUIC, a newer alternative to TCP, that multiplexes multiple logical streams of data over a single connection between the client and server. The lightweight stream abstraction can either be used for ongoing interactions or to frame larger requests or responses.
In addition to multiplexing, STREAM also provides for sending money or data in both directions. A client can send money to the server, or vice versa. An example of a server sending money to the client would be something like the gift card server that
came up with.Sending Data Over ILP
STREAM can be used to send messages directly through ILP, rather than over the internet. Now, why would you want to do that? For some applications, it may be easier to keep messages together with the payment (like a memo). There are also some crazier, more interesting possibilities that come from sending data over ILP, but we’ll explore those further in a future post.
If you have any questions about STREAM or want to use it in an application, feel free to ask questions on Gitter or one of our community calls!
