Add wiki docs to the repo

CONTRIBUTING.md

@@ -0,0 +1,28 @@
+This document describes process guidelines to be followed when contributing to Status Open Bounty repo.
+
+First, make sure to familiarize yourself with the [README](https://github.com/status-im/open-bounty/blob/develop/README.md) and [Testing](https://github.com/status-im/open-bounty/blob/develop/doc/testing.md) documents in order to setup the project properly.
+
+# Issues
+  - Issues should have type, priority and size (difficulty) assigned via corresponding labels
+  - Issue descriptions should include the following fields:
+    - **Summary**
+    - **Type**
+    - (*Features or enhancements only*) **User story**
+    - (*Bugs only*) **Expected behavior**
+    - (*Bugs only*) **Actual behavior**
+    - **Additional information**
+
+# Pull requests
+  - Branch names should include:
+    - prefixes indicating issue type (`bug`, `feature`, `doc`, `test`)
+    - short description in lisp-case
+    - and include associated issue number
+    
+    For instance, `bug/messy-problem-#1234`
+  - Start the title of the PR with [FIX #NNN], where #NNN is the issue number
+  - Always include `Status:` in the PR description to indicate whether PR is `WIP` or `Finished`.
+  - PR description should include the following sections:
+    - **Summary**
+    - **Notes**
+    - **Status**
+  - Merges into `develop` branch should be approved by at least 1 person, into `master` - by 2.

doc/deployment_flow.md

@@ -0,0 +1,16 @@
+# Deployment flow
+
+This briefly describes events that occur when an issue is labeled as bounty and a new contract has to be deployed.
+
+1. Issue is labeled
+2. Event is received via GitHub App webhook
+3. Contract is deployed
+4. GitHub issue comment "Deploying contract..." is posted
+5. `transaction_hash` is stored in the `issues` table
+
+The following items execute in scheduler threads that run each minute, so up to 60 sec delay can be expected.
+
+6. `update-issue-contract-address` scheduler thread fetches transaction receipt, updates `contract_address` and updates GitHub comment with a new image and current balance
+7. `deploy-pending-contracts` scheduler thread checks if there are issues that did not have corresponding contracts deployed and attempts to redeploy
+8. `update-balances` scheduler thread checks balances and updates GitHub comment accordingly
+9. `update-contract-internal-balances` scheduler threads updates internal ERC20 token balances for all deployed contracts. This is required by current contract code

doc/payout_flow.md

@@ -0,0 +1,57 @@
+# Payout flow
+
+This describes the sequence of events happening once a PR for an issue with a bounty was merged by repo maintainer.
+
+### Quick info on transaction hashes
+In the sequence described below, several types of hashes are used. SOB checks presence of different hashes on records in the `issues` table to decide which action to take on an issue and associated contract. These hashes are:
+- `transaction_hash`: set when contract is deployed to the labeled issue
+- `execute_hash`: set when PR for an issue with a bounty was merged
+- `confirm_hash`: fetched from receipt from transaction invoked in previous step
+- `payout_hash`: set when payout was confirmed via `Manage Payouts`
+
+The event flow is given below. For the bounty to be paid, each issue has to go through the steps in given order.
+
+### 1. PR closed and merged
+- app receives notification via GitHub App webhook (endpoint: `/webhook-app`)
+- `handle-claim` fn is invoked which will:
+- save PR in the `pull_requests` DB table, where state=1 for merged PRs
+- update issue in the DB with commit SHA, if PR was merged
+
+Afterwards two interleaving sequences of actions come into play: scheduler threads and manual user interaction in the `Manage Payouts` tab.
+
+### 2. `self-sign-bounty` scheduler thread
+- input query name: `pending-bounties`. This selects pending bounties (where `execute_hash` is nil and `commit_sha` is set)
+- execute payout transactions
+- store `execute_hash` and `winner_login` in `issues` DB table
+- update GitHub comment to "Pending maintainer confirmation"
+### 3. `update-confirm-hash` scheduler thread
+- input query name: `pending-payouts`. This selects bounties with `execute_hash` set and no `confirm_hash`
+- fetch `confirm_hash` from transaction receipt
+- store `confirm_hash` in `issues` DB table
+
+### 4. Manage Payouts view
+In order to confirm a payout, following conditions have to be met for an issue:
+- it is merged
+- not paid yet (meaning its `payout_hash` is nil)
+- not being confirmed at the moment (`:confirming?` flag is true)
+  OR
+- already confirmed by a scheduler thread(`confirm_hash` is not nil)
+
+Note that `confirm_hash` issue field and confirmation action in the UI are different things, albeit identically named. In order to confirm a payout from the UI, `confirm_hash` has to be already set by scheduler thread (see above).
+
+Payout confirmation action results in a `:confirm-payout` event. Its handler will
+- use `confirm_hash` to construct transaction payload
+- set `:confirming?` flag to `true`
+- execute `confirmTransaction()` call
+- pass transaction callback to `confirmTransaction()`. Once invoked, the callback will:
+  - get `payout_hash` passed as an argument
+  - dispatch `:save-payout-hash` event. Its handler will:
+    - POST to /api/user/bounty/%s/payout
+      - This will update `payout_hash` in `issues` DB table
+    - if POST is successful, dispatch `:payout-confirmed`
+      - `:payout-confirmed` will update  `:confirmed?` to `true` and remove `:confirming?` flag
+
+### 5. `update-payout-receipt` scheduler thread
+- input query name: `confirmed-payouts`. This selects confirmed payouts (the ones that have `payout_hash` and do not have `payout_receipt` set)
+- store `payout_receipt` in `issues` DB table
+- and update GitHub comment to "Paid to:..."

doc/sync_issues.md

@@ -0,0 +1,11 @@
+# Common sync issues
+
+- Repo rename. Related issue: https://github.com/status-im/open-bounty/issues/219.
+- Transaction callback not executed, hence payout-hash not set.
+- App downtime, multiple GitHub App deliveries failing. These can be afterwards replayed from GitHub App's Advanced tab.
+- Geth issue. Not solvable on app end, Geth restart usually fixes these.
+- Bot out of gas. Relevant issue: https://github.com/status-im/open-bounty/issues/195.
+- Sometimes repos are disabled in DB (state=0), probably only happens to repos that were added earlier through OAuth App.
+- PRs might end up in state=0 (opened) instead of state=1(merged), if PR did not have a proper text ("Fixes #..."). This one needs more investigation and more cases to reproduce.
+- Sometimes contract_address cannot be fetched for a long period of time.
+