kleros / kleros-api-deprecated

A Javascript library that makes it easy to build relayers and other DApps that use the Kleros protocol. DEPRECATED use https://github.com/kleros/archon for interfacing with standard arbitration contracts.

Kleros API

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

Basic Usage

See the full API docs here.

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.

// pay arbitration fee.
import Kleros from 'kleros-api'

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
)

KlerosInstance.arbitrable.payArbitrationFeeByPartyA() // pay arbitration fee for an arbitrable contract

You can also use the specific api that best suits your needs.

// 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

Development

If you want to contribute to our api or modify it for your usage

Setup

We assume that you have node and yarn installed.

yarn install

Test

yarn ganache
yarn test

Build

yarn run build

kleros-api-deprecated's Issues

Wrong values sometimes returned

This issue can be hard to reproduce. It can be seen in the logs of Kleros-Bot. The particular method that returns false values sometimes from Kleros-Bot is getTimeForPeriod in ContractWrappers/KlerosPOC.js.

Example:

Contract: 0xe533d0bd81b3ebf62938726e2b966c5e84e7eed8 with times [300,0,300,300,300] returns [0,0,0,300,0] first time called and [300, 0, 300, 0, 300] the next. My hypothesis is when the network is congested the api isn't waiting long enough for a response and interprets no response as 0. Seems to happen when having issues with no code at address bug

Throw Semantic Errors For The UI

Throw errors that the UI can show to the user.

Enables kleros/kleros-juror-front#10

Don't assume 1 dispute per contract

A lot of src/abstractWrappers/Disputes relies on the assumption that there will only be one dispute per contract. This is not a guarantee for future arbitrable contracts. Refactor to find disputes by arbitratorAddress + disputeId instead of arbitrableContractAddress

Dispute Properties

For sorting (rulings of all appeals + evidence submissions) by date.

I suggest we replace voteCounters and netPNK on disputes with rulings, with shape:

const dispute = {
  // Arbitrable Contract Data
  hash: arbitrableContractAddress, // Not needed
  arbitrableContractAddress,
  arbitrableContractStatus: arbitrableContractData.status,
  arbitratorAddress,
  partyA: arbitrableContractData.partyA,
  partyB: arbitrableContractData.partyB,

  // Dispute Data
  disputeId,
  session: dispute.firstSession + dispute.numberOfAppeals,
  numberOfAppeals: dispute.numberOfAppeals,
  fee: dispute.arbitrationFeePerJuror, // This can be rolled up into an array with `votes` (one item per appeal)
  deadline, // Should show the last date you could vote not the time when the current period ends
  disputeState: dispute.state,
  disputeStatus: dispute.status,
  voteCounters: dispute.voteCounters, // Not needed after `rulings` is implemented

  // Store Data
  description: constractStoreData ? constractStoreData.description : undefined,
  email: constractStoreData ? constractStoreData.email : undefined,
  votes, // This can be rolled up into an array with `fee` (one item per appeal)
  isJuror,
  hasRuled, // Can be replaced with `canVote`
  ruling, // Replaced with `rulings` ({ date, votes }) array (one item per appeal)
  evidence,
  netPNK
}

Handle disputes from different arbitrators

Disputes are stored irregardless of which arbitrator they use and are all fetched at the same time from the store. When returning results from the store always filter by the current arbitrator so we don't get disputes we can't interact with

Unit Tests for StoreWrapper

Keep track of who submitted which evidence/s

The new front end requires this. Is it possible?

Avoid searching through all New Period events

When a new user is looking for notifications on an arbitrator that has many periods it is really slow for them to get caught up.

Things that might help:

• New users start with lastBlock at current block (ignore all old events)
• For open disputes open one time handlers. Listen for events in a session range and then discard the handler

Test for kleros

There is no test for the base kleros api which is what we actually use in our front ends. Make a test that ensures all classes are bootstrapping correctly and event listener is being set up with all the correct handlers.

Wrong Dispute ID Being Returned

Dispute ID is 40 when it should be 4.

Handle errors in interactions with contracts

