From 81ef5978b83719974bcc6a4f1b52270e31669c01 Mon Sep 17 00:00:00 2001 From: Matthias Kretschmann Date: Mon, 14 May 2018 17:14:40 +0200 Subject: [PATCH] API docs & dev updates * new command: npm run doc, for generating the API.md file * new command: npm run dev, for live watching webpack * JSdoc: make all methods public by default, selectively make some private * JSdoc: organize all methods under their class * linting fixes * package updates --- .babelrc | 9 +- API.md | 534 ++++++++++++++++++++++---------- README.md | 16 + package.json | 14 +- src/Ed25519Keypair.js | 2 +- src/baseRequest.js | 13 +- src/connection.js | 17 +- src/format_text.js | 5 +- src/request.js | 2 +- src/sanitize.js | 14 +- src/stringify_as_query_param.js | 3 +- src/transaction.js | 45 ++- src/utils/ccJsonLoad.js | 3 +- src/utils/ccJsonify.js | 3 +- 14 files changed, 445 insertions(+), 235 deletions(-) diff --git a/.babelrc b/.babelrc index 5fb0a13..07af000 100644 --- a/.babelrc +++ b/.babelrc @@ -1,10 +1,11 @@ { - "presets": ["env"], - + "presets": [ + "env" + ], "plugins": [ "transform-export-extensions", "transform-object-assign", "transform-object-rest-spread" ], - "sourceMaps": true, -} + "sourceMaps": true +} \ No newline at end of file diff --git a/API.md b/API.md index 08e2295..d7e3808 100644 --- a/API.md +++ b/API.md @@ -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" diff --git a/README.md b/README.md index ad0440d..2737839 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ - [Browser usage](#browser-usage) - [BigchainDB Documentation](#bigchaindb-documentation) - [Speed Optimizations](#speed-optimizations) + - [Development](#development) - [Authors](#authors) - [License](#license) @@ -162,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 diff --git a/package.json b/package.json index ffe1018..440bdd8 100644 --- a/package.json +++ b/package.json @@ -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": { @@ -104,4 +106,4 @@ ], "babel": "inherit" } -} +} \ No newline at end of file diff --git a/src/Ed25519Keypair.js b/src/Ed25519Keypair.js index f6b07d9..4de118d 100644 --- a/src/Ed25519Keypair.js +++ b/src/Ed25519Keypair.js @@ -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 diff --git a/src/baseRequest.js b/src/baseRequest.js index b4b6d38..6825630 100644 --- a/src/baseRequest.js +++ b/src/baseRequest.js @@ -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; @@ -47,8 +46,8 @@ export default function baseRequest(url, { // Use vsprintf for the array call signature expandedUrl = vsprintf(url, urlTemplateSpec) } else if (urlTemplateSpec && - typeof urlTemplateSpec === 'object' && - Object.keys(urlTemplateSpec).length) { + typeof urlTemplateSpec === 'object' && + Object.keys(urlTemplateSpec).length) { expandedUrl = formatText(url, urlTemplateSpec) } else if (process.env.NODE_ENV !== 'production') { // eslint-disable-next-line no-console diff --git a/src/connection.js b/src/connection.js index 75f391b..fb31fbc 100644 --- a/src/connection.js +++ b/src/connection.js @@ -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) { diff --git a/src/format_text.js b/src/format_text.js index 38f697a..b24203c 100644 --- a/src/format_text.js +++ b/src/format_text.js @@ -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 @@ -69,7 +70,7 @@ export default function formatText(s, ...argv) { // Assigning in the conditionals here makes the code less bloated /* eslint-disable no-cond-assign */ while ((interpolationLeft = interpolationLeft.substring(curMatch[0].length)) && - value != null) { + value != null) { if ((curMatch = Regex.KEY_ACCESS.exec(interpolationLeft))) { value = value[curMatch[1]] } else if ((curMatch = Regex.INDEX_ACCESS.exec(interpolationLeft))) { diff --git a/src/request.js b/src/request.js index 9b0a622..1e45574 100644 --- a/src/request.js +++ b/src/request.js @@ -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. */ diff --git a/src/sanitize.js b/src/sanitize.js index b436545..9aa6b25 100644 --- a/src/sanitize.js +++ b/src/sanitize.js @@ -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) diff --git a/src/stringify_as_query_param.js b/src/stringify_as_query_param.js index abff250..714fb48 100644 --- a/src/stringify_as_query_param.js +++ b/src/stringify_as_query_param.js @@ -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 */ diff --git a/src/transaction.js b/src/transaction.js index d64e7dd..fc0b75d 100644 --- a/src/transaction.js +++ b/src/transaction.js @@ -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) @@ -251,7 +246,7 @@ export default class Transaction { }) const serializedTransaction = - Transaction.serializeTransactionIntoCanonicalString(signedTx) + Transaction.serializeTransactionIntoCanonicalString(signedTx) signedTx.id = sha256Hash(serializedTransaction) return signedTx } diff --git a/src/utils/ccJsonLoad.js b/src/utils/ccJsonLoad.js index e4b5f20..a364737 100644 --- a/src/utils/ccJsonLoad.js +++ b/src/utils/ccJsonLoad.js @@ -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) { diff --git a/src/utils/ccJsonify.js b/src/utils/ccJsonify.js index 3325c6c..cb59de9 100644 --- a/src/utils/ccJsonify.js +++ b/src/utils/ccJsonify.js @@ -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