payene / ilp-protocol-stream

Interledger Transport Protocol for sending multiple streams of money and data over ILP

ILP/STREAM

Interledger Transport Protocol for sending multiple streams of money and data over ILP.

STREAM is the recommended Transport Protocol to use for most Interledger applications.

The protocol allows a "client" and "server" to establish a bidirectional connection through Interledger that can be used to send money and data. This module handles authentication, encryption, flow control (making sure one party doesn't send more than the other can handle at once), and congestion control (avoiding sending more packets than the network can handle).

Install

Requires Node >= v8.10.

npm install ilp-protocol-stream

Usage

These snippets assume you are running a local moneyd.

You'll need ilp-plugin to run the example.

npm install ilp-plugin

See example.js for a runnable example, or paste the snippets into your own node project below. You'll need to provide a means of getting the shared secret from Server to Client.

Client:

Clients connect with the destinationAccount and sharedSecret generated by a Server.

const { createConnection } = require('ilp-protocol-stream')
const getPlugin = require('ilp-plugin')

const { destinationAccount, sharedSecret } = getThisFromTheServerSomehow()

async function run () {
  const connection = await createConnection({
    plugin: getPlugin(),
    destinationAccount,
    sharedSecret
  })

  const stream = connection.createStream()
  stream.write('hello\n')
  stream.write('here is some more data')
  await stream.sendTotal(100)
  await stream.sendTotal(200)
  stream.end()
}

run().catch((err) => console.log(err))

Server:

const { createServer } = require('ilp-protocol-stream')
const getPlugin = require('ilp-plugin')

async function run () {
  const server = await createServer({
    plugin: getPlugin()
  })

  // These need to be passed to the client through an authenticated communication channel
  const { destinationAccount, sharedSecret } = server.generateAddressAndSecret()

  server.on('connection', (connection) => {
    connection.on('stream', (stream) => {

      // Set the maximum amount of money this stream can receive
      stream.setReceiveMax(10000)

      stream.on('money', (amount) => {
        console.log(`got money: ${amount} on stream ${stream.id}`)
      })

      stream.on('data', (chunk) => {
        console.log(`got data on stream ${stream.id}: ${chunk.toString('utf8')}`)
      })

      stream.on('end', () => {
        console.log('stream closed')
      })
    })
  })
}

run().catch((err) => console.log(err))

API

See the full API docs at: https://interledgerjs.github.io/ilp-protocol-stream

The most important functions and classes to look at are:

• createConnection - open a Connection to a Server
• Server - class used to listen for incoming Connections
• Connection - class that manages the communication between a Client and a Server
• DataAndMoneyStream - stream class that can be used to send/receive data and money

Contribute

PRs, new ideas, and questions are very welcome!

Please feel free to open issues to discuss any problems you run into or suggestions you have.

License

Apache-2.0