Feat/update doc strings

README.md

@@ -1,6 +1,4 @@
-<p align="center">
-  <b style="font-size: 32px;">Kleros API</b>
-</p>
+# Kleros API
 
 <p align="center">
   <a href="https://badge.fury.io/js/kleros-api"><img src="https://badge.fury.io/js/kleros-api.svg" alt="NPM Version"></a>
@@ -15,55 +13,83 @@
   <a href="http://commitizen.github.io/cz-cli/"><img src="https://img.shields.io/badge/commitizen-friendly-brightgreen.svg" alt="Commitizen Friendly"></a>
 </p>
 
-> This repository contains a Javascript library that makes it easy to build Relayers and other DApps that use the Kleros protocol.
+> This repository contains a Javascript library that provides methods to interact with Kleros arbitrator
+  and Arbitrable contracts. It can be used to develop Relayers or DApps that use Kleros smart contracts.
 
 ## Installation
+```
+yarn add kleros-api
+```
 
-We assume that you have node and yarn installed.
+## Basic Usage
 
-```sh
-yarn install
-```
+See the full API docs [here](https://kleros.io/kleros-api/).
 
-## Test
+The base Kleros object initializes all of the different kleros api's with the contract
+addresses you pass. This object is useful if your application interacts with both arbitrators,
+arbitrable contracts and uses an off chain store to provide metadata on the different disputes
+for the UI.
 
-```sh
-yarn run ganache-cli
-yarn test
 ```
+// pay arbitration fee.
+import Kleros from 'kleros-api'
 
-## Develop
+const KlerosInstance = new Kleros(
+  ETH_PROVIDER, // ethereum provider object
+  KLEROS_STORE_URI, // uri of off chain storage e.g. https://kleros.in
+  ARITRATOR_CONTRACT_ADDRESS, // address of a deployed Kleros arbitrator contract
+  ARBITRABLE_CONTRACT_ADDRESS // address of a deployed arbitrable transaction contract
+)
 
-```sh
-yarn start
+KlerosInstance.arbitrable.payArbitrationFeeByPartyA() // pay arbitration fee for an arbitrable contract
 ```
 
-## Build
+You can also use the specific api that best suits your needs.
 
-```sh
-yarn run build
+```
+// deploy a new contract and pay the arbitration fee.
+import ArbitrableTransaction from 'kleros-api/contracts/implementations/arbitrable/ArbitrableTransaction'
+
+// deploy methods are static
+const contractInstance = ArbitrableTransaction.deploy(
+    "0x67a3f2BB8B4B2060875Bd6543156401B817bEd22", // users address
+    0.15, // amount of ETH to escrow
+    "0x0", // hash of the off chain contract
+    "0x3af76ef44932695a33ba2af52018cd24a74c904f", // arbitrator address
+    3600, // number of seconds until there is a timeout
+    "0x0474b723bd4986808366E0DcC2E301515Aa742B4", // the other party in the contract
+    "0x0", // extra data in bytes. This can be used to interact with the arbitrator contract
+    ETH_PROVIDER, // provider object to be used to interact with the network
+  )
+
+const address = contractInstance.address // get the address of your newly created contract
+
+const ArbitrableTransactionInstance = new ArbitrableTransaction(address) // instantiate instance of the api
+
+ArbitrableTransactionInstance.payArbitrationFeeByPartyA() // pay arbitration fee
 ```
 
-## Event Listeners
+## Development
 
-For notifications and event based updates, the api uses event listeners. In order to register and start listening to events, use these methods:
+If you want to contribute to our api or modify it for your usage
 
-##### Quick Start
+## Setup
 
-To register all events and start the listener, call:
+We assume that you have node and yarn installed.
 
 ```sh
-KlerosInstance.watchForEvents(arbitratorAddress, account, callback)
+yarn install
 ```
 
-params:
+## Test
 
-* arbitratorAddress: Address of arbitrator contract. Needed to update the store for disputes.
-* account: <optional> Address used for notification callbacks. If an address is provided, push notifications will only be sent for notifications that involve the address. If it is omitted and a callback is included, all notifications will be pushed.
-* callback: <optional> Function to be called for push notifications.
+```sh
+yarn run ganache-cli
+yarn test
+```
 
-##### Stop Listener
+## Build
 
 ```sh
-KlerosInstance.eventListener.stopWatchingArbitratorEvents(arbitratorAddress)
+yarn run build
 ```

deploy_docs.sh

@@ -0,0 +1,18 @@
+# Remove old docs dir
+rm -rf docs || exit 0;
+# Build docs
+yarn run docs;
+
+# Set up new directory
+mkdir ../esdocs;
+cp -r docs/* ../esdocs/;
+
+# github pages. must be run by user with ssh write access to kleros-api
+cd ../esdocs;
+git init;
+git add .;
+git commit -m "Deploy to GitHub Pages";
+git push --force --quiet "git@github.com:kleros/kleros-api.git" master:gh-pages;
+
+# cleanup
+rm -rf ../esdocs;

package.json

@@ -19,6 +19,7 @@
   "license": "MIT",
   "private": false,
   "scripts": {
+    "docs": "esdoc",
     "prettify": "kleros-scripts prettify",
     "lint": "kleros-scripts lint:js --config ./.eslintrc.js",
     "ganache": "ganache-cli -a 15",

src/contracts/AbstractContract.js

@@ -3,6 +3,11 @@ import _ from 'lodash'
 import isRequired from '../utils/isRequired'
 import delegateCalls from '../utils/delegateCalls'
 
+/**
+ * Abstract Contract holds a contract implementation to make calls to the blockchain but
+ * also includes methods that interact with the off chain store. NOTE all methods that
+ * the underlying contract implementation expose can be called directly from an Abstract contract.
+ */
 class AbstractContract {
   /**
    * AbstractContract wraps an implementation instance to provide access to higher level

src/contracts/ContractImplementation.js

@@ -2,9 +2,13 @@ import contract from 'truffle-contract'
 import _ from 'lodash'
 
 import isRequired from '../utils/isRequired'
-import * as errorConstants from '../constants/error'
+import * as errorConstants from '../../constants/error'
 import Web3Wrapper from '../utils/Web3Wrapper'
 
+/**
+ * ContractImplementation is a parent class for on chain contracts. It loads the contract from the
+ * blockchain and exposes the contract instance for use by the child.
+ */
 class ContractImplementation {
   constructor(
     web3Provider = isRequired('web3Provider'),
@@ -120,14 +124,21 @@ class ContractImplementation {
     }
   }
 
+  /**
+   * Create a new Promise to be used in loading the contract.
+   * @returns {Promise} - Resolves to contract instance.
+   */
   _newLoadingPromise = () =>
     new Promise((resolve, reject) => {
       this._contractLoadedResolver = resolve
       this._contractLoadedRejecter = reject
     })
 
   // we have getters so that abstract classes can provide public access to implementations variables
-  getContractInstance = () => this.contractInstance
+  /**
+   * Get the contract address for the currently instantiated contract.
+   * @returns {string} - The address of the contract.
+   */
   getContractAddress = () => this.contractAddress
 }
 

src/contracts/abstractions/Arbitrable.js

@@ -1,7 +1,10 @@
 import AbstractContract from '../AbstractContract'
 
 /**
- * Arbitrable Contract API.
+ * Arbitrable Abstract Contarct API. This wraps an arbitrable contract. It provides
+ * interaction with both the off chain store as well as the arbitrable instance. All
+ * arbitrable methods from the supplied contract implementation can be called from this
+ * object.
  */
 class ArbitrableContract extends AbstractContract {
   /**

src/contracts/abstractions/Arbitrator.js

@@ -1,10 +1,13 @@
 import _ from 'lodash'
 
-import * as arbitratorConstants from '../../constants/arbitrator'
+import * as arbitratorConstants from '../../../constants/arbitrator'
 import AbstractContract from '../AbstractContract'
 
 /**
- * Arbitrator API.
+ * Arbitrator Abstract Contarct API. This wraps an arbitrator contract. It provides
+ * interaction with both the off chain store as well as the arbitrator instance. All
+ * arbitrator methods from the supplied contract implementation can be called from this
+ * object.
  */
 class Arbitrator extends AbstractContract {
   /**

src/contracts/implementations/PNK/PinakionPOC.js

@@ -1,17 +1,17 @@
 import PinakionPOCArtifact from 'kleros/build/contracts/PinakionPOC' // FIXME: mock
 import _ from 'lodash'
 
-import * as ethConstants from '../../../constants/eth'
-import * as errorConstants from '../../../constants/error'
+import * as ethConstants from '../../../../constants/eth'
+import * as errorConstants from '../../../../constants/error'
 import ContractImplementation from '../../ContractImplementation'
 import deployContractAsync from '../../../utils/deployContractAsync'
 
 /**
- * Kleros API
+ * Provides interaction with a PinakionPOC contract deployed on the blockchain.
  */
 class PinakionPOC extends ContractImplementation {
   /**
-   * Constructor Kleros.
+   * Constructor PinakionPOC.
    * @param {object} web3Provider - web3 instance.
    * @param {string} contractAddress - of the contract (optionnal).
    */
@@ -20,7 +20,7 @@ class PinakionPOC extends ContractImplementation {
   }
 
   /**
-   * Kleros deploy.
+   * Deploy a new instance of PinakionPOC.
    * @param {string} account - account of user
    * @param {object} web3Provider - web3 provider object
    * @returns {object} - 'truffle-contract' Object | err The contract object or error deploy.
@@ -37,7 +37,7 @@ class PinakionPOC extends ContractImplementation {
   }
 
   /**
-   * change the kleros contract in the PNK contract.
+   * Change the kleros contract variable in instance of PinakionPOC.
    * @param {string} klerosAddress - Address of Kleros POC contract.
    * @param {string} account - Address of user.
    * @returns {object} - The result transaction object.
@@ -60,7 +60,7 @@ class PinakionPOC extends ContractImplementation {
   }
 
   /**
-   * transfer ownership of the PNK contract to the kleros POC contract.
+   * Transfer ownership of the PNK contract to the kleros POC contract.
    * @param {string} klerosAddress - Address of Kleros POC contract.
    * @param {string} account - Address of user.
    * @returns {object} - The result transaction object.

src/contracts/implementations/RNG/BlockHashRNG.js

@@ -1,16 +1,16 @@
 import BlockHashRNGArtifact from 'kleros-interaction/build/contracts/BlockHashRNG'
 import _ from 'lodash'
 
-import * as ethConstants from '../../../constants/eth'
+import * as ethConstants from '../../../../constants/eth'
 import ContractImplementation from '../../ContractImplementation'
 import deployContractAsync from '../../../utils/deployContractAsync'
 
 /**
- * Kleros API
+ * Provides interaction with an instance of BlockHashRNG.
  */
 class BlockHashRNG extends ContractImplementation {
   /**
-   * Constructor Kleros.
+   * Constructor BlockHashRNG.
    * @param {object} web3Provider - instance
    * @param {string} contractAddress - of the contract (optionnal)
    */
@@ -19,7 +19,7 @@ class BlockHashRNG extends ContractImplementation {
   }
 
   /**
-   * Kleros deploy.
+   * BlockHashRNG deploy.
    * @param {string} account - users account
    * @param {object} web3Provider - web3 provider object
    * @returns {object} - truffle-contract Object | err The contract object or error deploy

src/contracts/implementations/RNG/index.js

@@ -1,3 +1,3 @@
-import _BlockHashRNG from './BlockHashRNG'
+import BlockHashRNG from './BlockHashRNG'
 
-export const BlockHashRNG = _BlockHashRNG
+export { BlockHashRNG }

src/contracts/implementations/arbitrable/ArbitrableTransaction.js

@@ -1,14 +1,14 @@
 import arbitrableTransactionArtifact from 'kleros-interaction/build/contracts/ArbitrableTransaction'
 import _ from 'lodash'
 
-import * as ethConstants from '../../../constants/eth'
-import * as contractConstants from '../../../constants/contract'
-import * as errorConstants from '../../../constants/error'
+import * as ethConstants from '../../../../constants/eth'
+import * as contractConstants from '../../../../constants/contract'
+import * as errorConstants from '../../../../constants/error'
 import ContractImplementation from '../../ContractImplementation'
 import deployContractAsync from '../../../utils/deployContractAsync'
 
 /**
- * ArbitrableTransaction API
+ * Provides interaction with an Arbitrable Transaction contract deployed on the blockchain.
  */
 class ArbitrableTransaction extends ContractImplementation {
   /**
@@ -217,7 +217,6 @@ class ArbitrableTransaction extends ContractImplementation {
 
   /**
    * Get ruling options from dispute via event
-   * FIXME this can be an abstract method as it is in the standard
    * @param {string} arbitratorAddress address of arbitrator contract
    * @param {number} disputeId index of dispute
    * @returns {object[]} an array of objects that specify the name and value of the resolution option

src/contracts/implementations/arbitrator/KlerosPOC.js

@@ -1,18 +1,18 @@
 import klerosArtifact from 'kleros/build/contracts/KlerosPOC'
 import _ from 'lodash'
 
-import * as ethConstants from '../../../constants/eth'
-import * as errorConstants from '../../../constants/error'
-import * as arbitratorConstants from '../../../constants/arbitrator'
+import * as ethConstants from '../../../../constants/eth'
+import * as errorConstants from '../../../../constants/error'
+import * as arbitratorConstants from '../../../../constants/arbitrator'
 import ContractImplementation from '../../ContractImplementation'
 import deployContractAsync from '../../../utils/deployContractAsync'
 
 /**
- * Kleros API
+ * Provides interaction with a KlerosPOC contract on the blockchain.
  */
 class KlerosPOC extends ContractImplementation {
   /**
-   * Constructor Kleros.
+   * Create new KlerosPOC Implementation.
    * @param {object} web3Provider - web3 instance.
    * @param {string} contractAddress - Address of the KlerosPOC contract.
    */
@@ -21,7 +21,7 @@ class KlerosPOC extends ContractImplementation {
   }
 
   /**
-   * STATIC: Deploy a kleros instance
+   * STATIC: Deploy a KlerosPOC contract on the blockchain.
    * @param {string} rngAddress address of random number generator contract
    * @param {string} pnkAddress address of pinakion contract
    * @param {number[]} timesPerPeriod array of 5 ints indicating the time limit for each period of contract
@@ -52,7 +52,7 @@ class KlerosPOC extends ContractImplementation {
   }
 
   /**
-   * Use Arbitrator.buyPNK
+   * Purchase PNK.
    * @param {string} amount - The number of pinakion to buy.
    * @param {string} account - The address of the user.
    * @returns {object} - The result transaction object.
@@ -113,7 +113,6 @@ class KlerosPOC extends ContractImplementation {
 
   /**
    * Activate Pinakion tokens to be eligible to be a juror.
-   * FIXME use estimateGas
    * @param {string} amount - number of tokens to activate.
    * @param {string} account - address of user.
    * @returns {object} - PNK balance.
@@ -141,7 +140,7 @@ class KlerosPOC extends ContractImplementation {
   }
 
   /**
-   * Fetch the cost of arbitration
+   * Fetch the cost of arbitration.
    * @param {bytes} contractExtraData - extra data from arbitrable contract.
    * @returns {number} - The cost of arbitration.
    */