Merge pull request #86 from 1Hive/update-readme

Update README

README.md

@@ -2,7 +2,9 @@
 
 _**Original code:**_ [aragon-apps/apps/payroll](https://github.com/aragon/aragon-apps/tree/master/future-apps/payroll)
 
-The purpose of the Payroll app is to implement a Payroll system ~~in multiple currencies~~.
+<a href="https://installer.1hive.org"><img src="docs/assets/screenshot.png" /></a>
+
+The purpose of the Payroll app is to implement a Payroll system in base asset, equity asset or a mix of both.
 
 #### 🐲 Project Stage: development
 
@@ -14,11 +16,11 @@ The code in this repository has not been audited.
 
 ## How to run Payroll app locally
 
-To use this Aragon application, set it up using a token and a vault using:
+To use this Aragon application, set it up using a tokens and finance app using:
 
 ```sh
-npm install
-npm start # It actually starts `npm run start:ipfs:template`
+yarn install
+yarn start
 ```
 
 If everything is working correctly, your new DAO will be deployed and your browser will open http://localhost:3000/#/YOUR-DAO-ADDRESS.
@@ -27,72 +29,62 @@ If everything is working correctly, your new DAO will be deployed and your brows
 
 Initializing a Payroll app requires the following parameters:
 
-- **Finance**: a reference to [Finance](https://github.com/aragon/aragon-apps/tree/master/apps/finance) instance that Payroll app will use to pay salaries. Finance in turn will use [Vault](https://github.com/aragon/aragon-apps/tree/master/apps/vault) to access funds, but going through Finance will have everything properly accounted for.
-- **Ether Token**: EtherToken instance used as ether.
-- **Denomination Token**: token used to denominate salaries. All exchange rates for other tokens will be paired with it.
+- **Finance**: A reference to [Finance](https://github.com/aragon/aragon-apps/tree/master/apps/finance) instance that Payroll app will use to pay salaries. Finance in turn will use [Vault](https://github.com/aragon/aragon-apps/tree/master/apps/vault) to access funds, but going through Finance will have everything properly accounted for.
+- **Denomination token**: Address of the denomination token used for salary accounting
+- **Equity token manager**: A reference to the installed [Tokens app](https://github.com/aragon/aragon-apps/tree/master/apps/token-manager) instance this Payroll app will rely on for equity payments.
+- **Vesting length**: The length of vestings in seconds, the time when vestings can be completely claimed. Set to 0 to disable vestings
+- **Vesting cliff length**: The vesting cliff in seconds, the time until which vestings cannot be claimed
+- **Vesting revokable**: Whether vestings can be revoked
 
-### Lifecycle
+Employees will be able to choose payment in denomination token, equity token or a mix of both. Equity payments are a multiple of the base currency amount which is defined by the equity multiplier. Equity payments can also be vested by enabling vestings.
 
-#### Add allowed token
-```
-payroll.setAllowedToken(address _allowedToken, true)
-```
-Add token to the list of accepted ones for salary payment. It needs `MANAGE_ALLOWED_TOKENS_ROLE`.
+### Lifecycle
 
-#### Set exchange rate
-```
-payroll.setExchangeRate(address token, uint256 denominationExchangeRate)
-```
-Set the exchange rate for an allowed token against the Payroll denomination token. It needs `ORACLE_ROLE`.
 
 #### Add employee
 Three options can be used:
 ```
-payroll.addEmployee(address accountAddress, uint256 initialYearlyDenominationSalary, string role, uint256 startDate)
+payroll.addEmployee(address _accountAddress, uint256 _initialDenominationSalary,  uint64 _startDate, string _role)
 ```
-Add employee to the organization. Start date is used as the initial payment day. If it's not provided, the date of the transaction will be used. It needs `ADD_EMPLOYEE_ROLE`.
+Add employee to the organization. Start date is used as the initial payment day. It needs `ADD_EMPLOYEE_ROLE`.
 
 #### Modify employee salary
 ```
-payroll.setEmployeeSalary(uint128 employeeId, uint256 yearlyDenominationSalary)
+payroll.setEmployeeSalary(uint256 _employeeId, uint256 _denominationSalary)
 ```
-It needs `ADD_EMPLOYEE_ROLE`.
+It needs `SET_EMPLOYEE_SALARY_ROLE`.
 
-#### Remove employee
+#### Terminate employee
 ```
-payroll.removeEmployee(uint128 employeeId)
+payroll.terminateEmployee(uint256 _employeeId, uint64 _endDate)
 ```
-Remove employee from organization. The owed up to current date salary will be transferred to the employee. It needs `REMOVE_EMPLOYEE_ROLE`.
 
-#### Determine allocation
-```
-payroll.determineAllocation(address[] tokens, uint8[] distribution)
-```
-Employees can set the proportion of every allowed token that want to be used for their salary payment. Distribution values are expressed as a ratio to 100.
+Remove employee from organization. Owed salary will accrue until termination date. It needs `TERMINATE_EMPLOYEE_ROLE`.
 
 #### Request payroll
 ```
-payroll.payday()
+payroll.payday(uint256 _denominationTokenAllocation, int256 _requestedAmount, string _metaData)
 ```
 Employees can request payroll whenever they want and the proportional amount of their anual salary since the last request (or since the start date if it's the first one) will be transferred.
+Employees can choose to receive payment in base asset (denomination token), equity asset, or a mix of both. `_denominationTokenAllocation` determines the % of base asset payment from the total owed and the remaining will be paid in equity asset. The equity token payment is relative to the base asset payment and is defined by the equity multiplier. E.g If an employee has a salary of 1000 DAI and the multiplier is 4x then they can mint up to 4000 of the equity asset per period.
 
 #### Change account address
 ```
-payroll.changeAddressByEmployee(address newAddress)
+payroll.changeAddressByEmployee(address _newAccountAddress)
 ```
 Employees can change their own address.
 
-### Limitations
+### Caveats
+
+- Requesting any salary under the total available will forfeit the remainder.
+- If there are not enough funds in the orgs vault for the denomination token, `payday` will fail.
+- For equity payments with vestings: If the tokens app holds less tokens than requested equity amount, `payday` will fail.
 
-- Allowed tokens can not be removed right now. It wouldn't be trivial, as employees should be notified and they should modifiy their allocation.
-- If an employee requests payroll having allocated an allowed token which doesn't have an exchange rate, the transaction will fail. In other words, exchange rates must be set before employees try to use those tokens for their payrolls.
-- Exchange rate is not updated automatically. So it could happen that rates are outated when payrolls are requested. An external mechanism for updating rates often should be implemented.
-- If there are not enough funds for a given token, `payday` will fail. There's no automatic token conversion yet.
 
 ## Contributing
 
 We welcome community contributions!
 
-Please check out our [open Issues](https://github.com/1Hive/conviction-voting-app/issues) to get started.
+Please check out our [open Issues](https://github.com/1Hive/payroll-app/issues) to get started.
 
-If you discover something that could potentially impact security, please notify us immediately. The quickest way to reach us is via the #conviction-voting channel in our [team Keybase chat](https://1hive.org/contribute/keybase). Just say hi and that you discovered a potential security vulnerability and we'll DM you to discuss details.
+If you discover something that could potentially impact security, please notify us immediately. The quickest way to reach us is via the #payroll channel in our [team Keybase chat](https://1hive.org/contribute/keybase). Just say hi and that you discovered a potential security vulnerability and we'll DM you to discuss details.