Cleanups

Added: README.md, dependencies

Future Analysis.md

@@ -0,0 +1,100 @@
+# JUR Analysis
+
+## Closed Hubs
+
+A closed hub represents a group of JUR token holders who have a specific set of skills related to arbitration in common.
+
+This group of JUR token holders deposit their tokens into a `ClosedHub` contract, and voting that utilises this closed hub are routed through the `ClosedHub` contract.
+
+In addition to a `ClosedHub` contract instance for each closed hub group, there is a central `ClosedHubRepository` contract which records the list of all closed hub groups.
+
+The `ClosedHubRepository` contract would have a data structure similar to the below (there is a single `ClosedHubRepository` instance):  
+```
+//Mapping from closed hub name to closed hub contract address
+mapping (bytes32 => address) closedHubs;
+```
+
+Each `ClosedHub` contract instance would have a data structure similar to:  
+```
+//List of members in this closedHub
+mapping (address => bool) closedHubMembers;
+//Minimum escrow value an arbitration must have to use this closed hub
+uint256 public minimumEscrow;
+//Maximum escrow value an arbitration must have to use this closed hub
+uint256 public maximumEscrow;
+//Balances of JUR tokens staked to the contract by each member
+mapping (address => uint256) balances;
+```
+and an API similar to:  
+```
+//Transfer (stake) tokens to the closed hub
+function stakeTokens(uint256 _amount)
+//Member votes through the closed hub, specifying the arbitration on which they are voting, and the party and amount of tokens they wish to vote with
+function vote(address _arbitration, address _voteAddress, uint256 _voteAmount)
+```
+
+If a party wishes to, when setting up a new `Arbitration` contract, they can specify that they will only allow voting to originate from one or more closed hubs (as opposed to all JUR token holders). The `ArbitrationFactory` contract which is responsible for creating this new `Arbitration` contract would enforce that the arbitration fulfils the criteria to use a given closed hub (minimum / maximum escrowed amounts).
+
+Each `ClosedHub` group can implement bespoke logic to restrict membership and the amount of tokens staked (and therefore eligable to be voted with) by each individual member.
+
+For example, some closed hubs may have a single admin account, which is responsible for approving (or unapproving) each individual member. Alternatively it may be that, after the closed hub is first set up with a fixed list of members, new members are added via a voting process of existing members. The required quorum percentage and voting percentages would be specified by each individual closed hub (e.g. at least 30% of members must vote and of voting members, at least 70% must agree, in order for the vote to be valid).
+
+The `ClosedHub` contracts can also enforce limits on the amount of tokens that can be staked to the contract by each individual member. For example, it could enforce that no single member has more than 25% of the total JUR tokens staked to the contract. These rules could be enforced continuously as members stake (or withdraw) tokens from the closed hub.
+
+Members can, at any time, withdraw their staked JUR tokens from a closed hub in which they are a member.
+
+Within an `Arbitration` contract, if it is initialised with a closed hub (or hubs) requirement, then the `Arbitration` contract would enforce that all voting happens through the specified closed hubs.
+
+Within a closed hub group, it is possible for different members to vote differently on a given arbitration.
+
+## Solving Scalability
+
+Ethereum is the most mature blockchain that supports smart contract. However there are well-established scalability issues, with Ethereum currently supporting around 15 transactions per second (tps) meaning that when there is a high demand for network utilisation, viable gas prices often rise (as seen during the CryptoKitties launch). High gas prices can make the cost of transacting online (e.g. voting on arbitrations, or creating new arbitrations) prohibitively expensive.
+
+Whilst there is a roadmap to improve scalability in Ethereum including layer 1 and layer 2 solutions (specifically Casper / proof-of-stake, sharding, plasma) it is worth considering what the possible alternatives are.
+
+### Ethereum
+
+It is possible to reduce on-chain transactions either via a “side-chain” using something like the Loom networks approach whereby most transactions occur off-chain in a proof of authority side-chain, with the main chain being used to secure the side-chain at well-defined checkpoints or by using state channels (e.g. Raiden) to facilitate peer-to-peer micro-payments. Both of these have advantages in terms of reducing on-chain transactions, but come with a cost of additional complexity. Both approaches are also relatively novel and have not yet been used in large scale production applications.
+
+### EOS
+
+EOS’s mainnet is due to launch imminently. EOS promises high rates of tps and a different approach to accounting for transaction costs (aka gas fees in Ethereum). Gas mechanics differ to Ethereum and Cardano where ETH or ADA is used to pay directly for transaction costs, and instead, by holding EOS tokens you are entitled to use a proportional amount of network bandwidth. Scaling is solved through dPoS, a more efficient, but less decentralised approach to consensus. Fast finalisation and low costs of transactions may make EOS an attractive option for dApps which rely on incentivising users to make on-chain transactions (such as voting in the JUR system).
+
+### Cardano
+
+Cardano focuses on a research driven approach, solving scalability through splitting settlement from computation and putting an emphasis on interoperability between blockchains. Their is a mainnet currently launched based on centralised block production, with a release scheduled to introduce the Ouroboros consensus algorithm (proof of stake) which would decentralise network security with the deployment of the computation layer scheduled after this. Migrating to Cardano has the benefit that Smart Contracts written in Solidity should be deployable to Cardano (which is also developing its own native language) and the emphasis on blockchain interoperability may facilitate a smoother switch from Ethereum via atomic token swaps or similar mechanisms.
+
+### Summary
+
+Today, Ethereum is the clear choice for any dApp MVP. It has mature tooling, an active development community and a large base of potential users. Desktop wallet options such as MetaMask and mobile options such as Cipher, Trust & Status-IM give users relatively easy UX’s to interact with dApps. Once it becomes necessary to truly scale however it may well be that other blockchains offer better features at a lower cost, with very similar benefits with respect to decentralisation and transfer of value.
+
+## Smart Contract Architecture
+
+This is largely already covered in the smart contract specification. There would be 3 contracts:  
+
+  - JUR Token  
+  - Arbitration Factory  
+  - Arbitration [of which there will be multiple instances, one per arbitration]  
+
+Closed Hubs could either be built into the Arbitration Factory, or put into a separate contract as per above.
+
+To support web2 integrations, it may be necessary to have a new type of Arbitration contract with the escrow part removed, or otherwise potentially use the same contract, just setting the escrowed values to 0 (which would still support dispute resolution).
+
+## Uploading Proofs
+
+As discussed, I can’t see any reason to store any evidence associated with a dispute on-chain. We should be storing a hash of the original agreement between the two parties so that if a dispute arises both parties can independently and unilaterally prove the contents of the original agreement. If the agreement is bilaterally amended, then the updated agreement hash is also stored.
+
+Documents that form part of the dispute process are in any way subject to being contested, so there is no obvious advantage of storing those on-chain other than potentially for reporting purposes, but this could be managed off-chain.
+
+## Roadmap
+
+Items that should be on the roadmap post-ICO:
+
+  - develop closed hub contracts providing the ability for closed hub owners / members to customise their hubs appropriately.
+
+  - develop arbitration only (no escrow) arbitration contracts for integration with web2.0 clients.
+
+  - allow escrow in non-JUR tokens (ETH & other ERC20 tokens, e.g. DAI)
+
+  - continually monitor and improve arbitration parameters (time periods, minimum voting amounts) and modify if needed based on real life usage

