Official BigchainDB JavaScript driver for Node.js and the browser
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
getlarge 17d3a02cb3
Release 4.3.0
3 months ago
.ci Add SPDX license info strings to all source files 4 years ago
.github/workflows ci: extends wait delay 3 months ago
.husky fix: update release-it config 1 year ago
compose merge 4 years ago
docs Change Travis CI URLs to use .com 3 years ago
examples fix: update example 1 year ago
media Tried to change permissions of all files to 664 5 years ago
plugins fix: run lint 1 year ago
src fix: use abort-controller pkg for node <15 3 months ago
test feat: add `limit` query for transaction search requests 3 months ago
types feat: export extra types 3 months ago
.babelrc fix: update babel and lint config 1 year ago
.eslintignore fix: lint config 1 year ago
.eslintrc.js chore: update lint rules 3 months ago
.gitignore Release 4.1.2 2 years ago
.npmignore Release 4.1.2 2 years ago
.travis.yml fix: update travis config 1 year ago
API.md fix: add delegateSignatureAsync method 1 year ago
CODE_OF_CONDUCT.md Point Code of Contuct page to main BDB repo 3 years ago
CONTRIBUTING.rst Add SPDX license info strings to all source files 4 years ago
LICENSE Tried to change permissions of all files to 664 5 years ago
LICENSE-docs Reformat LICENSE-docs for readability 4 years ago
README.md fix: improve imports 1 year ago
RELEASE_PROCESS.md fix: regenerate doc 1 year ago
docker-compose.yml update tendermint version in docker compose 1 year ago
package.json Release 4.3.0 3 months ago
webpack.common.js chore: update wepback config 3 months ago
webpack.config.js chore: update wepback config 3 months ago
webpack.development.js chore: update wepback config 3 months ago
webpack.parts.js chore: update wepback config 3 months ago
webpack.production.js Add SPDX license info strings to all source files 4 years ago

README.md

js-bigchaindb-driver

Official JavaScript driver for BigchainDB to create transactions in Node.js and the browser.

Join the chat at https://gitter.im/bigchaindb/js-bigchaindb-driver npm codecov js ascribe Build Status Greenkeeper badge

Compatibility

BigchainDB Server BigchainDB JavaScript Driver
0.10 0.1.x
1.0.0 0.3.x
1.3.x 3.x.x
>= 2.0.0 4.x.x

Breaking changes

  • 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
  • Version 3.2 of BigchainDB JavaScript Driver introduces a new way of creating transfer transactions. Check older versions

Table of Contents


Installation and Usage

npm install bigchaindb-driver
const driver = require('bigchaindb-driver')
// or ES6+
import driver from 'bigchaindb-driver'

Example: Create a transaction

const driver = require('bigchaindb-driver')
const base58 = require('bs58');
const crypto = require('crypto');
const { Ed25519Sha256 } = require('crypto-conditions');

// BigchainDB server instance (e.g. https://example.com/api/v1/)
const API_PATH = 'http://localhost:9984/api/v1/'

// Create a new keypair.
const alice = new driver.Ed25519Keypair()

// Construct a transaction payload
const tx = driver.Transaction.makeCreateTransaction(
    // 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' },

    // A transaction needs an output
    [ driver.Transaction.makeOutput(
            driver.Transaction.makeEd25519Condition(alice.publicKey))
    ],
    alice.publicKey
)

// Sign the transaction with private keys
const txSigned = driver.Transaction.signTransaction(tx, alice.privateKey)

// Or use delegateSignTransaction to provide your own signature function
function signTransaction() {
    // get privateKey from somewhere
    const privateKeyBuffer = Buffer.from(base58.decode(alice.privateKey))
    return function sign(serializedTransaction, input, index) {
        const transactionUniqueFulfillment = input.fulfills ? serializedTransaction
                .concat(input.fulfills.transaction_id)
                .concat(input.fulfills.output_index) : serializedTransaction
        const transactionHash = crypto.createHash('sha3-256').update(transactionUniqueFulfillment).digest()
        const ed25519Fulfillment = new Ed25519Sha256();
        ed25519Fulfillment.sign(transactionHash, privateKeyBuffer);
        return ed25519Fulfillment.serializeUri();
    };
}
const txSigned = driver.Transaction.delegateSignTransaction(tx, signTransaction())

// Send the transaction off to BigchainDB
const conn = new driver.Connection(API_PATH)

conn.postTransactionCommit(txSigned)
    .then(retrievedTx => console.log('Transaction', retrievedTx.id, 'successfully posted.'))

Browser usage

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>BigchainDB boilerplate</title>
        <!-- Adjust version to your needs -->
        <script src="https://unpkg.com/bigchaindb-driver@4.2.0/dist/browser/bigchaindb-driver.window.min.js"></script>

        <script>
            // BigchainDB server instance (e.g. https://example.com/api/v1/)
            const API_PATH = 'http://localhost:9984/api/v1/'

            // Create a new keypair.
            const alice = new BigchainDB.Ed25519Keypair()

            // Construct a transaction payload
            const tx = BigchainDB.Transaction.makeCreateTransaction(
                // 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' },

                // A transaction needs an output
                [ BigchainDB.Transaction.makeOutput(
                        BigchainDB.Transaction.makeEd25519Condition(alice.publicKey))
                ],
                alice.publicKey
            )

            // Sign the transaction with private keys
            const txSigned = BigchainDB.Transaction.signTransaction(tx, alice.privateKey)

            // Send the transaction off to BigchainDB
            let conn = new BigchainDB.Connection(API_PATH)

            conn.postTransactionCommit(txSigned)
                .then(res => {
                    const elem = document.getElementById('lastTransaction')
                    elem.href = API_PATH + 'transactions/' + txSigned.id
                    elem.innerText = txSigned.id
                    console.log('Transaction', txSigned.id, 'accepted')
                })
            // Check console for the transaction's status
        </script>
    </head>
    <body id="home">
        <h1>Hello BigchainDB</h1>
        <p>Your transaction id is: <a id="lastTransaction" target="_blank"><em>processing</em></a></p>
    </body>
</html>

BigchainDB Documentation

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:

Development

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:

npm run doc

Release Process

See the file named RELEASE_PROCESS.md.

Authors

Licenses

See LICENSE and LICENSE-docs.