fincontracts-lib

Copyright (C) 2017 - Maciej Żurad, University of Luxembourg

Node.js package for interacting with Fincontracts deployed on the Ethereum blockchain.

• For more information about Fincontracts see the paper: Findel: Secure Derivative Contracts for Ethereum.
• For the Smart Contract implementation in Ethereum, see: https://github.com/cryptolu/findel
• An example project implementing a CLI using this package is hosted at: https://github.com/asiron/fincontracts-cli

Installation

Run this command in your project's root directory to install the package.

npm install --save fincontracts-lib

You can now import the package using:

const finlib = require('fincontracts-lib');

Getting started

In order to use most of the functionality of fincontracts-lib, you will need:

• an instance of web3.js provider connected to an Ethereum node, e.g. geth.
• an instance of FincontractMarketplace smart contract, which was compiled and deployed on the blockchain. We usually refer to that instance in the documentation, when we say FincontractMarketplace
• an interface/class of Gateway smart contract, which couldn't be deployed to the blockchain as its an abstract smart contract, but must be instantiated on demand with a given Gateway address during Fincontract processing, such as execution

Documentation

Documentation is hosted here thanks to ESDoc! Alternatively, you can clone this repo and build documentation locally. If you wish to do so, run:

npm run docs

Now, you can simply navigate to docs/index.html and browse the documentation.

Projects

fincontract-cli is an example project which uses fincontracts-lib. It contains scripts for running your own private blockchain, deploying smart contracts and generating JavaScript files with instantiation scripts necessary for using this library as already stated.

Examples

These examples show core functionality of the fincontracts-lib package. Everytime, we refer to these variables, we mean:

• fincontract is Fincontract's description tree
• marketplace is FincontractMarketplace smart contract instance
• web3 is web3.js instance connected to an Ethereum node

Deployer

Deployer allows for Fincontract deployment and issuence. Following example deploys the Fincontract and issues it to everyone.

const finlib = require('./fincontracts-lib');
try {
  const d = new finlib.Deployer(marketplace, web3);
  const id = await d.issue(fincontract, '0x0');
catch (err) {
  console.log(err);
}

Evaluator

Evaluator allows for evaluation of an instantiated Fincontract. The following example first pulls the Fincontract from the blockchain and then evaluates it using estimate method and converts all currencies to USD

const finlib = require('./fincontracts-lib');
const f = new finlib.Fetcher(marketplace);
const e = new finlib.Evaluator(web3, gateway);
const method = `estimate`;
const id = '<32 byte address of a deployed Fincontract>';
try {
  const fincontract = await f.pullFincontract(id);
  const evaluated   = await e.evaluate(fincontract.rootDescription, {method});
  const currencies  = finlib.Currency.convertToJSON(evaluated);
  const exchanged   = await finlib.Currency.changeAllCurrencies('USD', currencies);
  console.log(JSON.stringify(evaluated));
  console.log(JSON.stringify(exchanged));
} catch (err) {
  console.log(error(err));
}

Executor

Executor allows for execution of a deployed Fincontract given its address. It also allows for choosing a sub-fincontract if the top-level node is an OR node. For more details, consult the documentation ( Executor#choose ) The following example joins the Fincontract if possible.

const finlib = require('./fincontracts-lib');
const exec = new finlib.Executor(marketplace, gateway, web3);
const id = '<32 byte address of a deployed Fincontract>';
try {
  const executed = await exec.join(id);
  console.log(JSON.stringify(executed));
} catch (err) {
  console.log(err);
}

Parser

Parser can parse a String and return a Fincontract description, which then can be evaluated or deployed.

const finlib = require('./fincontracts-lib');
try {
  const p = new finlib.Parser();
  const expression = 'And(Give(Scale(11,One(USD))),Scale(10,One(EUR)))';
  const desc = await p.parse(expression);
} catch (err) {
  console.log(err);
}

Serializer

Serializer can take a Fincontract and serialize it to String. It serializes, all properties: owner, issuer and the proposedOwner as well as serializes the Fincontract's description tree into String, which can be easily parsed

const finlib = require('./fincontracts-lib');
const srz = new finlib.Serializer();
const serialized = srz.serialize(fincontract);
console.log(JSON.stringify(serialized));

DotGenerator

DotGenerator can take a Fincontract and generate a graph description in DOT language, that can be piped into any DOT engine, which supports HTML labels.

const finlib = require('./fincontracts-dot-generator');
const dg = new finlib.DotGenerator();
const dot = dg.generate(fincontract);
console.log(dot);