After tx's are successfully mined there can still be errors. For example voting during the wrong period will be rejected by the contract. However at the moment we are only throwing errors if a tx fails to be submitted. We need a way to watch tx's and revert store updates/state if an action is unsuccessful

add summary in the README

see an example on https://github.com/kleros/kleros-store

EventListener, Missed Events by Handler

TODO:

• EventListener should have a method to start itself or it should start itself in its constructor.
• Notifications and Disputes should only add handlers to EventListener.
• The lastBlock that is kept track of in order to call handlers on missed events should be handler specific, because only a subset of handlers may have been on when an event happened, (or a better solution for this).

add missing timeOutByPartyA() and timeOutByPartyA() functions

Add these functions, see https://github.com/kleros/kleros-interaction/blob/330568a6d0345af87395af40422aa43696749860/contracts/standard/arbitration/TwoPartyArbitrable.sol#L108 in https://github.com/kleros/kleros-api/blob/develop/src/contractWrappers/ArbitrableTransactionWrapper.js

Break out all getData methods in contractWrappers

e.x. instead of one getData method that returns session, period, timePerPeriod etc split them all up into individual getters

Unit Tests for Notifications

Implement notifications APIs

Jurors:

Notifications:

• Session started (register)/Able to activate tokens (automatically dismissed if not done manually by end of session)
• Drawn in dispute (we can handle this with a poll if we need too) postponed
• ArbitrationFee collected
• Ruling took place
• Dispute appealed
• Appeal period over (PNK win/lose amount)

Pending Actions (Stateful):

• Dispute needs vote
• Dispute needs execution

Contractors:

Notifications:

• Dispute created
• Jurors drawn
• Ruling took place
• Dispute appealed
• Appeal period over (decision)

Pending Actions (Stateful):

• Outstanding fee
• Dispute pending repartition/execution

Test event driven actions that do not have a callback

There is still a challenge of testing async actions that do not use a callback. This includes things like updating timestamps in the store.

Idea: Allow for a optional callback arg in all event handlers and only use it for the tests

stopWatchingEvents with leftover contractInstances

To reproduce:

• Start event listener on contract.
• Call stopWatchingForEvents.
• Start event listener again.

Should clear contract instance when we stop listening for events (use removeContractInstance?)

Rethink logic around stopping and starting in kleros.watchForEvents

Race condition with arbitrable contracts

An unforeseen consequence of the design choice to load and store the contract instance in the ContractImplementation class and to apply it to both arbitrable and arbitrator contracts is that we have race conditions between notifications or other background tasks and user actions.

For example: When we refresh the page while loading a contract in kleros.tech there is a race condition between notifications which is setting the arbitrable instance and the user who is trying to load a different arbitrable contract to fetch data.

bug dependency with babel

I have this issue when I use this package with create react app:

ReferenceError: regeneratorRuntime is not defined

Gracefully handle missing data in store

We currently have a disjointed strategy for handling missing data in the store. Sometimes errors are thrown, but as errors are not handled in the UI it crashes the UI. To mitigate this it can also fail silently (return an empty object) so that the UI doesn't crash.

Make event watchers more testable

Due to the async nature of events they are difficult to test in the integration test. We are just waiting some arbitrary amount of time right now but this is unreliable

Upgrade EventListener so it isn't reliant on user passing truffle-contract objects

EventListener relies on truffle-contract objects to watch event logs. This is easy for us to use but isn't particularly flexible as a util and will need to be generalized if we want to make it until a self contained tool kit.

Potential options:

• Parse Tx/Blocks directly like what is done here. We could fork this repo and extend it to fit our multi contract/ multi handler needs if this route is chosen.
• Investigate using filters with raw web3. User will need to pass contract abi.
• Create some sort of very general base contract wrapper for the EventListener that still uses truffle contract but doesn't force the user to have to know about it. (i.e. it needs to be passed a contracts/Implementations. This seem restrictive outside of our codebase however.

migrate to ganache

see http://truffleframework.com/ganache/

Use a shared queue for every action that hits the store

Use a promise queue for all action involving the store. Refactor StoreProviderWrapper so that it queues write tasks and then reads before it writes

