paradigm-connect v0.1.12

ParadigmConnect

ParadigmConnect provides a convenient way to interface with the Paradigm OrderStream and the Paradigm OrderGateway.

Getting Started

ParadigmConnect is currently only available as a Node.js module. Install with npm:

npm install --save paradigm-connect

Paradigm is dependent on a web3 connection, and you will need to require it.

const Web3 = require('web3');
const Paradigm = require('paradigm-connect');

web3 = new Web3(web3.currentProvider);

web3.eth.net.getId().then((networkId) => {
  // ... following code goes here.
}

Paradigm

The Paradigm class is the top level object through which you will interact with the library. It takes a variety of initialization parameters that you will need to provide.

  const paradigm = new Paradigm({ provider: web3.currentProvider, networkId: networkId });

Order

The Order class is what you will use to construct and sign orders which you'd like to post to the Paradigm OrderStream to be broadcast to the network.

  const Order = paradigm.Order;
  let order = new Order({ ... });

The Order constructor takes a javascript object that must contain the following things:

• The subcontract address as subContract
• The maker's address as maker
• The "maker values" object as makerValues

Additionally, makerArguments and takerArguments can be provided or pulled from the SubContract.

An example can be seen here.

Order has a method called make() which will sign the order on behalf of the maker.

  order.make();

This call will append three pieces of a cryptographic signature to the order's makerValues field: v, r, and s, which will be passed to the smart contract layer when the order is eventually "taken".

Additionally, these will be added directly to the order object as a method makerSignature() for convenience purposes.

  order.makerSignature() // => { v: '...', r: '...', s: '...' }

Once an order has been signed by the maker, you can recover their Ethereum address by calling:

  order.recoverMaker() // => '0x40a...'

Similarly, the Paradigm OrderStream requires that whomever is going to post the order (might be the maker, might be someone else) also signs the order. To that end, you can use the prepareForPost() method.

  let poster = ... // get an Ethereum address
  order.prepareForPost(poster);

This will add a posterSignature to the order in a similar way that we added the makerSignature. One key difference is that this does not get added to the makerValues by default. The poster is primarily a concern of the OrderStream.

Finally, once an order is made, posted, and discovered by another party, it can be "taken", which posts the order to the on-chain OrderGateway with the taker's details.

  order.take(taker, takerValues);

When an order has been generated via the OrderStream or other sources and order status is unknown isValid and amountRemaining can be used to get status information from the subContract.

  if(order.isValid() &&  order.amountRemaining() > 0) {
    order.take(taker, takerValues);
  }

For a more detailed explanation, check out the Order docs.

OrderStream

The OrderStream class provides convenient methods for interacting with the Paradigm OrderStream (OS) Network.

There are two primary methods that you should be aware of: add() and listen().

The add() method can be called once an order has been signed by the poster.

  const orderStream = paradigm.orderStream;
  orderStream.add(order);

The listen() method will connect you to the OS via web sockets to pick up incoming order events.

  orderStream.listen((message) => { console.log(message) });

Here is an example of both in action for a front-end web application:

  order.make().then(() => {
    order.prepareForPost(currentUser).then(() => {
      orderStream.add(order);
    })
  });

  // ...

  orderStream.listen((message) => {
    console.log(message);
    $('#orders').append(`<div class='card'><div class='card-body'>${message.data}</div></div>`);
  });

For a more detailed explanation, check out the OrderStream docs.