js-bigchaindb-driver/README.md

# JavaScript Driver for BigchainDB

> Inspired by [`js-bigchaindb-quickstart`](https://github.com/sohkai/js-bigchaindb-quickstart) of @sohkhai [thanks]

> Supports BigchainDB Server v0.10 (Warning: use CORS enabled [branch](https://github.com/bigchaindb/bigchaindb/tree/kyber-master-feat-cors) untill [PR #1311](https://github.com/bigchaindb/bigchaindb/pull/1311) is resolved )

Some naive helpers to get you on your way to making some transactions, if you'd like to use
[BigchainDB](https://github.com/bigchaindb/bigchaindb) with JavaScript.

Aimed to support usage in browsers or node and ES∞+, so
you'll probably need a babel here and a bundler there (or use [one of the built versions](./dist)),
of which I expect you'll know quite well ([otherwise, go check out js-reactor](https://github.com/bigchaindb/js-reactor)).
[![Build Status](https://travis-ci.org/bigchaindb/js-bigchaindb-driver.svg?branch=master)](https://travis-ci.org/bigchaindb/js-bigchaindb-driver)

## Compatibility

| BigchainDB Server | BigchainDB Javascript Driver |
| ----------------- |------------------------------|
| `~=0.10.1` | `~=0.1.0` |


## Contents

- [Getting Started](#getting-started)
- [Usage](#usage)
- [Speed Optimizations](#speed-optimizations)
- [Warnings](#warnings)
- [API](API.md)

## Getting started

### Install from npm

```bash
# install from npm
npm install js-bigchaindb-driver
# Install from GitHub - ssh
npm install git+ssh://github.com/bigchaindb/js-bigchaindb-driver.git
# Install from GitHub - https
npm install git+https://github.com/bigchaindb/js-bigchaindb-driver.git
```

### Import / ES6

```javascript
// ES6 Browser
import * as driver from 'js-bigchaindb-driver';
// ES<<6 Browser
let driver = require('js-bigchaindb-driver');
// ES<<6 CommonJS / node
let driver = require('js-bigchaindb-driver/dist/node');
```

## Usage

```javascript
import * as driver from 'js-bigchaindb-driver';

// http(s)://<bigchaindb-API-url>/ (e.g. http://localhost:9984/api/v1/)
const API_PATH = 'http://localhost:9984/api/v1/';

// create a new user with a public-private keypair
const alice = new driver.Ed25519Keypair();

// Create a transation
const tx = driver.Transaction.makeCreateTransaction(
    { assetMessage: 'My very own asset...' },
    { metaDataMessage: 'wrapped in a transaction' },
    [ driver.Transaction.makeOutput(
            driver.Transaction.makeEd25519Condition(alice.publicKey))
    ],
    alice.publicKey
);

// sign/fulfill the transaction
const txSigned = driver.Transaction.signTransaction(tx, alice.privateKey);

// send it off to BigchainDB
let conn = new driver.Connection(PATH, { 'Content-Type': 'application/json' });
conn.postTransaction(txSigned)
    .then(() => conn.getStatus(txSigned.id))
    .then((res) => console.log('Transaction status:', res.status));
```

You may also be interested in some [long-form tutorials with actual code](https://github.com/bigchaindb/kyber).

The expected flow for making transactions:

1. Go get yourself some keypairs! (or a whole bunch of them, nobody's
   counting)
    - `new driver.Ed25519Keypair()` 
1. Construct a transaction payload that you can send of to BigchainDB:
    - `driver.Transaction.makeCreateTransaction()` for creating a new asset or
    - `driver.Transaction.makeTransferTransaction()` for transfering an existing asset
1. A transaction needs an output (\*):
    - `driver.Transaction.makeOutput()` still requires a crypto-condition
    - `driver.Transaction.makeEd25519Condition()` should do the trick for a simple public key output.
1. (**Optional**) You've got everything you need, except for an asset and metadata. Maybe define them (any
   JSON-serializable object will do).
1. Ok, now you've got a transaction, but we need you to *sign* it cause, you
   know... cryptography and `¯\_(ツ)_/¯`:
   - `driver.Transaction.signTransaction()` allows you to sign with private keys.
1. Final step is to send the transaction off to BigchainDB:
   - `driver.Connection.postTransaction()`


(\*) If you're not sure what any of this means (and you're as
   confused as I think you are right now), you might wanna go check out [this](https://docs.bigchaindb.com/projects/server/en/latest/data-models/crypto-conditions.html)
   and [this](https://docs.bigchaindb.com/projects/py-driver/en/latest/usage.html#asset-transfer)
   and [this](https://tools.ietf.org/html/draft-thomas-crypto-conditions-01) first.

## Speed Optimizations

This implementation plays "safe" by using JS-native (or downgradable) libraries for its
crypto-related functions to keep compatibilities with the browser. If you do want some more speed, feel free to explore the following: 

* [chloride](https://github.com/dominictarr/chloride), or its underlying [sodium](https://github.com/paixaop/node-sodium)
  library
* [node-sha3](https://github.com/phusion/node-sha3) -- **MAKE SURE** to use [steakknife's fork](https://github.com/steakknife/node-sha3)
  if [the FIPS 202 upgrade](https://github.com/phusion/node-sha3/pull/25) hasn't been merged
  (otherwise, you'll run into all kinds of hashing problems)

## Warnings

> Crypto-conditions

Make sure you keep using a crypto-conditions implementation that implements the older v1 draft (e.g.
[`five-bells-condition@v3.3.1`](https://github.com/interledgerjs/five-bells-condition/releases/tag/v3.3.1)).
BigchainDB Server 0.10 does not implement the newer version of the spec and **WILL** fail if you to
use a newer implementation of crypto-conditions.

> SHA3

Make sure to use a SHA3 implementation that has been upgraded as per [FIPS 202](http://csrc.nist.gov/publications/drafts/fips-202/fips_202_draft.pdf).
Otherwise, the hashes you generate **WILL** be invalid in the eyes of the BigchainDB Server.

> Ed25519

If you do end up replacing `tweetnacl` with `chloride` (or any other `Ed25519` package), you might
want to double check that it gives you a correct public/private (or verifying/signing, if they use
that lingo) keypair.

An example BigchainDB Server-generated keypair (encoded in `base58`):

- Public: `DjPMHDD9JtgypDKY38mPz9f6owjAMAKhLuN1JfRAat8C`
- Private: `7Gf5YRch2hYTyeLxqNLgTY63D9K5QH2UQ7LYFeBGuKvo`

Your package should be able to take in the decoded version of the **private** key and return you the
same **public** key (once you encode that to `base58`).