/ README.md
README.md
1 # StandardBounties 2 [](https://gitter.im/bounties-network/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) 3 [ ](https://app.codeship.com/projects/257018) 4 5 `Version 1.1.0` 6 7 1. [Rationale](#1-rationale) 8 2. [Implementation](#2-implementation) 9 3. [Development](#3-development) 10 4. [Documentation](#4-documentation) 11 12 A set of standard contracts to be used as interfaces for any kind of bounty, either qualitative or quantitative in nature. 13 14 ## 1. Rationale 15 16 Ethereum smart contracts can trivially facilitate transactions of resources (or tokens) between individuals or groups, but service transactions are more complex. Requesting individuals (issuers) must first approve the work they're receiving before paying out funds, meaning bounty hunters must have trust that the issuer will pay them in the spirit of the original contract. 17 18 The _StandardBounties.sol_ contract facilitates transactions on qualitative data (often representing artifacts of completion of some service), allowing bounty issuers to systematically approve the work they receive. 19 20 21 ## 2. Implementation 22 23 A bounty can be used to pay amounts of ETH or a given token, based on the successful completion of the given task. The contract aims to reduce the necessary trust in the issuer by forcing them to deposit sufficient Ether (or tokens) to pay out the bounty at least once. 24 25 - A bounty begins by being issued, either through the `issueBounty()` function (which issues the bounty into draft stage), or `issueAndActivateBounty()`, which issues the bounty into the active stage 26 27 - In the `Draft` state, all bounty details can still be mutated. 28 29 In this state, the various functions which can be called are: 30 - `contribute()` [**ANYONE**]: contributes ETH (or tokens) to the bounty 31 - `activateBounty()` [**ONLY ISSUER**]: This will activate the bounty 32 - `killBounty()` [**ONLY ISSUER**]: This will kill the bounty 33 34 As well as several functions to alter the bounty details: 35 - `changeBountyDeadline()` [**ONLY ISSUER**] 36 - `changeBountyData()` [**ONLY ISSUER**] 37 - `changeBountyFulfillmentAmount()` [**ONLY ISSUER**] 38 - `changeBountyArbiter()` [**ONLY ISSUER**] 39 - `extendDeadline()` [**ONLY ISSUER**] 40 - `transferIssuer()` [**ONLY ISSUER**] 41 - `increasePayout()` [**ONLY ISSUER**] 42 43 - A bounty transitions to the `Active` state when the issuer calls `activateBounty()`, or if it was initially issued and activated. 44 45 This is only possible if 46 - the bounty hasn't expired (isn't past its deadline) 47 - the bounty has sufficient funds to pay out each milestone at least once 48 49 Once a bounty is `Active`, bounty hunters can submit fulfillments for the various milestones, and the bounty issuer can approve fulfillments to pay out the rewards. 50 51 In this state, the various functions which can be called are: 52 - `fulfillBounty()` [**ANYONE BUT ISSUER OR ARBITER**]: 53 - `updateFulfillment()` [**ONLY FULFILLER**] 54 - `acceptFulfillment()` [**ONLY ISSUER OR ARBITER**]: 55 - `increasePayout()` [**ONLY ISSUER**]: 56 - `transferIssuer()` [**ONLY ISSUER**] 57 - `extendDeadline()` [**ONLY ISSUER**] 58 - `killBounty()` [**ONLY ISSUER**]: 59 60 - A bounty transitions to the `Dead` state when the issuer calls `killBounty()`, which drains the bounty of its remaining balance. 61 62 In this state, the only functions which can be called are: 63 - `extendDeadline()` [**ONLY ISSUER**] 64 - `contribute()` [**ANYONE**] 65 - `activateBounty()` [**ONLY ISSUER**] 66 67 68 ## 3. Development 69 70 Any application can take advantage of the bounties network registry, which is currently deployed on the Main Ethereum Network at `0x2af47a65da8cd66729b4209c22017d6a5c2d2400`, and on the Rinkeby network at `0xf209d2b723b6417cbf04c07e733bee776105a073`. The `BountiesNetwork.eth` name will also always resolve to the most up-to-date registry version for the StandardBounties contract. 71 72 #### Data Schema 73 74 StandardBounties employs an off-chain storage data model, where the `data` field of each bounty and fulfillment, is a hash of a JSON object, which is stored in a distributed manner on IPFS. 75 The schema for the bounty data field is: 76 ``` 77 { 78 title: // A string representing the title of the bounty 79 description: // A string representing the description of the bounty, including all requirements 80 sourceFileName: // A string representing the name of the file 81 sourceFileHash: // The IPFS hash of the file associated with the bounty 82 contact: // A string representing the preferred contact method of the issuer of the bounty 83 categories: // an array of strings, representing the categories of tasks which are being requested 84 githubLink: // The link to the relevant repository 85 } 86 ``` 87 The current set of categories is: 88 ``` 89 ['Code', 'Bugs', 'Questions', 'Graphic Design', 'Social Media', 'Content Creation', 'Translations', 'Surveys'] 90 ``` 91 The data schema for the fulfillment data field is: 92 ``` 93 { 94 description: // A string representing the description of the fulfillment, and any necessary links to works 95 sourceFileName: // A string representing the name of the file being submitted 96 sourceFileHash: // A string representing the IPFS hash of the file being submitted 97 contact: // A string representing the preferred contact method of the fulfiller of the bounty 98 } 99 ``` 100 101 **If you're building on the StandardBounties and would like to add additional data fields, please submit a pull request on this repo.** 102 103 ## 4. Documentation 104 105 For thorough documentation of all functions, see [the documentation](./docs/documentation.md)