GitBook: [master] 37 pages and 3 assets modified

Author: jrag0x

.gitbook/assets/image (1).png

@@ -0,0 +1,12 @@
+# Introduction to Kleros
+
+🚧**👷 IN PROGRESS 👷**🚧
+
+## What is Kleros?
+
+Kleros is a decentralized decision protocol for use on smart contract platforms, which has been implemented on Ethereum. 
+
+It acts as a decentralized third party capable of providing decisions on the correct result when applying a set of rules to questions ranging from simple to highly complex. 
+
+This is achieved by using game theoretic incentives to have crowdsourced jurors analyze and rule on cases correctly. Hence, Kleros provides judgments in an inexpensive, reliable, typically fast, and decentralized way. Of particular relevance is the use of this protocol to dispute resolution, creating a form of decentralized justice.
+

.gitbook/assets/image (2).png

@@ -0,0 +1,63 @@
+# Table of contents
+
+* [Introduction to Kleros](README.md)
+* [FAQ](faq.md)
+* [Decentralized Justice Glossary](decentralized-justice-glossary.md)
+* [Governance](governance.md)
+* [PNK Token](pnk-token.md)
+
+## Products
+
+* [Court](products/court.md)
+* [Escrow](products/escrow.md)
+* [Curate](products/curate.md)
+* [Oracle](products/oracle.md)
+* [Linguo](products/linguo.md)
+* [Proof of Humanity](products/proof-of-humanity.md)
+* [Governor](products/governor.md)
+* [T2CR \(Token Registry\)](products/t2cr-token-registry.md)
+
+## INTEGRATIONS
+
+* [Overview](integrations/overview.md)
+* [Use Cases](integrations/untitled.md)
+* [xDai](integrations/xdai.md)
+* [Current Integrations](integrations/current-integrations.md)
+
+## Developer
+
+* [ERC-792: Arbitration Standard](developer/erc-792-arbitration-standard.md)
+* [ERC 1497: Evidence Standard](developer/erc-1497-evidence-standard.md)
+* [Archon: Ethereum Arbitration Standard API](developer/archon-ethereum-arbitration-standard-api.md)
+
+## Contribution Guidelines
+
+* [Overview](contribution-guidelines/overview.md)
+* [General Dev. Workflow](contribution-guidelines/general-dev.-workflow/README.md)
+  * [Task Tracking & Lifecycle](contribution-guidelines/general-dev.-workflow/task-tracking-and-lifecycle.md)
+  * [Releases](contribution-guidelines/general-dev.-workflow/releases.md)
+* [Smart Contract Workflow](contribution-guidelines/smart-contract-workflow/README.md)
+  * [Task Tracking & Lifecycle](contribution-guidelines/smart-contract-workflow/task-tracking-and-lifecycle.md)
+  * [RAB - Review, Audit, Bounty](contribution-guidelines/smart-contract-workflow/rab.md)
+  * [RABd \(+ Deploy\)](contribution-guidelines/smart-contract-workflow/rabd.md)
+  * [Reporting Vulnerabilities](contribution-guidelines/smart-contract-workflow/reporting-vulnerabilities.md)
+* [Code Style and Guidelines](contribution-guidelines/code-style-and-guidelines/README.md)
+  * [Git](contribution-guidelines/code-style-and-guidelines/git.md)
+  * [Solidity](contribution-guidelines/code-style-and-guidelines/solidity.md)
+  * [Web Languages](contribution-guidelines/code-style-and-guidelines/web-languages.md)
+* [License & Code of Conduct](contribution-guidelines/license-and-code-of-conduct/README.md)
+  * [License](contribution-guidelines/license-and-code-of-conduct/license.md)
+  * [Code of Conduct](contribution-guidelines/license-and-code-of-conduct/code-of-conduct.md)
+
+## Additional Resources
+
+---
+
+* [Telegram](https://t.me/kleros)
+* [Reddit](https://reddit.com/r/Kleros/)
+* [Github](https://github.com/kleros)
+* [Slack](https://slack.kleros.io/)
+* [Twitter](https://twitter.com/kleros_io)
+* [Blog](https://blog.kleros.io/)
+* [Forum](https://forum.kleros.io/)
+

.gitbook/assets/image.png

@@ -0,0 +1,14 @@
+---
+description: Keep your code compliant to Kleros' standards.
+---
+
+# Code Style and Guidelines
+
+{% page-ref page="git.md" %}
+
+{% page-ref page="solidity.md" %}
+
+{% page-ref page="web-languages.md" %}
+
+
+

README.md

@@ -0,0 +1,82 @@
+---
+description: Controlling version control.
+---
+
+# Git
+
+We use Git for version control and use [Conventional Commits](https://www.conventionalcommits.org) for branch names and commit messages to enforce consistency and enjoy automatic changelog generation.
+
+## Branches
+
+Use short and descriptive, kebab-cased names with a conventional commits type prefix separated by a slash, like so:
+
+* `feat/implement-arbitrator`
+* `fix/invalid-rulings-from-arbitrator`
+
+When several people are working on a branch, you may create personal branches that can be merged before merging the main branch to `develop`. For example:
+
+* `feat/implement-arbitrator/alice`
+* `feat/implement-arbitrator/bob`
+
+{% hint style="info" %}
+Always delete merged branches, locally and remotely. You can use the following command to list them, `git branch --merged | grep -v "\*"`.
+{% endhint %}
+
+## Commits
+
+It's important for commits to follow a standard to allow efficient navigation of change history in the case of regressions and to make reviewers' lives easier.
+
+### When to Commit
+
+As a general guideline, each commit should be a single logical change. Don't make several logical changes in one commit. For example, if a commit fixes a bug and optimizes the performance of a feature, split it. Here are some useful tips:
+
+* Use `git add -p` to interactively stage specific portions of modified files.
+* Commit early and often. Small, self-contained commits are easier to understand and revert when something goes wrong.
+* Order commits logically.
+
+When working locally, it's OK if your branch history is not perfect, but that should be cleaned up before pushing upstream.
+
+### Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org). If the repo uses [Kathari](), you can just run `yarn run cz` and follow the prompts to craft a valid message.
+
+{% hint style="info" %}
+Note that all the words in a commit message are in **present tense** except for the first word in the footer, e.g. Closes, Fixes, etc.
+{% endhint %}
+
+## Merging
+
+{% hint style="danger" %}
+Branches that are used by CI/CD processes, like `develop` and `master` should never have their history rewritten.
+{% endhint %}
+
+Before merging:
+
+* [x] Make sure the branch you are merging is fresh by rebasing it into the target branch.
+* [x] Verify that all commits adhere to this guide, otherwise, fix them.
+* [x] Wait for all CI/CD processes to give the green light.
+
+{% hint style="info" %}
+Always alert other people who are working on a branch when you are about to rewrite its history.
+{% endhint %}
+
+## Misc. Tips
+
+{% hint style="danger" %}
+Test before you push. Do not push half-done work.
+{% endhint %}
+
+{% hint style="info" %}
+Use lightweight tags to bookmark commits for future reference.
+{% endhint %}
+
+{% hint style="success" %}
+Keep repos in good shape by performing maintenance tasks from time to time:
+
+* `git-gc`
+* `git-prune`
+* `git-fsck`
+{% endhint %}
+
+
+

SUMMARY.md

@@ -0,0 +1,77 @@
+---
+description: Our standards for smart contract code.
+---
+
+# Solidity
+
+## Style
+
+We follow the [Official Solidity Style Guide](https://solidity.readthedocs.io/en/develop/style-guide.html) and use [Kathari]() for linting.
+
+## Comments & Documentation
+
+### When to Comment
+
+Comments should be used for:
+
+* Documenting all functions using the [**Ethereum Natural Specification Format**](https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format) \(ENSF\).
+* Explaining all non-obvious parts of code. A smart contract **must work**, but must also **convince external reviewers that it works**.
+* Explaining **security choices**.
+
+#### Computational Complexity
+
+If a function is **not** `O(1)` , the first line of the `@dev` part of the ENSF comment should be followed by what the **big O** complexity is and a brief explanation. This is so that callers know what they are getting into in terms of gas consumption. It is common for some gas intensive functions to only be called from clients and not from other contracts.
+
+#### External Trust
+
+For functions that make an external call with enough gas for re-entry, not `send` or `transfer`, specify **"UN/TRUSTED."** at the end of the `@dev` part of the ENSF comment. This tells readers wether the external call receiver is trusted or not, i.e. the code it executes is controlled.
+
+{% hint style="danger" %}
+Note that specifying a **contract type** for a variable **does not guarantee** that it will reference a contract of that **type** as any address can be coerced into any contract, and vice-versa.
+{% endhint %}
+
+#### Work in Progress
+
+Mark unsecured functions or functions that are **not finished** yet with **"TODO."** at the end of the `@dev` part of the ENSF comment.
+
+## Good Practices
+
+### Code
+
+A lot of these apply to software in general.
+
+* Do **not** use **magic numbers** or values, define a constant or enum.
+* If you need **special testing functions** that expose functionality not intended for production, make a test contract **inheriting** from the original one, rather than adding the testing functions to the original contract.
+
+### Mindset
+
+Traditional back ends do most of the heavy lifting for the front end, because computation is cheap and faster than on the client. But, smart contract backends, **leave most of the heavy lifting for the front end**, because computation is expensive and slower than on the client. This is an inherent property of consensus based systems that involve lots of parties. Improvements will always be made, but it will also always be cheaper to execute code on the front end.
+
+{% hint style="info" %}
+Abstractions can be made to make front end developers' lives easier. Our [archon](https://github.com/kleros/archon) does just that for ERC 792 contracts.
+{% endhint %}
+
+This and the security risks of smart contracts that interact with other smart contracts with complex and stateful interdependencies requires that we take a unique approach and mindset when developing smart contracts. Here are some general guidelines:
+
+* If possible, i.e. does not lead to a significant increase in computation, externally called functions should follow this **3-step pattern**:
+
+  * Verify that the call is authorized. Modifiers can be used for this.
+  * Execute state changes.
+  * Interact with other accounts by making external calls other than `send` and `transfer`.
+
+  This protects the function from being re-entered through the external calls and having some effect running more times than was intended. Note that despite what the official documentation indicates, `send` and `transfer` are not to be counted as interactions as they do not give enough gas to make a callback or change contract state.
+
+* Be aware of **gas consumption**. Smart contracts differ to traditional software where you can "Get it correct the first time, fast the second.", being slow in a smart contract is being incorrect. Out of gas transactions fail and high TX fees can place a huge burden on users.
+* Be OK with **"doing 0"**. A function that sends 0 tokens, gives a penalty of 0%, and/or can't be called again unless 0 seconds pass is fine. Smart contracts should have the minimum amount of code possible and this ties into the next point.
+* Don't protect the user from himself. Client execution is almost free, but smart contract execution isn't, so **limit smart contracts to blocking malicious behavior** and **let clients prevent the stupid ones**.
+* As a general rule, your priorities should be in this order:
+  * **Security**: Prevent vulnerabilities, unexpected behaviour, and reduce the impact of those which could arise.
+  * **Gas**: Lower the gas usage to save on TX fees.
+  * **Convincibility**: Write code that allows other parties to be easily convinced that it works. Remember that more time is spent in reviews/audits/bug bounties than in actually writing the code.
+  * **Reusability**: Write code that is generic enough to avoid starting from scratch every time. This should not hinder the 3 previous priorities.
+* Do not **over-engineer**. Over-engineering lowers security, increases gas costs, and decreases convincibility. [Kiss](https://en.wikipedia.org/wiki/KISS_principle) ♥.
+* Smart contracts should only do what is **required, no more, no less**. Do not abstract contracts into more generic contracts if the deployed version will only use a subset of the functionality. E.g. if you can only have 2 parties in your contract, only write code for 2 parties. Do not write code supporting an arbitrary number of parties and then set it to 2 at deployment. This is a stark contrast to traditional software where generic abstractions can save time in the long run. In smart contract development, there is no continuous deployments and the additional time spent in security practices that a generic contract requires far outweighs the potential benefit of its reusability.
+* However, **abstraction** can be useful when contracts need to interact with contracts which are **not known in advance**, either because they won't be finished by the time of deployment or because they will be developed by other projects you don't have control over. [**ERC20**](https://github.com/ethereum/EIPs/issues/20) and [**ERC792**](https://github.com/ethereum/EIPs/issues/792) are good examples of this.
+
+
+

contribution-guidelines/code-style-and-guidelines/README.md

@@ -0,0 +1,16 @@
+---
+description: How we handle the ever changing suite of tools and frameworks.
+---
+
+# Web Languages
+
+## Long Live the Web
+
+We are huge fans of the Web and Javascript community and regularly follow thought leaders, specially from the React team, to keep up to date with the latest best practices. However, we engineer for users, not other engineers, so we try to remain as pragmatic as possible.
+
+That said, I think we still do pretty well with staying up to date, although I'm not sure for how long after this last ReactConf :\).
+
+## Our Approach
+
+There is no point in listing out a bunch of frameworks and linters here. In general, we follow the **"pick the best tool for the job philosophy"**. Check out [Kathari]() and [one of our dapps](https://github.com/kleros/doges-on-trial) to get a sense of what we think that is at the moment.
+

contribution-guidelines/code-style-and-guidelines/git.md

@@ -0,0 +1,12 @@
+---
+description: How we keep track of new development work and push new code.
+---
+
+# General Dev. Workflow
+
+
+
+{% page-ref page="task-tracking-and-lifecycle.md" %}
+
+{% page-ref page="releases.md" %}
+

contribution-guidelines/code-style-and-guidelines/solidity.md

@@ -0,0 +1,26 @@
+---
+description: 'How we push new code to staging, production, and beyond.'
+---
+
+# Releases
+
+## Branch Deploys
+
+In an effort to keep everything as automated as possible, we have two main protected branches that get automatically deployed in most of our projects:
+
+| `develop` | `master` |
+| :--- | :--- |
+| Deploys to a staging environment. | Deploys to a production environment. |
+
+{% hint style="info" %}
+Pull requests also get deploy previews when applicable.
+{% endhint %}
+
+## Version Bumps & Releasing
+
+When a task is finished, it gets merged to `develop`. When `develop` is tested and ready to become a production release, the following process takes place:
+
+1. We run [standard-version](https://github.com/conventional-changelog/standard-version) on `develop` and take advantage of our [Git](../code-style-and-guidelines/git.md) style conventions to automatically create or update a changelog and bump the version number following [semver](https://semver.org) guidelines.
+2. We push and submit a pull request  to `master`.
+3. We conduct one final review before merging and letting CI/CD take care of the rest.
+

contribution-guidelines/code-style-and-guidelines/web-languages.md

@@ -0,0 +1,69 @@
+---
+description: Our methodology for keeping track of development work.
+---
+
+# Task Tracking & Lifecycle
+
+## All in Github
+
+{% hint style="info" %}
+See [Git Code Style & Guidelines](../code-style-and-guidelines/git.md) for our message and branch names style and guidelines.
+{% endhint %}
+
+We try to keep the number of tools we use to a minimum for simplicity and ease of on-boarding. The new features of Github make it possible to keep most of the project management next to the code, and this is our approach:
+
+| Issues | Projects | Milestones |
+| :--- | :--- | :--- |
+| Reference a specific task and keep track of its status. | Reference a long term project or goal. | Are used to group issues into time-controlled sprints. |
+
+## Labels for Days
+
+We also have a very comprehensive set of labels that can be automatically added to a repo using [Kathari](). It's important that all issues and pull requests have a priority, status, and type, and that they keep track of who is working and who is reviewing, if anyone.
+
+### **Optional**
+
+* duplicate 2️⃣ - Is a duplicate.
+* starter 🍼 - Good for new contributors.
+
+### **Priority**
+
+* **Critical 🔥** - Mission critical.
+* **High** - Top of to-do list.
+* **Low** - Bottom of to-do list.
+* **Medium** - Somewhere in the middle of to-do list.
+
+### Status
+
+* **Abandoned** - The assigned contributor gave up.
+* **Available** - Open for anyone to work on.
+* **Blocked** - Blocked by another issue.
+* **In Progress** - Someone is already working on it.
+* **On Hold** - Purposely paused.
+* **Proposal** - Don't work on it until accepted.
+* **Review Needed** - Pending reviews.
+
+### Type
+
+* **Bug 🐛** - Bugs.
+* **Documentation 📚** - Documentation work.
+* **Enhancement ✨** - Enhancements.
+* **Maintenance 🚧** - Chores.
+* **Question ❔ -** Queries about the project.
+
+## Lifecycle
+
+The lifecycle of a task goes like this:
+
+{% hint style="info" %}
+We don't have a complicated issue or pull request template, we just ask for common sense and for all necessary information.
+{% endhint %}
+
+1. An issue is raised with the description of what needs to be done.
+2. Discussion takes place and someone is assigned to the issue.
+3. The issue is added to a project and/or milestone, if applicable.
+4. The assignee branches off `develop` to work and submits a pull request when ready.
+5. Our CI/CD process lints, formats, and tests the code.
+6. The pull request is merged after all the changes are reviewed and accepted, and any requested changes are made.
+
+
+

contribution-guidelines/general-dev.-workflow/README.md

@@ -0,0 +1,12 @@
+---
+description: 'Kleros is open-sourced, MIT licensed and a civilized collaboration space.'
+---
+
+# License & Code of Conduct
+
+{% page-ref page="license.md" %}
+
+{% page-ref page="code-of-conduct.md" %}
+
+
+