Home Reference Source Repository


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

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


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:


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.


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.


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


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) {


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);
} catch (err) {


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);
} catch (err) {


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) {


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);


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);