README.md

@@ -1,2 +1,207 @@
-# mvp-smart-contract
-This repo will contain the main smart contract for the Jur MVP.
+# JUR Protocol
+
+## Specification
+
+See [JUR Protocol Specification]('JUR Protocol Specification.md')
+
+## Dependencies
+
+1. This repo uses truffle, node and npm:  
+https://nodejs.org/en/ (v8.4.0)  
+http://truffle.readthedocs.io/en/beta/getting_started/installation/
+https://github.com/trufflesuite/ganache-cli
+
+1. Run `npm install` in the repo root directory.
+
+## Compilation
+
+To compile the contracts to bytecode, you can execute:  
+`truffle compile`
+
+This will display some warnings due to OpenZeppelin library files which can be ignored.
+
+## Running Test Network
+
+To run a test ethereum network, in a separate terminal execute:  
+`ganache-cli`
+
+## Deployment
+
+The deployment is configured in `migrations/2_deploy_contracts.js`.
+
+Settings in the migrations file and `truffle.js` should also be reviewed / modified before mainnet release.
+
+To deploy, you can execute:  
+`truffle migrate --reset`
+
+which should output something similar to:
+```
+Using network 'development'.
+
+Running migration: 2_deploy_contracts.js
+  Deploying JURToken...
+  ... 0xff2c945eb1e2ca59de9e7b18a516fd3d130dd1b837152d9f5e5d84dae32fca43
+  JURToken: 0x2ef6dc25b5dd451221fca2f1d87048d6f0cb0cd3
+  Deploying ArbitrationFactory...
+  ... 0x12cbb2cf8864cce9c6b358722b823fd5f699aee3bce5371ffea194f9aae9f905
+  ArbitrationFactory: 0x159247d9d7571bcb174c78e9d619b0dbbafd7b50
+Saving successful migration to network...
+  ... 0x155f86784aaa062932832859c04cf475605d732bbde235f7749472d28d0f8db5
+Saving artifacts...
+```
+
+## Testing
+
+Comprehensive test cases have been added for all contracts.
+
+To test, you can execute:  
+`truffle test`
+
+which should output:
+```
+Using network 'development'.
+
+  Contract: Arbitration - no dispute
+JUR Token Address:  0x1f37801d4db18b6a4cb6a65eced53ccb63ab764e
+Arbitration Factory Address:  0xe254a552ddf1d3cd5db6a1a69a8d7626402e4271
+    ✓ 0. initialize token contract and arbitration factory contract (537ms)
+Arbitration Address: 0x3804475d74a3b5261b34d3c8f31af30055058466
+    ✓ 1. create new arbitration - state is unsigned (304ms)
+    ✓ 2. approve arbitration for transfers (147ms)
+    ✓ 3. only parties can sign arbitration (114ms)
+    ✓ 4. party1 signs arbitration (134ms)
+    ✓ 5. party1 unsigns arbitration (60ms)
+    ✓ 6. party1 resigns arbitration (115ms)
+    ✓ 7. party2 signs arbitration - state is now Signed (116ms)
+    ✓ 8. only parties can agree arbitration
+    ✓ 9. party2 agrees arbitration (86ms)
+    ✓ 10. party1 agrees arbitration - state is now Agreed (83ms)
+    ✓ 11. only parties can withdraw dispersals
+    ✓ 12. party1 withdraws dispersal (zero tokens) (111ms)
+    ✓ 13. party2 withdraws dispersal (150 tokens) - state is now Closed (130ms)
+
+  Contract: Arbitration - Amendment with no dispute
+JUR Token Address:  0x1f37801d4db18b6a4cb6a65eced53ccb63ab764e
+Arbitration Factory Address:  0xe254a552ddf1d3cd5db6a1a69a8d7626402e4271
+    ✓ 0. initialize token contract and arbitration factory contract (399ms)
+Arbitration Address: 0x3804475d74a3b5261b34d3c8f31af30055058466
+    ✓ 1. create new arbitration - state is unsigned (352ms)
+    ✓ 2. approve arbitration for transfers (133ms)
+    ✓ 3. only parties can sign arbitration (124ms)
+    ✓ 4. party1 signs arbitration (87ms)
+    ✓ 5. party1 unsigns arbitration (72ms)
+    ✓ 6. party1 resigns arbitration (174ms)
+    ✓ 7. party2 signs arbitration - state is now Signed (156ms)
+    ✓ 8. party2 proposes amendment (130ms)
+    ✓ 9. party1 agrees amendment (271ms)
+    ✓ 10. party1 proposes amendment without authorising additional funding - fail (78ms)
+    ✓ 11. party1 proposes amendment with authorised additional amendedFunding (247ms)
+    ✓ 12. party2 agrees amendment (246ms)
+    ✓ 13. party1 proposes amendment (257ms)
+    ✓ 14. party1 unagrees amendment (137ms)
+    ✓ 15. party1 agrees arbitration (99ms)
+    ✓ 16. party2 agrees arbitration - state is now Agreed (88ms)
+    ✓ 17. party1 withdraws dispersal (zero tokens) (112ms)
+    ✓ 18. party2 withdraws dispersal (180 tokens) - state is now Closed (165ms)
+
+  Contract: Arbitration - Tied dispute
+JUR Token Address:  0x1f37801d4db18b6a4cb6a65eced53ccb63ab764e
+Arbitration Factory Address:  0x738f23b326d12610a6374de0a12e3f5ce6b9eeca
+    ✓ 0. initialize token contract and arbitration factory contract (545ms)
+Arbitration Address: 0x4cd198d5d2c81a00fe1960fd6b8137fc39e7613a
+    ✓ 1. create new arbitration - state is unsigned (296ms)
+    ✓ 2. approve arbitration for transfers (260ms)
+    ✓ 3. only parties can sign arbitration
+    ✓ 4. party1 signs arbitration (91ms)
+    ✓ 5. party2 signs arbitration - state is now Signed (117ms)
+    ✓ 6. party1 disputes arbitration with sufficient vote (338ms)
+    ✓ 7. party2 sets their dispute dispersal (226ms)
+    ✓ 8. unable to change dispute dispersal after DISPUTE_DISPERSAL_DURATION (112ms)
+    ✓ 9. start voting resulting in a tie (405ms)
+    ✓ 10. vote is extended due to a tie (113ms)
+    ✓ 11. additional votes placed (under 5%) (226ms)
+    ✓ 12. dispute ends, no more voting possible (119ms)
+    ✓ 12. voters receive rewards (508ms)
+    ✓ 14. parties receive payouts (572ms)
+
+  Contract: Arbitration - Tied dispute
+JUR Token Address:  0x1f37801d4db18b6a4cb6a65eced53ccb63ab764e
+Arbitration Factory Address:  0x738f23b326d12610a6374de0a12e3f5ce6b9eeca
+    ✓ 0. initialize token contract and arbitration factory contract (519ms)
+Arbitration Address: 0x4cd198d5d2c81a00fe1960fd6b8137fc39e7613a
+    ✓ 1. create new arbitration - state is unsigned (268ms)
+    ✓ 2. approve arbitration for transfers (257ms)
+    ✓ 3. only parties can sign arbitration (47ms)
+    ✓ 4. party1 signs arbitration (101ms)
+    ✓ 5. party2 signs arbitration - state is now Signed (121ms)
+    ✓ 6. party1 disputes arbitration with sufficient vote (464ms)
+    ✓ 7. party2 sets their dispute dispersal (219ms)
+    ✓ 8. unable to change dispute dispersal after DISPUTE_DISPERSAL_DURATION (105ms)
+    ✓ 9. start voting (440ms)
+    ✓ 10. vote is extended due to lots of votes during last 30 minutes (402ms)
+    ✓ 11. unable to payout voters due to extended window (59ms)
+    ✓ 12. able to vote during extended window (223ms)
+    ✓ 13. voters receive rewards (693ms)
+    ✓ 14. parties receive payouts (600ms)
+
+  Contract: Arbitration - Approve and call
+JUR Token Address:  0x1f37801d4db18b6a4cb6a65eced53ccb63ab764e
+Arbitration Factory Address:  0x738f23b326d12610a6374de0a12e3f5ce6b9eeca
+    ✓ 0. initialize token contract and arbitration factory contract (739ms)
+Arbitration Address: 0x4cd198d5d2c81a00fe1960fd6b8137fc39e7613a
+    ✓ 1. create new arbitration - state is unsigned (266ms)
+    ✓ 2. only parties can sign arbitration (85ms)
+    ✓ 3. must send first argument as your own address (60ms)
+    ✓ 4. party1 signs arbitration (129ms)
+    ✓ 5. party2 signs arbitration - state is now Signed (145ms)
+    ✓ 6. party1 disputes arbitration with sufficient vote (397ms)
+    ✓ 7. party2 sets their dispute dispersal (202ms)
+    ✓ 8. unable to change dispute dispersal after DISPUTE_DISPERSAL_DURATION (94ms)
+    ✓ 9. start voting (589ms)
+    ✓ 10. unable to vote if ratio between new winner and second best is more than 2 (58ms)
+    ✓ 11. dispute ends, no more voting possible (125ms)
+    ✓ 12. voters receive rewards (502ms)
+    ✓ 13. parties receive payouts (526ms)
+
+  Contract: Arbitration - Reject dispute
+JUR Token Address:  0x1f37801d4db18b6a4cb6a65eced53ccb63ab764e
+Arbitration Factory Address:  0x738f23b326d12610a6374de0a12e3f5ce6b9eeca
+    ✓ 0. initialize token contract and arbitration factory contract (524ms)
+Arbitration Address: 0x4cd198d5d2c81a00fe1960fd6b8137fc39e7613a
+    ✓ 1. create new arbitration - state is unsigned (257ms)
+    ✓ 2. approve arbitration for transfers (300ms)
+    ✓ 3. only parties can sign arbitration (47ms)
+    ✓ 4. party1 signs arbitration (208ms)
+    ✓ 5. party2 signs arbitration - state is now Signed (138ms)
+    ✓ 6. party1 disputes arbitration with sufficient vote (367ms)
+    ✓ 7. party2 sets their dispute dispersal (213ms)
+    ✓ 8. unable to change dispute dispersal after DISPUTE_DISPERSAL_DURATION (114ms)
+    ✓ 9. start voting - reject option wins (471ms)
+    ✓ 10. unable to vote if ratio between new winner and second best is more than 2 (76ms)
+    ✓ 11. dispute ends, no more voting possible (117ms)
+    ✓ 12. voters receive rewards (499ms)
+    ✓ 13. parties receive payouts (493ms)
+
+  Contract: Arbitration - Simple dispute
+JUR Token Address:  0x1f37801d4db18b6a4cb6a65eced53ccb63ab764e
+Arbitration Factory Address:  0x738f23b326d12610a6374de0a12e3f5ce6b9eeca
+    ✓ 0. initialize token contract and arbitration factory contract (631ms)
+Arbitration Address: 0x4cd198d5d2c81a00fe1960fd6b8137fc39e7613a
+    ✓ 1. create new arbitration - state is unsigned (314ms)
+    ✓ 2. approve arbitration for transfers (309ms)
+    ✓ 3. only parties can sign arbitration (65ms)
+    ✓ 4. party1 signs arbitration (124ms)
+    ✓ 5. party2 signs arbitration - state is now Signed (141ms)
+    ✓ 6. party1 disputes arbitration with insufficient vote - fail (208ms)
+    ✓ 7. party1 disputes arbitration with sufficient vote (352ms)
+    ✓ 8. party2 sets their dispute dispersal (238ms)
+    ✓ 9. unable to change dispute dispersal after DISPUTE_DISPERSAL_DURATION (221ms)
+    ✓ 10. start voting (788ms)
+    ✓ 11. unable to vote if ratio between new winner and second best is more than 2 (127ms)
+    ✓ 12. dispute ends, no more voting possible (152ms)
+    ✓ 13. voters receive rewards (570ms)
+    ✓ 14. parties receive payouts (605ms)
+
+
+  106 passing (28s)
+```