mirror of
https://github.com/bigchaindb/js-bigchaindb-driver.git
synced 2024-11-21 17:26:56 +01:00
Official BigchainDB JavaScript driver for Node.js and the browser
| .ci | ||
| .github/workflows | ||
| .husky | ||
| compose | ||
| docs | ||
| examples | ||
| media | ||
| plugins | ||
| src | ||
| test | ||
| types | ||
| .babelrc | ||
| .eslintignore | ||
| .eslintrc.js | ||
| .gitignore | ||
| .npmignore | ||
| .travis.yml | ||
| API.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.rst | ||
| docker-compose.yml | ||
| LICENSE | ||
| LICENSE-docs | ||
| package.json | ||
| README.md | ||
| RELEASE_PROCESS.md | ||
| webpack.common.js | ||
| webpack.config.js | ||
| webpack.development.js | ||
| webpack.parts.js | ||
| webpack.production.js | ||
Official JavaScript driver for BigchainDB to create transactions in Node.js and the browser.
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
- BigchainDB Documentation
- Speed Optimizations
- Development
- Release Process
- Authors
- Licenses
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
- The Hitchhiker's Guide to BigchainDB
- HTTP API Reference
- The Transaction Model
- Inputs and Outputs
- Asset Transfer
- All 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:
- 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)
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
- inspired by
js-bigchaindb-quickstartof @sohkhai [thanks] - BigchainDB contact@ipdb.global
- BigchainDB contributors
Licenses
See LICENSE and LICENSE-docs.