Merge pull request #3 from ascribe/feature/styling-functional

driver docs

API.md

@@ -0,0 +1,227 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### 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)
+-   [getTransaction](#gettransaction)
+-   [getStatus](#getstatus)
+-   [listBlocks](#listblocks)
+-   [listOutputs](#listoutputs)
+-   [listTransactions](#listtransactions)
+-   [listVotes](#listvotes)
+-   [pollStatusAndFetchTransaction](#pollstatusandfetchtransaction)
+-   [postTransaction](#posttransaction)
+
+## Ed25519Keypair
+
+**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
+
+**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)** 
+
+## makeEd25519Condition
+
+**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`)
+
+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)
+
+## makeSha256Condition
+
+**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`)
+
+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)
+
+## makeThresholdCondition
+
+**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`)
+
+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)
+
+## makeCreateTransaction
+
+**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)&lt;[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)&lt;[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()`).
+
+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!
+
+## makeOutput
+
+**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`)
+
+Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** An Output usable in a Transaction
+
+## makeTransferTransaction
+
+**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)&lt;[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()`).
+
+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!
+
+## 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
+
+**Parameters**
+
+-   `blockId`  
+-   `API_PATH`  
+
+## getTransaction
+
+**Parameters**
+
+-   `txId`  
+-   `API_PATH`  
+
+## getStatus
+
+**Parameters**
+
+-   `tx_id`  
+-   `API_PATH`  
+
+## listBlocks
+
+**Parameters**
+
+-   `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+    -   `$0.tx_id`  
+    -   `$0.status`  
+-   `API_PATH`  
+-   `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`  
+-   `API_PATH`  
+-   `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`  
+-   `API_PATH`  
+-   `asset_id`  
+-   `operation`  
+
+## listVotes
+
+**Parameters**
+
+-   `block_id`  
+-   `API_PATH`  
+
+## pollStatusAndFetchTransaction
+
+**Parameters**
+
+-   `tx_id`  
+-   `API_PATH`  
+
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** 
+
+## postTransaction
+
+**Parameters**
+
+-   `transaction`  
+-   `API_PATH`  

README.md

@@ -17,7 +17,7 @@ of which I expect you'll know quite well ([otherwise, go check out js-reactor](h
 - [Usage](#usage)
 - [Speed Optimizations](#speed-optimizations)
 - [Warnings](#warnings)
-- [API](#api)
+- [API](API.md)
 
 ## Getting started
 
@@ -141,23 +141,4 @@ An example BigchainDB Server-generated keypair (encoded in `base58`):
 - Private: `7Gf5YRch2hYTyeLxqNLgTY63D9K5QH2UQ7LYFeBGuKvo`
 
 Your package should be able to take in the decoded version of the **private** key and return you the
-same **public** key (once you encode that to `base58`).
-
-
-## API
-
-### Keypairs
-
-```
-new Ed25519Keypair(secret)
-```
-
-### Transaction
-
-```
-Transaction(secret)
-```
-
-
-
-### Connection
+same **public** key (once you encode that to `base58`).

src/Ed25519Keypair.js

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

src/connection/getBlock.js

@@ -1,7 +1,11 @@
 import getApiUrls from './getApiUrls';
 import request from '../request';
 
-
+/**
+ * @public
+ * @param blockId
+ * @param API_PATH
+ */
 export default function getBlock(blockId, API_PATH) {
     return request(getApiUrls(API_PATH)['blocks_detail'], {
             urlTemplateSpec: {

src/connection/getStatus.js

@@ -1,7 +1,11 @@
 import getApiUrls from './getApiUrls';
 import request from '../request';
 
-
+/**
+ * @public
+ * @param tx_id
+ * @param API_PATH
+ */
 export default function getStatus(tx_id, API_PATH) {
     return request(getApiUrls(API_PATH)['statuses'], {
             query: {

src/connection/getTransaction.js

@@ -1,7 +1,11 @@
 import getApiUrls from './getApiUrls';
 import request from '../request';
 
-
+/**
+ * @public
+ * @param txId
+ * @param API_PATH
+ */
 export default function getTransaction(txId, API_PATH) {
     return request(getApiUrls(API_PATH)['transactions_detail'], {
             urlTemplateSpec: {

src/connection/listBlocks.js

@@ -1,7 +1,12 @@
 import getApiUrls from './getApiUrls';
 import request from '../request';
 
-
+/**
+ * @public
+ * @param tx_id
+ * @param status
+ * @param API_PATH
+ */
 export default function listBlocks({tx_id, status}, API_PATH) {
     return request(getApiUrls(API_PATH)['blocks'], {
             query: {

src/connection/listOutputs.js

@@ -1,7 +1,13 @@
 import getApiUrls from './getApiUrls';
 import request from '../request';
 
-
+/**
+ * @public
+ * @param public_key
+ * @param unspent
+ * @param API_PATH
+ * @param onlyJsonResponse
+ */
 export default function listOutputs({ public_key, unspent }, API_PATH, onlyJsonResponse=true) {
     return request(getApiUrls(API_PATH)['outputs'], {
         query: {

src/connection/listTransactions.js

@@ -1,7 +1,12 @@
 import getApiUrls from './getApiUrls';
 import request from '../request';
 
-
+/**
+ * @public
+ * @param asset_id
+ * @param operation
+ * @param API_PATH
+ */
 export default function listTransactions({ asset_id, operation }, API_PATH) {
     return request(getApiUrls(API_PATH)['transactions'], {
         query: {

src/connection/listVotes.js

@@ -1,7 +1,11 @@
 import getApiUrls from './getApiUrls';
 import request from '../request';
 
-
+/**
+ * @public
+ * @param block_id
+ * @param API_PATH
+ */
 export default function listVotes(block_id, API_PATH) {
     return request(getApiUrls(API_PATH)['votes'], {
             query: {

src/connection/pollStatusAndFetchTransaction.js

@@ -1,7 +1,12 @@
 import getTransaction from './getTransaction';
 import getStatus from './getStatus';
 
-
+/**
+ * @public
+ * @param tx_id
+ * @param API_PATH
+ * @return {Promise}
+ */
 export default function (tx_id, API_PATH) {
     return new Promise((resolve, reject) => {
         const timer = setInterval(() => {

src/connection/postTransaction.js

@@ -1,7 +1,12 @@
 import getApiUrls from './getApiUrls';
 import request from '../request';
 
-
+/**
+ * @public
+ *
+ * @param transaction
+ * @param API_PATH
+ */
 export default function postTransaction(transaction, API_PATH) {
     return request(getApiUrls(API_PATH)['transactions'], {
         method: 'POST',

src/transaction/index.js

@@ -8,3 +8,4 @@ export makeTransferTransaction from './makeTransferTransaction';
 export serializeTransactionIntoCanonicalString from './serializeTransactionIntoCanonicalString';
 export signTransaction from './signTransaction';
 export ccJsonLoad from './utils/ccJsonLoad';
+export ccJsonify from './utils/ccJsonify';

src/transaction/makeCreateTransaction.js

@@ -1,7 +1,9 @@
 import makeInputTemplate from './makeInputTemplate';
 import makeTransaction from './makeTransaction';
 
+
 /**
+ * @public
  * Generate a `CREATE` transaction holding the `asset`, `metadata`, and `outputs`, to be signed by
  * the `issuers`.
  * @param {object} asset Created asset's data

src/transaction/makeEd25519Condition.js

@@ -7,9 +7,10 @@ import ccJsonify from './utils/ccJsonify';
 
 
 /**
+ * @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 {bool} json If true returns a json object otherwise a crypto-condition type
+ * @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)
  */
 export default function makeEd25519Condition(publicKey, json=true) {

src/transaction/makeOutput.js

@@ -1,4 +1,5 @@
 /**
+ * @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()`)

src/transaction/makeSha256Condition.js

@@ -4,10 +4,12 @@ import cc from 'five-bells-condition';
 
 import ccJsonify from './utils/ccJsonify';
 
+
 /**
+ * @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 {bool} json If true returns a json object otherwise a crypto-condition type
+ * @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)
  */
 export default function makeSha256Condition(preimage, json=true) {

src/transaction/makeThresholdCondition.js

@@ -1,14 +1,14 @@
-import { Buffer } from 'buffer';
-
-import base58 from 'bs58';
 import cc from 'five-bells-condition';
 
 import ccJsonify from './utils/ccJsonify';
+
+
 /**
+ * @public
  * Create an Sha256 Threshold Cryptocondition from threshold to put into an Output of a Transaction
  * @param {number} threshold
- * @param {array} subconditions
- * @param {bool} json If true returns a json object otherwise a crypto-condition type
+ * @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)
  */
 export default function makeThresholdCondition(threshold, subconditions=[], json=true) {

src/transaction/makeTransferTransaction.js

@@ -1,7 +1,9 @@
 import makeInputTemplate from './makeInputTemplate';
 import makeTransaction from './makeTransaction';
 
+
 /**
+ * @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

src/transaction/serializeTransactionIntoCanonicalString.js

@@ -2,9 +2,16 @@ import stableStringify from 'json-stable-stringify';
 import clone from 'clone';
 
 
+/**
+ * @public
+ * Canonically serializes a transaction into a string by sorting the keys
+ * @param {object} (transaction)
+ * @return {string} a canonically serialized Transaction
+ */
 export default function serializeTransactionIntoCanonicalString(transaction) {
     // BigchainDB signs fulfillments by serializing transactions into a "canonical" format where
     const tx = clone(transaction);
+    // TODO: set fulfillments to null
     // Sort the keys
     return stableStringify(tx, (a, b) => (a.key > b.key ? 1 : -1));
 }

src/transaction/signTransaction.js

@@ -7,6 +7,7 @@ import serializeTransactionIntoCanonicalString from './serializeTransactionIntoC
 
 
 /**
+ * @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

src/transaction/utils/ccJsonLoad.js

@@ -3,7 +3,8 @@ import cc from 'five-bells-condition';
 import { Buffer } from 'buffer';
 
 /**
- *
+ * @public
+ * Loads a crypto-condition class (Fulfillment or Condition) from a BigchainDB JSON object
  * @param {object} conditionJson
  * @returns {cc.Condition} Ed25519 Condition (that will need to wrapped in an Output)
  */

src/transaction/utils/ccJsonify.js

@@ -1,7 +1,8 @@
 import base58 from 'bs58';
 
 /**
- * Create an Ed25519 Cryptocondition from an Ed25519 public key to put into an Output of a Transaction
+ * @public
+ * Serializes a crypto-condition class (Condition or Fulfillment) into a BigchainDB-compatible JSON
  * @param {cc.Fulfillment} fulfillment base58 encoded Ed25519 public key for the recipient of the Transaction
  * @returns {object} Ed25519 Condition (that will need to wrapped in an Output)
  */