Update README with instructions for getting started.

README.md

@@ -1,41 +1,76 @@
 # Core prototype
-Code repository for Boson Protocol smart contracts. The description of the contracts and process can be found in [doc_contracts.md](doc_contracts.md).    
 
-## Install
-Install dependencies from project root folder:
-```
-    $ npm install @openzeppelin/contracts truffle-assertions ethers
-```
+Code repository for Boson Protocol smart contracts. The description of the 
+contracts and process can be found in [doc_contracts.md](doc_contracts.md).    
 
-Migrations are using HDWalletProvider, install it if you need it:
-```
-    $ npm install @truffle/hdwallet-provider
+## Getting started
+
+Note: all commands below are run from the project root.
+
+To install dependencies:
+
+```shell script
+npm install
+````
+
+To compile all contracts:
+
+```shell script
+npm run compile
 ```
 
-## Contracts initialization 
-[Migrations script](./migrations/2_deploy_contracts.js) for Truffle also does this initialization:
+To run the unit tests:
+
+1. Ensure Ethereum is running locally on port 8545. This can be achieved using
+   Ganache, `ganache-cli` or `etherlime ganache`.
+1. Copy your 12 word mnemonic to `.secret`. Create the file if it doesn't 
+   already exist.
+1. Execute the unit tests:
+
+```shell script
+npm run test:unit
+``` 
+
+Note: currently, the unit test suite will fail the second time it is run against
+the same Ethereum instance. As a reuls, you'll need to reset between test runs.
+
+To run the integration tests, follow the instructions in 
+[`testUserInteractions/README.md](testUserInteractions/README.md).
+
+## Contracts initialization
+ 
+[Migrations script](./migrations/2_deploy_contracts.js) for Truffle also does 
+this initialization:
+
 - ERC1155ERC721.setApprovalForAll(contractVoucherKernel.address, 'true')
 - ERC1155ERC721.setVoucherKernelAddress(contractVoucherKernel.address)
 - VoucherKernel.setCashierAddress(contractCashier.address)
 
 ## Deployed contracts
-Contract are deployed on Kovan testnet at addresses:  
+
+Contracts are deployed on Kovan testnet at addresses:
+  
 ERC1155ERC721: 0xF3aA8eB3812303F6c86c136557bC23E48d634B58  
 VoucherKernel: 0x1806312211bd1521430C953683038d6263580feE  
 Cashier: 0xaaf749c8e6e37b51410F1810ADcAEED18d0C166F   
+
 The frontend is currently pointing to Kovan deployment.  
 
-Contract are also deployed on Ropsten testnet at addresses:  
+Contract are also deployed on Ropsten testnet at addresses:
+  
 ERC1155ERC721: 0xe7028d66222aD1AfEB0098956347A6284443bd16  
 VoucherKernel: 0xa93f95bf0039CE30957b77A6638e2e273598D576  
 Cashier: 0x014b8baF57bA77FaE23075aa93c2B768eeb440bD  
 
 ## Progress
-See the project board at [https://github.com/bosonprotocol/bsn-core-prototype/projects/2](https://github.com/bosonprotocol/bsn-core-prototype/projects/2).
 
+See the  
+[project board](https://github.com/bosonprotocol/bsn-core-prototype/projects/2).
 
 ## Coverage
+
 Test coverage is executed by running the following command: 
 
 ``` 
-npm run coverage
+npm run coverage
+```

doc_contracts.md

@@ -1,5 +1,9 @@
 # Smart contracts description
-This is a brief description of the smart contracts used in Boson Protocol. They are based on two NFT standards, [ERC-1155](https://eips.ethereum.org/EIPS/eip-1155) and [ERC-721](https://eips.ethereum.org/EIPS/eip-721).  
+
+This is a brief description of the smart contracts used in Boson Protocol. They 
+are based on two NFT standards, 
+[ERC-1155](https://eips.ethereum.org/EIPS/eip-1155) and 
+[ERC-721](https://eips.ethereum.org/EIPS/eip-721).  
 
 Main contracts:  
 * BosonToken: ERC-20 contract for the native Boson Protocol token  
@@ -8,33 +12,49 @@ Main contracts:
 * VoucherKernel: main business logic  
 * usingHelpers: common utils as structures  
 
-Supported currencies are currently ETH and BSN tokens therefore functions dealing with funds have appendices such as ETH_ETH or ETH_TKN to denote the currencies used in that particular function (e.g. `function requestCreateOrder_ETH_ETH(uint256[] calldata metadata)`).  
-
+Supported currencies are currently ETH and BSN tokens therefore functions 
+dealing with funds have appendices such as ETH_ETH or ETH_TKN to denote the 
+currencies used in that particular function (e.g. 
+`function requestCreateOrder_ETH_ETH(uint256[] calldata metadata)`).  
 
 ## Transactions flow
-The journey through the NFT lifecycle is presented on a simplified diagram below.  
+
+The journey through the NFT lifecycle is presented on a simplified diagram 
+below.  
 
 ![Simplified exchange mechanism](assets/boson_exchange_diagram_simplified.png)  
 
+Voucher's status is defined in 7 bits that are set depending on the path in its 
+lifecycle (defined in 
+[usingHelpers.sol](https://github.com/bosonprotocol/bsn-core-prototype/blob/master/contracts/usingHelpers.sol#L29)):  
 
-Voucher's status is defined in 7 bits that are set depending on the path in its lifecycle (defined in [usingHelpers.sol](https://github.com/bosonprotocol/bsn-core-prototype/blob/master/contracts/usingHelpers.sol#L29)):  
 7:COMMITTED  
-6:REDEEMED
  
+6:REDEEMED  
 5:REFUNDED   
-4:EXPIRED 
  
-3:COMPLAINED
  
-2:CANCELORFAULT
  
+4:EXPIRED  
+3:COMPLAINED  
+2:CANCELORFAULT  
 1:FINAL  
 
-
 ### Happy path
-The process starts with Seller making an offer - minting a VoucherSet, which is represented as ERC-1155 token: `Cashier.requestCreateOrder()`. The Seller sets the expiration period of the whole VoucherSet.  
 
-Then the Buyer purchases the Voucher, i.e. is committing to redeem it at some point later - this means an ERC-721 token is extracted from a VoucherSet: `Cashier.requestVoucher()`.  
+The process starts with Seller making an offer - minting a VoucherSet, which is 
+represented as ERC-1155 token: `Cashier.requestCreateOrder()`. The Seller sets 
+the expiration period of the whole VoucherSet.  
 
-The Buyer redeems the voucher, thus releasing the payment amount to the Seller: `VoucherKernel.redeem()`.  
+Then the Buyer purchases the Voucher, i.e. is committing to redeem it at some 
+point later - this means an ERC-721 token is extracted from a VoucherSet: 
+`Cashier.requestVoucher()`.  
 
-After the two wait periods pass (the period within which Buyer can complain and the period within which Seller can admit cancel/fault), the Seller's deposit can be returned to the Seller and Buyer's deposit can be returned to the Buyer.  
+The Buyer redeems the voucher, thus releasing the payment amount to the Seller: 
+`VoucherKernel.redeem()`.  
 
-A scheduled process is running in the backend that flags the vouchers when redemption was made and when wait periods expire. Anybody could be executing these functions, marked as external, the backend is currently running them for convenience: `VoucherKernel.triggerExpiration()`, `VoucherKernel.triggerFinalizeVoucher()`, `Cashier.withdraw()`.  
+After the two wait periods pass (the period within which Buyer can complain and 
+the period within which Seller can admit cancel/fault), the Seller's deposit 
+can be returned to the Seller and Buyer's deposit can be returned to the Buyer.  
 
+A scheduled process is running in the backend that flags the vouchers when 
+redemption was made and when wait periods expire. Anybody could be executing 
+these functions, marked as external, the backend is currently running them for 
+convenience: `VoucherKernel.triggerExpiration()`, 
+`VoucherKernel.triggerFinalizeVoucher()`, `Cashier.withdraw()`.