2017-06-06 16:29:28 +02:00
# [](https://www.bigchaindb.com)
2017-02-10 17:57:14 +01:00
2018-05-14 14:06:44 +02:00
> Official JavaScript driver for [BigchainDB](https://github.com/bigchaindb/bigchaindb) to create transactions in Node.js and the browser.
2017-02-10 17:57:14 +01:00
2017-11-30 12:12:08 +01:00
[](https://gitter.im/bigchaindb/js-bigchaindb-driver?utm_source=badge& utm_medium=badge& utm_campaign=pr-badge& utm_content=badge)
2017-06-13 16:53:11 +02:00
[](https://www.npmjs.com/package/bigchaindb-driver)
2017-06-21 13:22:25 +02:00
[](https://codecov.io/gh/bigchaindb/js-bigchaindb-driver)
2017-06-13 16:53:11 +02:00
[](https://github.com/ascribe/javascript)
2017-06-06 16:23:27 +02:00
[](https://travis-ci.org/bigchaindb/js-bigchaindb-driver)
2017-06-07 00:15:10 +02:00
[](https://greenkeeper.io/)
2017-04-27 14:11:39 +02:00
2018-05-14 14:06:44 +02:00
- [Main Documentation ](https://docs.bigchaindb.com/projects/js-driver/en/latest/usage.html )
- [Driver API reference ](API.md )
2017-09-22 10:26:14 +02:00
2017-05-11 10:22:48 +02:00
## Compatibility
2017-05-11 09:30:00 +02:00
2017-06-07 17:08:42 +02:00
| BigchainDB Server | BigchainDB JavaScript Driver |
2017-05-11 09:30:00 +02:00
| ----------------- |------------------------------|
2017-06-23 11:25:36 +02:00
| `0.10` | `0.1.x` |
2018-05-14 14:06:44 +02:00
| `1.0.0` | `0.3.x` |
| `1.3.x` | `3.x.x` |
2018-04-03 10:43:25 +02:00
| `>= 2.0.0` | `4.x.x` |
2017-05-11 09:30:00 +02:00
2017-12-19 16:56:16 +01:00
## Breaking changes
2018-04-03 10:47:00 +02:00
2018-04-04 10:27:23 +02:00
- **Version 4.0** of BigchainDB JavaScript Driver makes the driver compatible with BigchainDB 2.0. There are new functions for sending off transactions along with other changes. Check [older versions ](https://docs.bigchaindb.com/projects/js-driver/en/latest/readme.html#features )
2018-04-03 10:47:00 +02:00
- **Version 3.2** of BigchainDB JavaScript Driver introduces a new way of creating transfer transactions. Check [older versions ](https://docs.bigchaindb.com/projects/js-driver/en/latest/readme.html#features )
2017-05-11 09:30:00 +02:00
2018-05-14 14:06:44 +02:00
## Table of Contents
2018-04-04 10:27:23 +02:00
2018-05-14 14:06:44 +02:00
- [Installation and Usage ](#installation-and-usage )
- [Example: Create a transaction ](#example-create-a-transaction )
- [Browser usage ](#browser-usage )
- [BigchainDB Documentation ](#bigchaindb-documentation )
- [Speed Optimizations ](#speed-optimizations )
2018-05-14 17:14:40 +02:00
- [Development ](#development )
2018-05-14 14:06:44 +02:00
- [Authors ](#authors )
- [License ](#license )
2017-04-27 14:11:39 +02:00
2018-05-14 14:06:44 +02:00
---
2017-02-10 17:57:14 +01:00
2018-05-14 14:06:44 +02:00
## Installation and Usage
2017-04-27 14:11:39 +02:00
2017-05-03 00:16:48 +02:00
```bash
2017-06-06 16:29:28 +02:00
npm install bigchaindb-driver
2017-04-27 14:11:39 +02:00
```
2018-05-14 14:06:44 +02:00
```js
const driver = require('bigchaindb-driver')
// or ES6+
import driver from 'bigchaindb-driver'
```
2017-06-22 10:34:18 +02:00
### Example: Create a transaction
2017-06-13 21:30:23 +02:00
2017-06-06 16:29:28 +02:00
```js
2017-06-23 15:00:55 +02:00
const driver = require('bigchaindb-driver')
2017-04-27 14:11:39 +02:00
2018-05-14 14:06:44 +02:00
// BigchainDB server instance (e.g. https://test.bigchaindb.com/api/v1/)
2017-06-13 16:53:11 +02:00
const API_PATH = 'http://localhost:9984/api/v1/'
2017-02-10 17:57:14 +01:00
2017-06-23 15:00:55 +02:00
// Create a new keypair.
2017-06-13 16:53:11 +02:00
const alice = new driver.Ed25519Keypair()
2017-04-27 14:11:39 +02:00
2017-06-13 21:30:23 +02:00
// Construct a transaction payload
2017-04-27 14:11:39 +02:00
const tx = driver.Transaction.makeCreateTransaction(
2017-06-23 15:00:55 +02:00
// Define the asset to store, in this example it is the current temperature
// (in Celsius) for the city of Berlin.
{ city: 'Berlin, DE', temperature: 22, datetime: new Date().toString() },
// Metadata contains information about the transaction itself
// (can be `null` if not needed)
{ what: 'My first BigchainDB transaction' },
2017-06-13 21:30:23 +02:00
// A transaction needs an output
2017-04-27 14:11:39 +02:00
[ driver.Transaction.makeOutput(
driver.Transaction.makeEd25519Condition(alice.publicKey))
],
alice.publicKey
2017-06-14 18:06:06 +02:00
)
2017-04-27 14:11:39 +02:00
2017-06-23 15:00:55 +02:00
// Sign the transaction with private keys
2017-06-13 16:53:11 +02:00
const txSigned = driver.Transaction.signTransaction(tx, alice.privateKey)
2017-04-27 14:11:39 +02:00
2017-06-13 21:30:23 +02:00
// Send the transaction off to BigchainDB
2017-06-23 15:00:55 +02:00
const conn = new driver.Connection(API_PATH)
2017-06-13 21:30:23 +02:00
2018-04-04 10:27:23 +02:00
conn.postTransactionCommit(txSigned)
2017-06-23 15:00:55 +02:00
.then(retrievedTx => console.log('Transaction', retrievedTx.id, 'successfully posted.'))
2017-04-27 14:11:39 +02:00
```
2018-05-14 14:06:44 +02:00
### Browser usage
2017-06-21 17:39:19 +02:00
```html
<!DOCTYPE html>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
2017-06-23 15:00:55 +02:00
< title > BigchainDB boilerplate< / title >
2017-06-21 17:39:19 +02:00
<!-- Adjust version to your needs -->
2018-04-04 10:27:23 +02:00
< script src = "https://unpkg.com/bigchaindb-driver@4.0.0/dist/browser/bigchaindb-driver.window.min.js" > < / script >
2017-06-21 17:39:19 +02:00
2017-06-23 15:00:55 +02:00
< script >
2018-05-14 14:06:44 +02:00
// BigchainDB server instance (e.g. https://test.bigchaindb.com/api/v1/)
2017-06-21 17:39:19 +02:00
const API_PATH = 'http://localhost:9984/api/v1/'
2017-06-23 15:00:55 +02:00
// Create a new keypair.
2017-06-21 17:39:19 +02:00
const alice = new BigchainDB.Ed25519Keypair()
// Construct a transaction payload
const tx = BigchainDB.Transaction.makeCreateTransaction(
2017-06-23 15:00:55 +02:00
// Define the asset to store, in this example it is the current temperature
// (in Celsius) for the city of Berlin.
{ city: 'Berlin, DE', temperature: 22, datetime: new Date().toString() },
// Metadata contains information about the transaction itself
// (can be `null` if not needed)
{ what: 'My first BigchainDB transaction' },
2017-06-21 17:39:19 +02:00
// A transaction needs an output
[ BigchainDB.Transaction.makeOutput(
BigchainDB.Transaction.makeEd25519Condition(alice.publicKey))
],
alice.publicKey
)
2017-06-23 15:00:55 +02:00
// Sign the transaction with private keys
2017-06-21 17:39:19 +02:00
const txSigned = BigchainDB.Transaction.signTransaction(tx, alice.privateKey)
// Send the transaction off to BigchainDB
2017-06-22 17:19:31 +02:00
let conn = new BigchainDB.Connection(API_PATH)
2017-06-21 17:39:19 +02:00
2018-04-04 10:27:23 +02:00
conn.postTransactionCommit(txSigned)
2017-06-23 15:00:55 +02:00
.then(res => {
const elem = document.getElementById('lastTransaction')
elem.href = API_PATH + 'transactions/' + txSigned.id
elem.innerText = txSigned.id
console.log('Transaction', txSigned.id, 'accepted')
})
2017-06-22 10:34:18 +02:00
// Check console for the transaction's status
< / script >
2017-06-21 17:39:19 +02:00
< / head >
< body id = "home" >
2017-06-23 15:00:55 +02:00
< h1 > Hello BigchainDB< / h1 >
< p > Your transaction id is: < a id = "lastTransaction" target = "_blank" > < em > processing< / em > < / a > < / p >
2017-06-21 17:39:19 +02:00
< / body >
< / html >
```
2017-06-13 21:30:23 +02:00
## BigchainDB Documentation
2017-04-27 14:11:39 +02:00
2018-05-14 14:06:44 +02:00
- [The Hitchhiker's Guide to BigchainDB ](https://www.bigchaindb.com/developers/guide/ )
2017-06-13 21:30:23 +02:00
- [HTTP API Reference ](https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html )
- [The Transaction Model ](https://docs.bigchaindb.com/projects/server/en/latest/data-models/transaction-model.html?highlight=crypto%20conditions )
- [Inputs and Outputs ](https://docs.bigchaindb.com/projects/server/en/latest/data-models/inputs-outputs.html )
- [Asset Transfer ](https://docs.bigchaindb.com/projects/py-driver/en/latest/usage.html#asset-transfer )
- [All BigchainDB Documentation ](https://docs.bigchaindb.com/ )
2017-02-10 17:57:14 +01:00
2017-04-27 14:11:39 +02:00
## Speed Optimizations
2017-02-10 17:57:14 +01:00
2017-06-16 14:21:52 +02:00
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:
2017-02-10 17:57:14 +01:00
2017-06-07 15:49:44 +02:00
* [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)
2017-02-10 17:57:14 +01:00
2018-05-14 17:14:40 +02:00
## Development
```js
git clone git@github.com:bigchaindb/js-bigchaindb-driver.git
cd js-bigchaindb-driver/
npm i
npm run dev
```
After updating source files in `src/` , make sure to update the API documentation. The following command will scan all source files and create the Markdown output into `./API.md` :
```bash
npm run doc
```
2017-06-06 16:32:43 +02:00
2017-06-06 16:29:28 +02:00
## Authors
2017-06-07 00:17:05 +02:00
* inspired by [`js-bigchaindb-quickstart` ](https://github.com/sohkai/js-bigchaindb-quickstart ) of @sohkhai [thanks]
2017-06-06 16:29:28 +02:00
* BigchainDB < dev @ bigchaindb . com >
2017-06-06 16:25:38 +02:00
## 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.
2017-06-07 00:15:10 +02:00
```
