bigchaindb/js-bigchaindb-driver
1
0
Fork 0
mirror of https://github.com/bigchaindb/js-bigchaindb-driver.git synced 2024-11-25 11:28:37 +01:00
Code Releases Activity

Merge pull request #173 from bigchaindb/fix/documentation

Browse Source 
Readme & dev updates
This commit is contained in:
Matthias Kretschmann 2018-05-14 18:00:03 +02:00 committed by GitHub
commit 5c106a2ff3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 470 additions and 250 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.babelrc
View File

@ -1,10 +1,11 @@
{
"presets": ["env"],
"presets": [
"env"
],
"plugins": [
"transform-export-extensions",
"transform-object-assign",
"transform-object-rest-spread"
],
"sourceMaps": true,
"sourceMaps": true
}

534
API.md
View File

@ -2,217 +2,421 @@
### Table of Contents
- [Ed25519Keypair](#ed25519keypair)
- [makeEd25519Condition](#makeed25519condition)
- [makeSha256Condition](#makesha256condition)
- [makeThresholdCondition](#makethresholdcondition)
- [makeCreateTransaction](#makecreatetransaction)
- [makeOutput](#makeoutput)
- [makeTransferTransaction](#maketransfertransaction)
- [serializeTransactionIntoCanonicalString](#serializetransactionintocanonicalstring)
- [signTransaction](#signtransaction)
- [ccJsonLoad](#ccjsonload)
- [ccJsonify](#ccjsonify)
- [getBlock](#getblock)
- [getStatus](#getstatus)
- [getTransaction](#gettransaction)
- [listBlocks](#listblocks)
- [listOutputs](#listoutputs)
- [listTransactions](#listtransactions)
- [listVotes](#listvotes)
- [pollStatusAndFetchTransaction](#pollstatusandfetchtransaction)
- [postTransaction](#posttransaction)
- [Ed25519Keypair][1]
- [Connection][2]
- [getBlock][3]
- [getTransaction][4]
- [listBlocks][5]
- [listOutputs][6]
- [listTransactions][7]
- [listVotes][8]
- [postTransaction][9]
- [postTransactionSync][10]
- [postTransactionCommit][11]
- [searchAssets][12]
- [searchMetadata][13]
- [Transaction][14]
- [serializeTransactionIntoCanonicalString][15]
- [makeCreateTransaction][16]
- [makeEd25519Condition][17]
- [makeOutput][18]
- [makeSha256Condition][19]
- [makeThresholdCondition][20]
- [makeTransferTransaction][21]
- [signTransaction][22]
- [ccJsonLoad][23]
- [ccJsonify][24]
## Ed25519Keypair
[src/Ed25519Keypair.js:12-17][25]
Type: [Object][26]
**Parameters**
- `secret` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** A seed that will be used as a key derivation function
- `seed` **[Buffer][27]?** A seed that will be used as a key derivation function
**Properties**
- `publicKey` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**
- `privateKey` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**
- `publicKey` **[string][28]**
- `privateKey` **[string][28]**
## makeEd25519Condition
## Connection
[src/connection.js:8-168][29]
Base connection
**Parameters**
- `publicKey` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** base58 encoded Ed25519 public key for the recipient of the Transaction
- `json` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If true returns a json object otherwise a crypto-condition type (optional, default `true`)
- `path`
- `headers` (optional, default `{}`)
Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Ed25519 Condition (that will need to wrapped in an Output)
### getBlock
## makeSha256Condition
[src/connection.js:44-50][30]
**Parameters**
- `preimage` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Preimage to be hashed and wrapped in a crypto-condition
- `json` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If true returns a json object otherwise a crypto-condition type (optional, default `true`)
- `blockHeight`
Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Preimage-Sha256 Condition (that will need to wrapped in an Output)
### getTransaction
## makeThresholdCondition
[src/connection.js:55-61][31]
**Parameters**
- `threshold` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**
- `subconditions` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** (optional, default `[]`)
- `json` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If true returns a json object otherwise a crypto-condition type (optional, default `true`)
- `transactionId`
Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Sha256 Threshold Condition (that will need to wrapped in an Output)
### listBlocks
## makeCreateTransaction
[src/connection.js:67-73][32]
**Parameters**
- `asset` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Created asset's data
- `metadata` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Metadata for the Transaction
- `outputs` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** Array of Output objects to add to the Transaction.
Think of these as the recipients of the asset after the transaction.
For `CREATE` Transactions, this should usually just be a list of
Outputs wrapping Ed25519 Conditions generated from the issuers' public
keys (so that the issuers are the recipients of the created asset).
- `issuers` **...[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** Public key of one or more issuers to the asset being created by this
Transaction.
Note: Each of the private keys corresponding to the given public
keys MUST be used later (and in the same order) when signing the
Transaction (`signTransaction()`).
- `transactionId`
- `status`
Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Unsigned transaction -- make sure to call signTransaction() on it before
sending it off!
### listOutputs
## makeOutput
[src/connection.js:79-91][33]
**Parameters**
- `condition` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Condition (e.g. a Ed25519 Condition from `makeEd25519Condition()`)
- `amount` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Amount of the output (optional, default `1`)
- `publicKey`
- `spent`
Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** An Output usable in a Transaction
### listTransactions
## makeTransferTransaction
[src/connection.js:97-104][34]
**Parameters**
- `unspentTransaction` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Previous Transaction you have control over (i.e. can fulfill
its Output Condition)
- `metadata` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Metadata for the Transaction
- `outputs` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** Array of Output objects to add to the Transaction.
Think of these as the recipients of the asset after the transaction.
For `TRANSFER` Transactions, this should usually just be a list of
Outputs wrapping Ed25519 Conditions generated from the public keys of
the recipients.
- `fulfilledOutputs` **...[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Indices of the Outputs in `unspentTransaction` that this
Transaction fulfills.
Note that the public keys listed in the fulfilled Outputs
must be used (and in the same order) to sign the Transaction
(`signTransaction()`).
- `assetId`
- `operation`
Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Unsigned transaction -- make sure to call signTransaction() on it before
sending it off!
### listVotes
## serializeTransactionIntoCanonicalString
**Parameters**
- `transaction`
- `null` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** (transaction)
Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a canonically serialized Transaction
## signTransaction
**Parameters**
- `transaction` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Transaction to sign. `transaction` is not modified.
- `privateKeys` **...[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Private keys associated with the issuers of the `transaction`.
Looped through to iteratively sign any Input Fulfillments found in
the `transaction`.
Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The signed version of `transaction`.
## ccJsonLoad
**Parameters**
- `conditionJson` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
Returns **cc.Condition** Ed25519 Condition (that will need to wrapped in an Output)
## ccJsonify
**Parameters**
- `fulfillment` **cc.Fulfillment** base58 encoded Ed25519 public key for the recipient of the Transaction
Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Ed25519 Condition (that will need to wrapped in an Output)
## getBlock
[src/connection.js:109-115][35]
**Parameters**
- `blockId`
## getStatus
### postTransaction
**Parameters**
- `tx_id`
## getTransaction
**Parameters**
- `txId`
## listBlocks
**Parameters**
- `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `$0.tx_id`
- `$0.status`
- `tx_id`
- `status`
## listOutputs
**Parameters**
- `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `$0.public_key`
- `$0.unspent`
- `onlyJsonResponse`
- `public_key`
- `unspent`
## listTransactions
**Parameters**
- `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `$0.asset_id`
- `$0.operation`
- `asset_id`
- `operation`
## listVotes
**Parameters**
- `block_id`
## pollStatusAndFetchTransaction
**Parameters**
- `tx_id`
Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
## postTransaction
[src/connection.js:120-125][36]
**Parameters**
- `transaction`
### postTransactionSync
[src/connection.js:130-135][37]
**Parameters**
- `transaction`
### postTransactionCommit
[src/connection.js:140-145][38]
**Parameters**
- `transaction`
### searchAssets
[src/connection.js:150-156][39]
**Parameters**
- `search`
### searchMetadata
[src/connection.js:161-167][40]
**Parameters**
- `search`
## Transaction
[src/transaction.js:12-253][41]
Construct Transactions
### serializeTransactionIntoCanonicalString
[src/transaction.js:18-25][42]
Canonically serializes a transaction into a string by sorting the keys
**Parameters**
- `transaction`
- `null` **[Object][26]** (transaction)
Returns **[string][28]** a canonically serialized Transaction
### makeCreateTransaction
[src/transaction.js:76-83][43]
Generate a `CREATE` transaction holding the `asset`, `metadata`, and `outputs`, to be signed by
the `issuers`.
**Parameters**
- `asset` **[Object][26]** Created asset's data
- `metadata` **[Object][26]** Metadata for the Transaction
- `outputs` **[Array][44]<[Object][26]>** Array of Output objects to add to the Transaction.
Think of these as the recipients of the asset after the transaction.
For `CREATE` Transactions, this should usually just be a list of
Outputs wrapping Ed25519 Conditions generated from the issuers' public
keys (so that the issuers are the recipients of the created asset).
- `issuers` **...[Array][44]<[string][28]>** Public key of one or more issuers to the asset being created by this
Transaction.
Note: Each of the private keys corresponding to the given public
keys MUST be used later (and in the same order) when signing the
Transaction (`signTransaction()`).
Returns **[Object][26]** Unsigned transaction -- make sure to call signTransaction() on it before
sending it off!
### makeEd25519Condition
[src/transaction.js:92-103][45]
Create an Ed25519 Cryptocondition from an Ed25519 public key
to put into an Output of a Transaction
**Parameters**
- `publicKey` **[string][28]** base58 encoded Ed25519 public key for the recipient of the Transaction
- `json` **[boolean][46]** If true returns a json object otherwise a crypto-condition type (optional, default `true`)
Returns **[Object][26]** Ed25519 Condition (that will need to wrapped in an Output)
### makeOutput
[src/transaction.js:113-133][47]
Create an Output from a Condition.
Note: Assumes the given Condition was generated from a
single public key (e.g. a Ed25519 Condition)
**Parameters**
- `condition` **[Object][26]** Condition (e.g. a Ed25519 Condition from `makeEd25519Condition()`)
- `amount` **[string][28]** Amount of the output (optional, default `'1'`)
Returns **[Object][26]** An Output usable in a Transaction
### makeSha256Condition
[src/transaction.js:141-149][48]
Create a Preimage-Sha256 Cryptocondition from a secret to put into an Output of a Transaction
**Parameters**
- `preimage` **[string][28]** Preimage to be hashed and wrapped in a crypto-condition
- `json` **[boolean][46]** If true returns a json object otherwise a crypto-condition type (optional, default `true`)
Returns **[Object][26]** Preimage-Sha256 Condition (that will need to wrapped in an Output)
### makeThresholdCondition
[src/transaction.js:158-172][49]
Create an Sha256 Threshold Cryptocondition from threshold to put into an Output of a Transaction
**Parameters**
- `threshold` **[number][50]**
- `subconditions` **[Array][44]** (optional, default `[]`)
- `json` **[boolean][46]** If true returns a json object otherwise a crypto-condition type (optional, default `true`)
Returns **[Object][26]** Sha256 Threshold Condition (that will need to wrapped in an Output)
### makeTransferTransaction
[src/transaction.js:195-216][51]
Generate a `TRANSFER` transaction holding the `asset`, `metadata`, and `outputs`, that fulfills
the `fulfilledOutputs` of `unspentTransaction`.
**Parameters**
- `unspentOutputs`
- `outputs` **[Array][44]<[Object][26]>** Array of Output objects to add to the Transaction.
Think of these as the recipients of the asset after the transaction.
For `TRANSFER` Transactions, this should usually just be a list of
Outputs wrapping Ed25519 Conditions generated from the public keys of
the recipients.
- `metadata` **[Object][26]** Metadata for the Transaction
- `unspentTransaction` **[Object][26]** Previous Transaction you have control over (i.e. can fulfill
its Output Condition)
- `OutputIndices` **...[number][50]** Indices of the Outputs in `unspentTransaction` that this
Transaction fulfills.
Note that listed public keys listed must be used (and in
the same order) to sign the Transaction
(`signTransaction()`).
Returns **[Object][26]** Unsigned transaction -- make sure to call signTransaction() on it before
sending it off!
### signTransaction
[src/transaction.js:229-252][52]
Sign the given `transaction` with the given `privateKey`s, returning a new copy of `transaction`
that's been signed.
Note: Only generates Ed25519 Fulfillments. Thresholds and other types of Fulfillments are left as
an exercise for the user.
**Parameters**
- `transaction` **[Object][26]** Transaction to sign. `transaction` is not modified.
- `privateKeys` **...[string][28]** Private keys associated with the issuers of the `transaction`.
Looped through to iteratively sign any Input Fulfillments found in
the `transaction`.
Returns **[Object][26]** The signed version of `transaction`.
## ccJsonLoad
[src/utils/ccJsonLoad.js:10-40][53]
Loads a crypto-condition class (Fulfillment or Condition) from a BigchainDB JSON object
**Parameters**
- `conditionJson` **[Object][26]**
Returns **cc.Condition** Ed25519 Condition (that will need to wrapped in an Output)
## ccJsonify
[src/utils/ccJsonify.js:8-61][54]
Serializes a crypto-condition class (Condition or Fulfillment) into a BigchainDB-compatible JSON
**Parameters**
- `fulfillment` **cc.Fulfillment** base58 encoded Ed25519 public key for recipient of the Transaction
Returns **[Object][26]** Ed25519 Condition (that will need to wrapped in an Output)
[1]: #ed25519keypair
[2]: #connection
[3]: #getblock
[4]: #gettransaction
[5]: #listblocks
[6]: #listoutputs
[7]: #listtransactions
[8]: #listvotes
[9]: #posttransaction
[10]: #posttransactionsync
[11]: #posttransactioncommit
[12]: #searchassets
[13]: #searchmetadata
[14]: #transaction
[15]: #serializetransactionintocanonicalstring
[16]: #makecreatetransaction
[17]: #makeed25519condition
[18]: #makeoutput
[19]: #makesha256condition
[20]: #makethresholdcondition
[21]: #maketransfertransaction
[22]: #signtransaction
[23]: #ccjsonload
[24]: #ccjsonify
[25]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/Ed25519Keypair.js#L12-L17 "Source code on GitHub"
[26]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[27]: https://nodejs.org/api/buffer.html
[28]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[29]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L8-L168 "Source code on GitHub"
[30]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L44-L50 "Source code on GitHub"
[31]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L55-L61 "Source code on GitHub"
[32]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L67-L73 "Source code on GitHub"
[33]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L79-L91 "Source code on GitHub"
[34]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L97-L104 "Source code on GitHub"
[35]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L109-L115 "Source code on GitHub"
[36]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L120-L125 "Source code on GitHub"
[37]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L130-L135 "Source code on GitHub"
[38]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L140-L145 "Source code on GitHub"
[39]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L150-L156 "Source code on GitHub"
[40]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/connection.js#L161-L167 "Source code on GitHub"
[41]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L12-L253 "Source code on GitHub"
[42]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L18-L25 "Source code on GitHub"
[43]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L76-L83 "Source code on GitHub"
[44]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[45]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L92-L103 "Source code on GitHub"
[46]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[47]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L113-L133 "Source code on GitHub"
[48]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L141-L149 "Source code on GitHub"
[49]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L158-L172 "Source code on GitHub"
[50]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
[51]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L195-L216 "Source code on GitHub"
[52]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/transaction.js#L229-L252 "Source code on GitHub"
[53]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/utils/ccJsonLoad.js#L10-L40 "Source code on GitHub"
[54]: https://github.com/bigchaindb/js-bigchaindb-driver/blob/691fadfd9887d59fcff4877d9f90521da11ef950/src/utils/ccJsonify.js#L8-L61 "Source code on GitHub"

52
README.md
View File

@ -1,6 +1,6 @@
# [![js-bigchaindb-driver](media/repo-banner@2x.png)](https://www.bigchaindb.com)
> Official JavaScript driver for [BigchainDB](https://github.com/bigchaindb/bigchaindb) with some naive helpers to get you on your way making transactions in Node.js and the browser.
> Official JavaScript driver for [BigchainDB](https://github.com/bigchaindb/bigchaindb) to create transactions in Node.js and the browser.
[![Join the chat at https://gitter.im/bigchaindb/js-bigchaindb-driver](https://badges.gitter.im/bigchaindb/js-bigchaindb-driver.svg)](https://gitter.im/bigchaindb/js-bigchaindb-driver?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![npm](https://img.shields.io/npm/v/bigchaindb-driver.svg)](https://www.npmjs.com/package/bigchaindb-driver)
@ -9,7 +9,8 @@
[![Build Status](https://travis-ci.org/bigchaindb/js-bigchaindb-driver.svg?branch=master)](https://travis-ci.org/bigchaindb/js-bigchaindb-driver)
[![Greenkeeper badge](https://badges.greenkeeper.io/bigchaindb/js-bigchaindb-driver.svg)](https://greenkeeper.io/)
- Documentation: https://docs.bigchaindb.com/projects/js-driver/en/latest/usage.html
- [Main Documentation](https://docs.bigchaindb.com/projects/js-driver/en/latest/usage.html)
- [Driver API reference](API.md)
## Compatibility
@ -25,28 +26,37 @@
- **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)
- **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)
## Table of Contents
## Contents
- [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)
- [Development](#development)
- [Authors](#authors)
- [License](#license)
* [Installation and Usage with package managers (npm/yarn)](#installation-and-usage-with-package-managers-npmyarn)
* [Example: Create a transaction](#example-create-a-transaction)
* [Use a pre-built image (browser only)](#use-a-pre-built-image-browser-only)
* [Documentation](#bigchaindb-documentation)
* [Authors](#authors)
* [License](#license)
---
## Installation and Usage with package managers (npm/yarn)
## Installation and Usage
```bash
npm install bigchaindb-driver
```
```js
const driver = require('bigchaindb-driver')
// or ES6+
import driver from 'bigchaindb-driver'
```
### Example: Create a transaction
```js
const driver = require('bigchaindb-driver')
// BigchainDB server instance or IPDB (e.g. https://test.ipdb.io/api/v1/)
// BigchainDB server instance (e.g. https://test.bigchaindb.com/api/v1/)
const API_PATH = 'http://localhost:9984/api/v1/'
// Create a new keypair.
@ -79,7 +89,7 @@ conn.postTransactionCommit(txSigned)
.then(retrievedTx => console.log('Transaction', retrievedTx.id, 'successfully posted.'))
```
## Use a pre-built image (browser only)
### Browser usage
```html
<!DOCTYPE html>
@ -91,7 +101,7 @@ conn.postTransactionCommit(txSigned)
<script src="https://unpkg.com/bigchaindb-driver@4.0.0/dist/browser/bigchaindb-driver.window.min.js"></script>
<script>
// BigchainDB server instance or IPDB (e.g. https://test.ipdb.io/api/v1/)
// BigchainDB server instance (e.g. https://test.bigchaindb.com/api/v1/)
const API_PATH = 'http://localhost:9984/api/v1/'
// Create a new keypair.
@ -139,6 +149,7 @@ conn.postTransactionCommit(txSigned)
## BigchainDB Documentation
- [The Hitchhiker's Guide to BigchainDB](https://www.bigchaindb.com/developers/guide/)
- [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)
@ -152,6 +163,21 @@ This implementation plays "safe" by using JS-native (or downgradable) libraries
* [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)
## 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
```
## Authors

12
package.json
View File

@ -13,21 +13,22 @@
"main": "./dist/node/index.js",
"browser": "./dist/browser/bigchaindb-driver.cjs2.min.js",
"scripts": {
"lint": "./node_modules/.bin/eslint ./",
"lint": "eslint ./{src,test,examples}",
"build": "npm run clean && npm run build:cjs && npm run build:dist",
"build:bundle": "webpack",
"build:cjs": "cross-env BABEL_ENV=cjs babel ./src -d dist/node",
"build:dist": "cross-env NODE_ENV=production webpack -p",
"dev": "webpack -p -w",
"clean": "rimraf dist/bundle dist/node",
"test": "npm run lint && nyc ava test/ && npm run thanks && npm run report-coverage",
"testmine": "npm run lint && nyc ava test/integration/test_min*",
"thanks": "cowsay Hi, thanks for your interest in BigchainDB. We appreciate your contribution!",
"release": "./node_modules/release-it/bin/release-it.js --src.tagName='v%s' --github.release --npm.publish --non-interactive",
"release-minor": "./node_modules/release-it/bin/release-it.js minor --src.tagName='v%s' --github.release --npm.publish --non-interactive",
"release-major": "./node_modules/release-it/bin/release-it.js major --src.tagName='v%s' --github.release --npm.publish --non-interactive",
"prepublishOnly": "npm run build",
"precommit": "lint-staged",
"report-coverage": "nyc report --reporter=lcov > coverage.lcov && codecov"
"report-coverage": "nyc report --reporter=lcov > coverage.lcov && codecov",
"doc": "node ./node_modules/documentation/bin/documentation.js build src/index.js -f md -o API.md -g --markdown-toc"
},
"lint-staged": {
"*.js": [
@ -49,16 +50,17 @@
"babel-preset-es2015-no-commonjs": "0.0.2",
"babel-runtime": "^6.26.0",
"cross-env": "^5.1.4",
"documentation": "^6.3.2",
"eslint": "^4.19.1",
"eslint-config-ascribe": "^3.0.5",
"eslint-plugin-import": "^2.9.0",
"husky": "^0.14.3",
"lint-staged": "^7.0.0",
"sinon": "^5.0.0",
"nyc": "^11.6.0",
"release-it": "^7.2.1",
"rimraf": "^2.6.2",
"webpack": "^4.4.1",
"sinon": "^5.0.0",
"webpack": "^4.8.3",
"webpack-cli": "^2.0.13"
},
"dependencies": {

2
src/Ed25519Keypair.js
View File

@ -3,7 +3,7 @@ import nacl from 'tweetnacl'
/**
* @public
* @class Keypair Ed25519 keypair in base58 (as BigchainDB expects base58 keys)
* Ed25519 keypair in base58 (as BigchainDB expects base58 keys)
* @type {Object}
* @param {Buffer} [seed] A seed that will be used as a key derivation function
* @property {string} publicKey

9
src/baseRequest.js
View File

@ -3,14 +3,13 @@ import fetchPonyfill from 'fetch-ponyfill'
import { vsprintf } from 'sprintf-js'
import formatText from './format_text'
import stringifyAsQueryParam from './stringify_as_query_param'
const fetch = fetchPonyfill(Promise)
/**
* @private
* imported from https://github.com/bigchaindb/js-utility-belt/
*
* Global fetch wrapper that adds some basic error handling and ease of use enhancements.
@ -24,14 +23,14 @@ const fetch = fetchPonyfill(Promise)
* @param {string} url Url to request. Can be specified as a sprintf format string (see
* https://github.com/alexei/sprintf.js) that will be resolved using
* `config.urlTemplateSpec`.
* @param {object} config Additional configuration, mostly passed to fetch as its 'init' config
* @param {Object} config Additional configuration, mostly passed to fetch as its 'init' config
* (see https://developer.mozilla.org/en-US/docs/Web/API/GlobalFetch/fetch#Parameters).
* @param {*} config.jsonBody Json payload to the request. Will automatically be
* JSON.stringify()-ed and override `config.body`.
* @param {string|object} config.query Query parameter to append to the end of the url.
* @param {string|Object} config.query Query parameter to append to the end of the url.
* If specified as an object, keys will be
* decamelized into snake case first.
* @param {*[]|object} config.urlTemplateSpec Format spec to use to expand the url (see sprintf).
* @param {*[]|Object} config.urlTemplateSpec Format spec to use to expand the url (see sprintf).
* @param {*} config.* All other options are passed through to fetch.
*
* @return {Promise} Promise that will resolve with the response if its status was 2xx;

17
src/connection.js
View File

@ -1,9 +1,10 @@
import request from './request'
const HEADER_BLACKLIST = ['content-type']
/**
* Base connection
*/
export default class Connection {
constructor(path, headers = {}) {
this.path = path
@ -38,7 +39,6 @@ export default class Connection {
}
/**
* @public
* @param blockHeight
*/
getBlock(blockHeight) {
@ -50,7 +50,6 @@ export default class Connection {
}
/**
* @public
* @param transactionId
*/
getTransaction(transactionId) {
@ -62,7 +61,6 @@ export default class Connection {
}
/**
* @public
* @param transactionId
* @param status
*/
@ -75,7 +73,6 @@ export default class Connection {
}
/**
* @public
* @param publicKey
* @param spent
*/
@ -94,7 +91,6 @@ export default class Connection {
}
/**
* @public
* @param assetId
* @param operation
*/
@ -108,7 +104,6 @@ export default class Connection {
}
/**
* @public
* @param blockId
*/
listVotes(blockId) {
@ -120,7 +115,6 @@ export default class Connection {
}
/**
* @public
* @param transaction
*/
postTransaction(transaction) {
@ -131,7 +125,6 @@ export default class Connection {
}
/**
* @public
* @param transaction
*/
postTransactionSync(transaction) {
@ -142,19 +135,16 @@ export default class Connection {
}
/**
* @public
* @param transaction
*/
postTransactionCommit(transaction) {
return this._req(this.getApiUrls('transactionsCommit'), {
method: 'POST',
jsonBody: transaction
})
}
/**
* @public
* @param search
*/
searchAssets(search) {
@ -166,7 +156,6 @@ export default class Connection {
}
/**
* @public
* @param search
*/
searchMetadata(search) {

3
src/format_text.js
View File

@ -11,7 +11,7 @@ const Regex = {
/**
* imported from https://github.com/bigchaindb/js-utility-belt/
*
* @private
* Formats strings similarly to C's sprintf, with the addition of '${...}' formats.
*
* Makes a first pass replacing '${...}' formats before passing the expanded string and other
@ -47,6 +47,7 @@ export default function formatText(s, ...argv) {
let interpolationLeft = replacement
/**
* @private
* Interpolation algorithm inspired by sprintf-js.
*
* Goes through the replacement string getting the left-most key or index to interpolate

2
src/request.js
View File

@ -1,7 +1,6 @@
import baseRequest from './baseRequest'
import sanitize from './sanitize'
const DEFAULT_REQUEST_CONFIG = {
headers: {
'Accept': 'application/json'
@ -9,6 +8,7 @@ const DEFAULT_REQUEST_CONFIG = {
}
/**
* @private
* Small wrapper around js-utility-belt's request that provides url resolving,
* default settings, and response handling.
*/

14
src/sanitize.js
View File

@ -3,6 +3,7 @@ import coreObjectEntries from 'core-js/library/fn/object/entries'
/**
* @private
* Abstraction for selectFromObject and omitFromObject for DRYness.
* Set isInclusion to true if the filter should be for including the filtered items (ie. selecting
* only them vs omitting only them).
@ -21,6 +22,7 @@ function filterFromObject(obj, filter, { isInclusion = true } = {}) {
}
/**
* @private
* Returns a filtered copy of the given object's own enumerable properties (no inherited
* properties), keeping any keys that pass the given filter function.
*/
@ -40,24 +42,26 @@ function applyFilterOnObject(obj, filterFn) {
}
/**
* @private
* Similar to lodash's _.pick(), this returns a copy of the given object's
* own and inherited enumerable properties, selecting only the keys in
* the given array or whose value pass the given filter function.
* @param {object} obj Source object
* @param {array|function} filter Array of key names to select or function to invoke per iteration
* @return {object} The new object
* @param {Object} obj Source object
* @param {Array|function} filter Array of key names to select or function to invoke per iteration
* @return {Object} The new object
*/
function selectFromObject(obj, filter) {
return filterFromObject(obj, filter)
}
/**
* @private
* Glorified selectFromObject. Takes an object and returns a filtered shallow copy that strips out
* any properties that are falsy (including coercions, ie. undefined, null, '', 0, ...).
* Does not modify the passed in object.
*
* @param {object} obj Javascript object
* @return {object} Sanitized Javascript object
* @param {Object} obj Javascript object
* @return {Object} Sanitized Javascript object
*/
export default function sanitize(obj) {
return selectFromObject(obj, (val) => !!val)

3
src/stringify_as_query_param.js
View File

@ -4,6 +4,7 @@ import queryString from 'query-string'
/**
* @private
* imported from https://github.com/bigchaindb/js-utility-belt/
*
* Takes a key-value dictionary (ie. object) and converts it to a query-parameter string that you
@ -24,7 +25,7 @@ import queryString from 'query-string'
*
* ?page=1&page_size=10
*
* @param {object} obj Query params dictionary
* @param {Object} obj Query params dictionary
* @param {function} [transform=decamelize] Transform function for each of the param keys
* @return {string} Query param string
*/

43
src/transaction.js
View File

@ -6,11 +6,13 @@ import cc from 'crypto-conditions'
import ccJsonify from './utils/ccJsonify'
import sha256Hash from './sha256Hash'
/**
* Construct Transactions
*/
export default class Transaction {
/**
* @public
* Canonically serializes a transaction into a string by sorting the keys
* @param {object} (transaction)
* @param {Object} (transaction)
* @return {string} a canonically serialized Transaction
*/
static serializeTransactionIntoCanonicalString(transaction) {
@ -54,12 +56,11 @@ export default class Transaction {
}
/**
* @public
* Generate a `CREATE` transaction holding the `asset`, `metadata`, and `outputs`, to be signed by
* the `issuers`.
* @param {object} asset Created asset's data
* @param {object} metadata Metadata for the Transaction
* @param {object[]} outputs Array of Output objects to add to the Transaction.
* @param {Object} asset Created asset's data
* @param {Object} metadata Metadata for the Transaction
* @param {Object[]} outputs Array of Output objects to add to the Transaction.
* Think of these as the recipients of the asset after the transaction.
* For `CREATE` Transactions, this should usually just be a list of
* Outputs wrapping Ed25519 Conditions generated from the issuers' public
@ -69,7 +70,7 @@ export default class Transaction {
* Note: Each of the private keys corresponding to the given public
* keys MUST be used later (and in the same order) when signing the
* Transaction (`signTransaction()`).
* @returns {object} Unsigned transaction -- make sure to call signTransaction() on it before
* @returns {Object} Unsigned transaction -- make sure to call signTransaction() on it before
* sending it off!
*/
static makeCreateTransaction(asset, metadata, outputs, ...issuers) {
@ -82,12 +83,11 @@ export default class Transaction {
}
/**
* @public
* Create an Ed25519 Cryptocondition from an Ed25519 public key
* to put into an Output of a Transaction
* @param {string} publicKey base58 encoded Ed25519 public key for the recipient of the Transaction
* @param {boolean} [json=true] If true returns a json object otherwise a crypto-condition type
* @returns {object} Ed25519 Condition (that will need to wrapped in an Output)
* @returns {Object} Ed25519 Condition (that will need to wrapped in an Output)
*/
static makeEd25519Condition(publicKey, json = true) {
const publicKeyBuffer = Buffer.from(base58.decode(publicKey))
@ -103,13 +103,12 @@ export default class Transaction {
}
/**
* @public
* Create an Output from a Condition.
* Note: Assumes the given Condition was generated from a
* single public key (e.g. a Ed25519 Condition)
* @param {object} condition Condition (e.g. a Ed25519 Condition from `makeEd25519Condition()`)
* @param {Object} condition Condition (e.g. a Ed25519 Condition from `makeEd25519Condition()`)
* @param {string} amount Amount of the output
* @returns {object} An Output usable in a Transaction
* @returns {Object} An Output usable in a Transaction
*/
static makeOutput(condition, amount = '1') {
if (typeof amount !== 'string') {
@ -134,11 +133,10 @@ export default class Transaction {
}
/**
* @public
* Create a Preimage-Sha256 Cryptocondition from a secret to put into an Output of a Transaction
* @param {string} preimage Preimage to be hashed and wrapped in a crypto-condition
* @param {boolean} [json=true] If true returns a json object otherwise a crypto-condition type
* @returns {object} Preimage-Sha256 Condition (that will need to wrapped in an Output)
* @returns {Object} Preimage-Sha256 Condition (that will need to wrapped in an Output)
*/
static makeSha256Condition(preimage, json = true) {
const sha256Fulfillment = new cc.PreimageSha256()
@ -151,12 +149,11 @@ export default class Transaction {
}
/**
* @public
* Create an Sha256 Threshold Cryptocondition from threshold to put into an Output of a Transaction
* @param {number} threshold
* @param {Array} [subconditions=[]]
* @param {boolean} [json=true] If true returns a json object otherwise a crypto-condition type
* @returns {object} Sha256 Threshold Condition (that will need to wrapped in an Output)
* @returns {Object} Sha256 Threshold Condition (that will need to wrapped in an Output)
*/
static makeThresholdCondition(threshold, subconditions = [], json = true) {
const thresholdCondition = new cc.ThresholdSha256()
@ -175,13 +172,12 @@ export default class Transaction {
}
/**
* @public
* Generate a `TRANSFER` transaction holding the `asset`, `metadata`, and `outputs`, that fulfills
* the `fulfilledOutputs` of `unspentTransaction`.
* @param {object} unspentTransaction Previous Transaction you have control over (i.e. can fulfill
* @param {Object} unspentTransaction Previous Transaction you have control over (i.e. can fulfill
* its Output Condition)
* @param {object} metadata Metadata for the Transaction
* @param {object[]} outputs Array of Output objects to add to the Transaction.
* @param {Object} metadata Metadata for the Transaction
* @param {Object[]} outputs Array of Output objects to add to the Transaction.
* Think of these as the recipients of the asset after the transaction.
* For `TRANSFER` Transactions, this should usually just be a list of
* Outputs wrapping Ed25519 Conditions generated from the public keys of
@ -191,7 +187,7 @@ export default class Transaction {
* Note that listed public keys listed must be used (and in
* the same order) to sign the Transaction
* (`signTransaction()`).
* @returns {object} Unsigned transaction -- make sure to call signTransaction() on it before
* @returns {Object} Unsigned transaction -- make sure to call signTransaction() on it before
* sending it off!
*/
// TODO:
@ -220,16 +216,15 @@ export default class Transaction {
}
/**
* @public
* Sign the given `transaction` with the given `privateKey`s, returning a new copy of `transaction`
* that's been signed.
* Note: Only generates Ed25519 Fulfillments. Thresholds and other types of Fulfillments are left as
* an exercise for the user.
* @param {object} transaction Transaction to sign. `transaction` is not modified.
* @param {Object} transaction Transaction to sign. `transaction` is not modified.
* @param {...string} privateKeys Private keys associated with the issuers of the `transaction`.
* Looped through to iteratively sign any Input Fulfillments found in
* the `transaction`.
* @returns {object} The signed version of `transaction`.
* @returns {Object} The signed version of `transaction`.
*/
static signTransaction(transaction, ...privateKeys) {
const signedTx = clone(transaction)

3
src/utils/ccJsonLoad.js
View File

@ -3,9 +3,8 @@ import base58 from 'bs58'
import cc from 'crypto-conditions'
/**
* @public
* Loads a crypto-condition class (Fulfillment or Condition) from a BigchainDB JSON object
* @param {object} conditionJson
* @param {Object} conditionJson
* @returns {cc.Condition} Ed25519 Condition (that will need to wrapped in an Output)
*/
export default function ccJsonLoad(conditionJson) {

3
src/utils/ccJsonify.js
View File

@ -1,10 +1,9 @@
import base58 from 'bs58'
/**
* @public
* Serializes a crypto-condition class (Condition or Fulfillment) into a BigchainDB-compatible JSON
* @param {cc.Fulfillment} fulfillment base58 encoded Ed25519 public key for recipient of the Transaction
* @returns {object} Ed25519 Condition (that will need to wrapped in an Output)
* @returns {Object} Ed25519 Condition (that will need to wrapped in an Output)
*/
export default function ccJsonify(fulfillment) {
let conditionUri