change deploy command with yarn

"deploy": "yarn build && npm publish",=>"deploy": "yarn build && yarn publish",

Use isCallValid (estimateGas) in Kleros API

See https://github.com/kleros/kleros-bot/blob/c2737f9f06a8b1137e70babe0f14ebfd90b484a5/src/helpers.js#L34

implement helper method to make gasEstimate calls. Add to kleros-interaction so both repos can use it?

XMLHttpRequest only available client side

XMLHttpRequest is a browser object so if api is used in server side code (nodejs) all interactions with the store fail

add test if Bob raises an appeal

Mock store interactions in tests

Using the hosted store is outside the scope of the api tests. In addition it causes concurrency problems where multiple tests are writing to the same central profile, and it slows down the tests dramatically. Create a framework to mock store and return data needed for the api tests

Add `createdAt` Throughout The API

The new front end design requires some dates that we are missing.

The first that come to mind are:

• Dispute createdAt.
• Evidence submittedAt.
• Ruling ruledAt.

We should also return all timestamps as milliseconds since epoch.

API Lets You Vote After Voting Period is Over

Even in a different session.

Meta-Mask Question

Per: https://thenextweb.com/hardfork/2018/04/03/google-bans-cryptocurrency-mining-extensions-in-the-chrome-web-store - what's the status of using Meta-Mask?

add test if a Alice and Bob create a dispute and A lice wins on https://github.com/kleros/kleros-api/blob/develop/tests/integration/contracts.test.js

Missing `appealDraws` make `canRule` always falsy in getDataForDispute

Causes kleros/kleros-juror-front#12

Make an AppealPossible Notification

The AppealPossible event is not triggered in KlerosPOC but we would still like to have a Appeal Possible (Ruling has been given) notification

Create a notification triggered by the period passing event for all disputes that are appealable in the current session.

No Code at Address - Error when contract exists

Sometimes when instantiating the the KlerosPOC contract it throws the error UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: Cannot create instance of KlerosPOC; no code at address <contract address> even though the contract exists.

My hypothesis is it has to do with network congested. In any case need to make API more failure tolerant and either retry a certain number of times wait longer for a response.

Note: mostly seen when connecting to ETH network via infura

Related to #42

add reimburse fn

PartyB calls this function if he decides to reimburse partyA.

lockedTokens change after activating tokens

activatedTokens = 0, lockedTokens = 0

• Activate 1 token

activatedTokens = 1, lockedTokens = 1e-18

passPeriod estimateGas is failing

We use estimateGas to ensure that a transaction will not be rejected before we send them. passPeriod fails while running the tests with estimateGas

show the timestamp lastInteraction

we need this lastInteraction to compute if a party can call the timeout

Add Missing Properties to Returned Disputes

The new front end requires these 3 properties on dispute objects:

• votesForPartyA
• votesForPartyB
• netPNK - The PNK the juror received or lost (negative).

add status payment done

use https://github.com/kleros/kleros-api/blob/0c05b40e08b72bac4cec61dfd4c83e96c0078182/constants.js

publish esdoc documentation on GH pages

see https://github.com/kleros/kleros-api#docs

add the missing function pay()

Pay the party B. To be called when the good is delivered or the service rendered.

DRY out setup of integration tests and break them into smaller tests

At the moment the integration tests all use the same setup (creating contracts, staking tokens, raising a dispute etc.). The dispute resolution flow integration test is also way too long. DRY out the setup and then break the tests into as many files as possible so that smaller parts can be tested individually.

DRY out fetching active disputes and make process more efficient

Throughout the codebase and in many event handlers we are iterating over all of the disputes to find the active disputes. Create one function that does this work for us. Also make it more efficient by searching through events to find appeals or new disputes that have been raised in the last session

Return all token amounts in the same unit

All calls returning token amounts should be normalized to their standard unit
i.e.
WEI -> ETH
WEI(?) -> PNK

Create a queue for failed http requests

We have to be able to recover store updates that fail. Create a failure queue and retry when appropriate so that we do not lose data