js-bigchaindb-driver/README.md

Official JavaScript driver for BigchainDB with some naive helpers to get you on your way making transactions in Node.js and the browser.

Compatibility

BigchainDB Server	BigchainDB JavaScript Driver
~=0.10.1	~=1.0.0

Contents

• Installation
• Usage
• Speed Optimizations
• Warnings
• npm releases
• Authors
• License
• API reference

Installation

npm install bigchaindb-driver

Usage

import * as driver from '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 key pair
const alice = new driver.Ed25519Keypair()

// Create a transaction
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'll probably need a babel here and a bundler there. Alternatively, use one of the bundled dist versions:

• dist/bundle/: Babelified and packaged with dependencies, so you can drop it in anywhere you want.
• dist/node/: Babelified into a CommonJS module, so you can drop it in on any node project.

You may also be interested in some long-form tutorials with actual code.

The expected flow for making transactions:

1. Go get yourself some key pairs. (or a whole bunch of them, nobody's counting)
   • new driver.Ed25519Keypair()
2. Construct a transaction payload that you can send off to BigchainDB:
   • driver.Transaction.makeCreateTransaction() for creating a new asset or
   • driver.Transaction.makeTransferTransaction() for transferring an existing asset
3. 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.
4. (Optional) You've got everything you need, except for an asset and metadata. Maybe define them (any JSON-serializable object will do).
5. 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.
6. 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 and this and this 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, or its underlying sodium library
• node-sha3 -- MAKE SURE to use steakknife's fork if the FIPS 202 upgrade 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).

BigchainDB Server 0.10 does not implement the newer version of the spec and WILL fail if you try using a newer implementation of crypto-conditions.

SHA3

Make sure to use a SHA3 implementation that has been upgraded as per FIPS 202. 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) key pair.

An example BigchainDB Server-generated key pair (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).

npm releases

For a new patch release, execute on the machine where you're logged into your npm account:

npm run release

Command is powered by release-it package, defined in the package.json.

That's what the command does without any user interaction:

• create release commit by updating version in package.json
• create tag for that release commit
• push commit & tag
• create a new release on GitHub, with change log auto-generated from commit messages
• publish to npm as a new release

If you want to create a minor or major release, use these commands:

npm run release-minor

npm run release-major

Authors

• inspired by js-bigchaindb-quickstart of @sohkhai [thanks]
• BigchainDB dev@bigchaindb.com

License

Copyright 2017 BigchainDB GmbH

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.