diff --git a/.gitbook/assets/broken-icosahedron.png b/.gitbook/assets/broken-icosahedron.png new file mode 100644 index 0000000..b34643c Binary files /dev/null and b/.gitbook/assets/broken-icosahedron.png differ diff --git a/SUMMARY.md b/SUMMARY.md index 6f231bd..6fa107e 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -66,7 +66,8 @@ ## Developers -* [Arbitration Development](developer/arbitration-development/README.md) +* [Deployment Addresses](developer/deployment-addresses.md) +* [Arbitration Standard](developer/arbitration-development/README.md) * [ERC-792: Arbitration Standard](developer/arbitration-development/erc-792-arbitration-standard.md) * [ERC 1497: Evidence Standard](developer/arbitration-development/erc-1497-evidence-standard.md) * [Arbitration by Example](developer/arbitration-by-example/README.md) @@ -76,32 +77,36 @@ * [ArbitrableTransaction.sol](developer/arbitration-by-example/arbitrabletransaction.sol.md) * [MultipleArbitrableTransaction.sol](developer/arbitration-by-example/multiplearbitrabletransaction.sol.md) * [MultipleArbitrableTokenTransaction.sol](developer/arbitration-by-example/multiplearbitrabletokentransaction.sol.md) -* [Archon: Ethereum Arbitration Standard Interaction Library](developer/archon-ethereum-arbitration-standard-api.md) -* [Deployment Addresses](developer/deployment-addresses.md) -* [Curate Classic: Integration for Devs](developer/classic.md) -* [Light Curate: Integration for Devs](developer/light-curate.md) -* [Guide for Preparing Transactions](developer/guide-for-preparing-transactions.md) - -## Contribution Guidelines +* [Archon: Arbitration SDK](developer/archon-ethereum-arbitration-standard-api.md) +* Product Integration for Devs + * [Curate Classic Integration](developer/classic.md) + * [Light Curate Integration](developer/light-curate.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) -* [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) +## PRODUCT & TECH SUPPORT +* [Support Playbook](support/support-playbook.md) +* [Support FAQ](support/support-faq.md) +* Technical Guides + * [Proposing Transactions to the Governance](support/guide-for-preparing-transactions.md) + * [Drawing Jurors Manually](support/guide-manual-jurors-drawing.md) -## Additional Resources +## Resources * [Discord](https://discord.gg/cAvWk8B23f) * [Telegram](https://t.me/kleros) diff --git a/contribution-guidelines/smart-contract-workflow/reporting-vulnerabilities.md b/contribution-guidelines/smart-contract-workflow/reporting-vulnerabilities.md index 01d71ee..1e1c137 100644 --- a/contribution-guidelines/smart-contract-workflow/reporting-vulnerabilities.md +++ b/contribution-guidelines/smart-contract-workflow/reporting-vulnerabilities.md @@ -8,3 +8,5 @@ description: When you find something wrong with a contract. You can privately disclose vulnerabilities to us at any time, by sending an email to clement@kleros.io and contact@kleros.io. We can then discuss the best way to handle things on a case by case basis. +**🚧 TODO/FIXME: switch to security@kleros.io?** + diff --git a/developer/guide-for-preparing-transactions.md b/support/guide-for-preparing-transactions.md similarity index 100% rename from developer/guide-for-preparing-transactions.md rename to support/guide-for-preparing-transactions.md diff --git a/support/guide-manual-jurors-drawing.md b/support/guide-manual-jurors-drawing.md new file mode 100644 index 0000000..d57694b --- /dev/null +++ b/support/guide-manual-jurors-drawing.md @@ -0,0 +1,29 @@ + +# Guide for Drawing Jurors Manually + +`KlerosLiquid` draws jurors randomly. Anyone could do this task, even the users. The Kleros Cooperative runs the [following bot](https://github.com/kleros/action-callback-bots/) to take care of it automatically. + +Sometimes the bots break because of... +* RPC service degradation, +* Transactions getting stuck, +* Not enough gas in bot wallets, +* Programming errors. + +The users are not expected to worry about this upkeep, but anyone willing to pay for gas may draw the jurors manually. Although there is no frontend functionality to draw the jurors, it can be done by calling the contracts directly. + +## Procedure + +It is useful to know [KlerosLiquid uses three phases](https://github.com/kleros/kleros/blob/master/contracts/kleros/KlerosLiquid.sol#L390) to obtain randomness in a safe way: +* Phase 0: `staking` +* Phase 1: `generating` +* Phase 2: `drawing` + +Steps: +1. In order to draw the jurors, you need to be in Drawing phase (`phase == 2`). to do so, just call `passPhase` when able. you can use block explorer tools such as etherscan or blockscout. (on gnosis chain, these functions are called through "Write Proxy"). +2. Look for disputes that are still missing jurors to draw, for example on the [KlerosBoard](https://klerosboard.com/#/100/cases). +3. Call `drawJurors` , you will pass the id of the dispute, and in `_iterations` the number of needed jurors. + +## Resources + +* Ethereum Mainnet KlerosLiquid [https://etherscan.io/address/0x988b3a538b618c7a603e1c11ab82cd16dbe28069](https://etherscan.io/address/0x988b3a538b618c7a603e1c11ab82cd16dbe28069) +* Gnosis Chain KlerosLiquid [https://blockscout.com/xdai/mainnet/address/0x9C1dA9A04925bDfDedf0f6421bC7EEa8305F9002](https://blockscout.com/xdai/mainnet/address/0x9C1dA9A04925bDfDedf0f6421bC7EEa8305F9002) \ No newline at end of file diff --git a/support/support-faq.md b/support/support-faq.md new file mode 100644 index 0000000..81c7b6c --- /dev/null +++ b/support/support-faq.md @@ -0,0 +1,3 @@ +# Support FAQ + +**🚧 In Progress 🚧** \ No newline at end of file diff --git a/support/support-playbook.md b/support/support-playbook.md new file mode 100644 index 0000000..372c5cd --- /dev/null +++ b/support/support-playbook.md @@ -0,0 +1,138 @@ +# Support Playbook +**🚧 In Progress 🚧** + +## 👉 Start Here +This document is for *things that look broken* somewhere in the Kleros product ecosystem. + +
+ +
+ +If you’re pretty sure you’ve found something that’s broken, please ask yourself... + +### 🔔🗯 **Is this a *major* issue that needs to be resolved in 24 hours or less?** +If so, follow the steps in the [Major Issues section below](#major-issues). + +Examples: +* Any **downtime in vital fonctions** of the application. +* Any 🛡**security issue** that cannot wait another minute. +* An issue putting the **Kleros reputation** at major risk. + + +### 🔕💬 **Is this something that can be addressed on a longer timeline?** +If so, follow the steps in the [Everything Else section below](#everything-else). + + +## 🚨 Major Issues + +### 🛡 Security Issues +Please refer to the [Security Disclosure page](../contribution-guidelines/smart-contract-workflow/reporting-vulnerabilities.md). + +### 🧯 Non-Security Issues + +If you have found a major issue that needs to be resolved in **24 hours or less** (this should be rare), please: + +1. Go to the [TODO] channel in the ***Product Support*** section/thread etc +2. Create a message with the following information: + * Where you found the issue, + * Description of the behavior, step-by-step instructions on how to recreate the issue, + * User account information for any known impacted accounts, + * Screenshots (if relevant), + * Relevant device info (mobile/desktop, browser, etc). +3. Someone from the Team will respond to you ASAP to let you know that the issue has been seen. The Team member will pull in the relevant team members to begin working on the problem and provide updates in [TODO: public issue tracker?]. + +## 🐛 Everything Else + +If you have found an issue that does not need to be resolved immediately (this should be most things), please: + +1. Go to the [TODO] channel in the ***Product Support*** section/thread for the product/protocol for which you need help: + * Integrations & Developers + * Court + * Proof of Humanity + * ... +2. Create a short descriptive title for the issue with the following information: + * Where you found the issue, + * Description of the behavior, step-by-step instructions on how to recreate the issue, + * User account information for any known impacted accounts, + * Screenshots (if relevant), + * Relevant device info (mobile/desktop, browser, etc). +5) The Product Owner will acknowledge seeing your tag within the next business day and add the issue to the backlog. They may ask follow-up questions as part of this process. Once in the backlog, the issue will be prioritized accordingly and the Product Owner will provide updates as appropriate. + +## 🚑 Support Service Levels + +Support is provided by resources made available by the **Kleros Cooperative**. + +### 👨‍⚕️ Playbook & Expectations +**🚧 In Progress 🚧** + +| Playbook | 🚨 Emergencies | 🐛 Everything Else | +| --- | --- | --- | +| **Support channel** | [TODO]
`#emergency-support` | [TODO]
`#dev-support`
`#[product]-support` | +| **Monitored by** | Product Owner
AND
Engineers On-Call | Product Owner | +| **Triage and Prioritization** | Whoever sees the issue first begins work immediately | Wait for prioritization by Product Owner | +| **First response time** | ASAP | Within 1 business day | +| **Expectations** | Issue is worked on until resolved, even outside of normal business hours | Issue is *not* worked on outside of normal business hours unless indicated otherwise +| **Escalation after** | 1 Hour | 5 days if stagnant | +| **Escalation channel** | Tag the `@TODO` team| Tag `@[Product]Owner` | + +### 🌡 Useful Metrics +These metrics may be observed over different time periods (daily, weekly, monthly, quarterly, yearly). + +* Satisfaction +* Average Issue Count +* Ticket Backlog +* First Response Time +* First Response Resolution Rate (for example a response pointing to a * solution documented in the [Support FAQ](./support-faq.md)). +* Average Response Time +* Number of Interactions per Issue +* Average Ticket Resolution Issue +* Issue Resolution Rate + +For [more information on these metrics](https://blog.hubspot.com/service/customer-experience-metrics). + +## 🧗‍♀️ Escalation Contacts + +* Security Team: [Reporting Page](../contribution-guidelines/smart-contract-workflow/reporting-vulnerabilities.md) +* Developer Relations: Emmett (@TG) +* Product Owners + * Court v1: [TODO (@TG)] + * Court v2: [TODO (@TG)] + * Curate: [TODO (@TG)] + * Tokens: [TODO (@TG)] + * Reality oracle: [TODO (@TG)] + * Proof of Humanity v1: [TODO (@TG)] + * Proof of Humanity v2: [TODO (@TG)] + * Governor and Zodiac Reality: [TODO (@TG)] + * Moderate: [TODO (@TG)] + * Vea bridge: [TODO (@TG)] + * Escrow: [TODO (@TG)] + * Linguo: [TODO (@TG)] + * Dispute Resolver: [TODO (@TG)] + +## 🌿 Ticket Lifecyle + +### 📝 From Issue Report to Ticket Creation + +The relevant Team members are responsible for monitoring the issues reported in the Support communication channels/threads below according to the severity of the issue. As a general rule, *a ticket is created to track the issue*, it is then triaged and prioritized before being picked up a team member. This process is fast-tracked for emergencies. + +### 🤝 Resolution + +Once a ticket has been assigned or self-assigned, the assigned engineer is responsible for further ticket hygiene including: +* Keeping the ticket status up to date (In Progress, PR review, etc) +* Attaching relevant PRs. +* Staying focused on the ticket and completing in high priority. + +If the assigned engineer does not finish their ticket before [TODO: rotating schedule for support duties?], they will either: +* Notify the Product Owner that they will stay with the ticket through completion, OR +* Document their notes and hand-off to the next on-call engineer. + +### 🚦 Status Tracking +[TODO: public issue tracker?] + +The following status markers are used: +* 🔴 Issue has been received & is being triaged +* ⭕️ Issue is on-going & being worked on +* 🟡 A fix has been provided for the issue and is awaiting confirmation/deployment +* 🟢 Issue is resolved + +