diff --git a/API.md b/API.md new file mode 100644 index 0000000..2e50b10 --- /dev/null +++ b/API.md @@ -0,0 +1,227 @@ + + +### 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)<[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()`). + +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)<[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` diff --git a/README.md b/README.md index a06b59c..e9a572f 100644 --- a/README.md +++ b/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 @@ -158,22 +158,3 @@ An example BigchainDB Server-generated keypair (encoded in `base58`): 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 \ No newline at end of file diff --git a/src/Ed25519Keypair.js b/src/Ed25519Keypair.js index 0bbe407..7f1f961 100644 --- a/src/Ed25519Keypair.js +++ b/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 */ diff --git a/src/connection/getBlock.js b/src/connection/getBlock.js index 1add066..252ac84 100644 --- a/src/connection/getBlock.js +++ b/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: { diff --git a/src/connection/getStatus.js b/src/connection/getStatus.js index a04ec32..dd30b29 100644 --- a/src/connection/getStatus.js +++ b/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: { diff --git a/src/connection/getTransaction.js b/src/connection/getTransaction.js index b6bdafd..20c89dc 100644 --- a/src/connection/getTransaction.js +++ b/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: { diff --git a/src/connection/listBlocks.js b/src/connection/listBlocks.js index a7c8fcc..d391433 100644 --- a/src/connection/listBlocks.js +++ b/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: { diff --git a/src/connection/listOutputs.js b/src/connection/listOutputs.js index 79a410e..6a1839a 100644 --- a/src/connection/listOutputs.js +++ b/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: { diff --git a/src/connection/listTransactions.js b/src/connection/listTransactions.js index fab731b..ab4d509 100644 --- a/src/connection/listTransactions.js +++ b/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: { diff --git a/src/connection/listVotes.js b/src/connection/listVotes.js index 0667cb1..51091bc 100644 --- a/src/connection/listVotes.js +++ b/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: { diff --git a/src/connection/pollStatusAndFetchTransaction.js b/src/connection/pollStatusAndFetchTransaction.js index daf36e4..0ba4dc3 100644 --- a/src/connection/pollStatusAndFetchTransaction.js +++ b/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(() => { diff --git a/src/connection/postTransaction.js b/src/connection/postTransaction.js index 4c5bf42..e654640 100644 --- a/src/connection/postTransaction.js +++ b/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', diff --git a/src/transaction/index.js b/src/transaction/index.js index 49a9614..939ae7e 100644 --- a/src/transaction/index.js +++ b/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'; diff --git a/src/transaction/makeCreateTransaction.js b/src/transaction/makeCreateTransaction.js index 20476ac..597dcb9 100644 --- a/src/transaction/makeCreateTransaction.js +++ b/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 diff --git a/src/transaction/makeEd25519Condition.js b/src/transaction/makeEd25519Condition.js index 1bc4e26..4c6b7bb 100644 --- a/src/transaction/makeEd25519Condition.js +++ b/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) { diff --git a/src/transaction/makeOutput.js b/src/transaction/makeOutput.js index 55eeed6..fa15747 100644 --- a/src/transaction/makeOutput.js +++ b/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()`) diff --git a/src/transaction/makeSha256Condition.js b/src/transaction/makeSha256Condition.js index 234cd3e..72ef2ef 100644 --- a/src/transaction/makeSha256Condition.js +++ b/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) { diff --git a/src/transaction/makeThresholdCondition.js b/src/transaction/makeThresholdCondition.js index dafcd03..1dc4c9d 100644 --- a/src/transaction/makeThresholdCondition.js +++ b/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) { diff --git a/src/transaction/makeTransferTransaction.js b/src/transaction/makeTransferTransaction.js index bc06b3a..c5813c0 100644 --- a/src/transaction/makeTransferTransaction.js +++ b/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 diff --git a/src/transaction/serializeTransactionIntoCanonicalString.js b/src/transaction/serializeTransactionIntoCanonicalString.js index 65d2fe8..bf97d55 100644 --- a/src/transaction/serializeTransactionIntoCanonicalString.js +++ b/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)); } \ No newline at end of file diff --git a/src/transaction/signTransaction.js b/src/transaction/signTransaction.js index dc1e154..7b974a0 100644 --- a/src/transaction/signTransaction.js +++ b/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 diff --git a/src/transaction/utils/ccJsonLoad.js b/src/transaction/utils/ccJsonLoad.js index e756553..a6707cc 100644 --- a/src/transaction/utils/ccJsonLoad.js +++ b/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) */ diff --git a/src/transaction/utils/ccJsonify.js b/src/transaction/utils/ccJsonify.js index 3380e27..f8ae532 100644 --- a/src/transaction/utils/ccJsonify.js +++ b/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) */